@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/02-CORE-GUIDES/api-reference/modules/api-reference-08-pagination.md

@@ -1,513 +1,513 @@
-# Module 08: Pagination
-
-**Level:** Intermediate
-**Category:** GraphQL Query Patterns
-
-## Overview
-
-Cursor-based pagination is essential for efficiently querying large datasets from Fluent Commerce GraphQL API. This module covers auto-pagination configuration, cursor handling, pageInfo management, and best practices for processing millions of records without memory exhaustion or timeouts.
-
-## Table of Contents
-
-- [Why Pagination](#why-pagination)
-- [Relay Connection Specification](#relay-connection-specification)
-- [Auto-Pagination Configuration](#auto-pagination-configuration)
-- [Manual Pagination](#manual-pagination)
-- [Cursor Handling](#cursor-handling)
-- [pageInfo Management](#pageinfo-management)
-- [Performance Considerations](#performance-considerations)
-- [Best Practices](#best-practices)
-- [Common Patterns](#common-patterns)
-- [Troubleshooting](#troubleshooting)
-- [See Also](#see-also)
-
----
-
-## Why Pagination
-
-Fluent Commerce APIs can return millions of records. Without pagination:
-
-| Problem | Impact |
-|---------|--------|
-| API Timeouts | Requests fail after 30-60 seconds |
-| Memory Exhaustion | Node.js/Deno runs out of memory |
-| Slow Responses | Minutes to return data |
-| Network Overhead | Multi-MB responses block network |
-
-**With Pagination:**
-- Fast response times (<1 second per page)
-- Memory efficient (process chunks)
-- Fault tolerant (resume from cursor)
-- Rate limit friendly
-
----
-
-## Relay Connection Specification
-
-Fluent Commerce implements the Relay Connection Specification:
-
-```graphql
-type Query {
-  inventoryPositions(first: Int, after: String): InventoryPositionConnection
-}
-
-type InventoryPositionConnection {
-  edges: [InventoryPositionEdge!]!
-  pageInfo: PageInfo!
-}
-
-type InventoryPositionEdge {
-  node: InventoryPosition!
-  cursor: String!
-}
-
-type PageInfo {
-  hasNextPage: Boolean!
-  hasPreviousPage: Boolean!
-  startCursor: String
-  endCursor: String
-}
-```
-
-**Key Concepts:**
-- **edges**: Array of edge objects (each contains node + cursor)
-- **node**: The actual data record
-- **cursor**: Opaque string for resuming pagination
-- **pageInfo**: Metadata about pagination state
-
----
-
-## Auto-Pagination Configuration
-
-The SDK provides automatic pagination via `FluentClient.graphql()`:
-
-```typescript
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-const client = await createClient({ config });
-
-// Auto-paginate through all results
-const results = await client.graphql({
-  query: `
-    query GetPositions($first: Int, $after: String) {
-      inventoryPositions(first: $first, after: $after) {
-        edges {
-          node {
-            id
-            ref
-            onHand
-            productRef
-            locationRef
-          }
-        }
-        pageInfo {
-          hasNextPage
-          endCursor
-        }
-      }
-    }
-  `,
-  pagination: {
-    pageSize: 100,        // Records per page (default: 100)
-    maxPages: 50,         // Stop after N pages (default: Infinity)
-    delayMs: 100         // Delay between pages (default: 0)
-  }
-});
-
-// Results automatically combined from all pages
-console.log(`Fetched ${results.data.inventoryPositions.edges.length} positions`);
-```
-
-**Configuration Options:**
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `pageSize` | number | 100 | Number of records per page (max 250) |
-| `maxPages` | number | Infinity | Stop after N pages |
-| `delayMs` | number | 0 | Milliseconds to wait between pages |
-
----
-
-## Manual Pagination
-
-For more control, implement pagination manually:
-
-```typescript
-async function* paginateResults(client, query, variables = {}) {
-  let hasNextPage = true;
-  let cursor = null;
-
-  while (hasNextPage) {
-    const result = await client.graphql({
-      query,
-      variables: {
-        ...variables,
-        first: 100,
-        after: cursor
-      }
-    });
-
-    const connection = result.data.inventoryPositions;
-
-    // Yield current page
-    yield connection.edges.map(e => e.node);
-
-    // Update pagination state
-    hasNextPage = connection.pageInfo.hasNextPage;
-    cursor = connection.pageInfo.endCursor;
-  }
-}
-
-// Usage: Process one page at a time
-for await (const page of paginateResults(client, query)) {
-  console.log(`Processing ${page.length} records`);
-  // Process records in chunks
-}
-```
-
-**Benefits of Manual Pagination:**
-- Process each page before fetching next
-- Lower memory footprint
-- Can pause/resume between pages
-- Better error handling per page
-
----
-
-## Cursor Handling
-
-**Cursor Characteristics:**
-- Opaque strings (do not parse)
-- Base64-encoded (implementation detail)
-- Connection-specific (don't reuse across queries)
-- Stable (same cursor returns same position)
-
-```typescript
-// ✅ CORRECT: Use cursors as-is
-let cursor = pageInfo.endCursor;
-await client.graphql({
-  query,
-  variables: { first: 100, after: cursor }
-});
-
-// ❌ WRONG: Don't parse or manipulate
-const decoded = Buffer.from(cursor, 'base64').toString();  // Don't do this!
-cursor = cursor.substring(0, 10);  // Don't truncate!
-```
-
-**Cursor Storage:**
-
-```typescript
-// Save cursor for resumability
-const stateService = new StateService(kvAdapter);
-
-let cursor = await stateService.get('last_cursor');
-while (hasNextPage) {
-  const result = await client.graphql({
-    query,
-    variables: { first: 100, after: cursor }
-  });
-
-  // Process page...
-
-  cursor = result.data.inventoryPositions.pageInfo.endCursor;
-  await stateService.set('last_cursor', cursor);  // Checkpoint
-}
-```
-
----
-
-## pageInfo Management
-
-The `pageInfo` object controls pagination flow:
-
-```typescript
-interface PageInfo {
-  hasNextPage: boolean;      // More pages available?
-  hasPreviousPage: boolean;  // Can paginate backwards?
-  startCursor: string | null;  // First cursor in page
-  endCursor: string | null;    // Last cursor in page
-}
-```
-
-**Forward Pagination:**
-```typescript
-// Use endCursor + hasNextPage
-while (pageInfo.hasNextPage) {
-  const result = await client.graphql({
-    query,
-    variables: { first: 100, after: pageInfo.endCursor }
-  });
-  pageInfo = result.data.connection.pageInfo;
-}
-```
-
-**Backward Pagination:**
-```typescript
-// Use startCursor + hasPreviousPage
-while (pageInfo.hasPreviousPage) {
-  const result = await client.graphql({
-    query,
-    variables: { last: 100, before: pageInfo.startCursor }
-  });
-  pageInfo = result.data.connection.pageInfo;
-}
-```
-
----
-
-## Performance Considerations
-
-### Page Size Selection
-
-| Page Size | Use Case | Pros | Cons |
-|-----------|----------|------|------|
-| 25-50 | Real-time UI | Fast response | Many requests |
-| 100 | Balanced (default) | Good throughput | Moderate memory |
-| 250 | Batch processing | Fewer requests | Higher memory |
-
-```typescript
-// Small pages for UI responsiveness
-const results = await client.graphql({
-  query,
-  pagination: { pageSize: 25 }  // Fast initial render
-});
-
-// Large pages for bulk ETL
-const results = await client.graphql({
-  query,
-  pagination: { pageSize: 250, delayMs: 500 }  // Respect rate limits
-});
-```
-
-### Rate Limiting
-
-Add delays between pages to avoid rate limits:
-
-```typescript
-const results = await client.graphql({
-  query,
-  pagination: {
-    pageSize: 250,
-    delayMs: 500  // 500ms delay between pages
-  }
-});
-```
-
-### Memory Management
-
-Process pages individually for large datasets:
-
-```typescript
-async function processLargeDataset(client, query) {
-  for await (const page of paginateResults(client, query)) {
-    // Process and discard each page
-    await processBatch(page);
-    // page is garbage collected after iteration
-  }
-}
-```
-
----
-
-## Best Practices
-
-### 1. Always Include pageInfo
-
-```typescript
-// ✅ CORRECT: Include pageInfo
-query GetPositions($first: Int, $after: String) {
-  inventoryPositions(first: $first, after: $after) {
-    edges { node { id ref } }
-    pageInfo { hasNextPage endCursor }  # Required!
-  }
-}
-
-// ❌ WRONG: Missing pageInfo
-query GetPositions {
-  inventoryPositions {
-    edges { node { id ref } }
-    # Can't paginate without pageInfo!
-  }
-}
-```
-
-### 2. Use Variables for Pagination
-
-```typescript
-// ✅ CORRECT: Parameterized pagination
-query GetPositions($first: Int, $after: String) {
-  inventoryPositions(first: $first, after: $after) { ... }
-}
-
-// ❌ WRONG: Hardcoded values
-query GetPositions {
-  inventoryPositions(first: 100, after: "xyz") { ... }
-}
-```
-
-### 3. Handle Empty Pages
-
-```typescript
-const result = await client.graphql({ query, variables });
-
-if (result.data.inventoryPositions.edges.length === 0) {
-  console.log('No results found');
-  return;
-}
-
-// Process results...
-```
-
-### 4. Implement Timeouts
-
-```typescript
-const TIMEOUT_MS = 30000;  // 30 seconds
-
-const controller = new AbortController();
-const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS);
-
-try {
-  const result = await client.graphql({
-    query,
-    variables,
-    signal: controller.signal
-  });
-} finally {
-  clearTimeout(timeout);
-}
-```
-
----
-
-## Common Patterns
-
-### Pattern 1: Full Dataset Export
-
-```typescript
-async function exportAllPositions(client) {
-  const allRecords = [];
-
-  for await (const page of paginateResults(client, query)) {
-    allRecords.push(...page);
-  }
-
-  return allRecords;
-}
-```
-
-### Pattern 2: Streaming to File
-
-```typescript
-import { createWriteStream } from 'fs';
-
-async function streamToCSV(client, outputPath) {
-  const writer = createWriteStream(outputPath);
-  writer.write('ref,onHand,productRef,locationRef\n');
-
-  for await (const page of paginateResults(client, query)) {
-    for (const record of page) {
-      writer.write(`${record.ref},${record.onHand},${record.productRef},${record.locationRef}\n`);
-    }
-  }
-
-  writer.end();
-}
-```
-
-### Pattern 3: Progress Tracking
-
-```typescript
-async function fetchWithProgress(client, query) {
-  let totalFetched = 0;
-  let pageNum = 0;
-
-  for await (const page of paginateResults(client, query)) {
-    totalFetched += page.length;
-    pageNum++;
-    console.log(`Page ${pageNum}: ${totalFetched} records fetched`);
-  }
-
-  return totalFetched;
-}
-```
-
----
-
-## Troubleshooting
-
-### Issue 1: Pagination Never Stops
-
-**Symptom:** Loop runs forever despite data being exhausted
-
-**Cause:** Not checking `hasNextPage`
-
-**Solution:**
-```typescript
-// ✅ Check hasNextPage
-while (pageInfo.hasNextPage) {
-  // Fetch next page...
-}
-```
-
-### Issue 2: Duplicate Records
-
-**Symptom:** Same records appear multiple times
-
-**Cause:** Not using cursor correctly
-
-**Solution:**
-```typescript
-// ✅ Always pass endCursor from previous page
-cursor = result.data.connection.pageInfo.endCursor;
-```
-
-### Issue 3: Missing Records
-
-**Symptom:** Some records not fetched
-
-**Cause:** Starting with wrong cursor
-
-**Solution:**
-```typescript
-// ✅ Start with null cursor
-let cursor = null;  // Start from beginning
-```
-
-### Issue 4: Memory Leak
-
-**Symptom:** Memory usage grows indefinitely
-
-**Cause:** Accumulating all pages in memory
-
-**Solution:**
-```typescript
-// ✅ Process pages individually
-for await (const page of paginateResults(client, query)) {
-  await processBatch(page);
-  // page is discarded after iteration
-}
-```
-
----
-
-## See Also
-
-**Related Modules:**
-- [Module 01: Client API](./api-reference-01-client-api.md) - FluentClient GraphQL methods
-- [Module 05: Services](./api-reference-05-services.md) - ExtractionOrchestrator with auto-pagination
-- [Auto-Pagination Guide](../../auto-pagination/modules/auto-pagination-01-foundations.md) - Deep dive into pagination
-
-**Complete Guides:**
-- [Auto-Pagination Module Series](../../auto-pagination/modules/readme.md) - 7-module learning path
-- [Extraction Guide](../../extraction/extraction-readme.md) - Large dataset exports
-- [GraphQL Best Practices](../../00-START-HERE/getting-started.md#graphql-queries)
-
-**Templates:**
-- [GraphQL Extraction Templates](../../../01-TEMPLATES/versori/workflows/extraction/graphql-queries/) - Production examples
-
----
-
-**Navigation:**
-- [Back to Module List](./readme.md)
-- [Previous: Module 07 - Parsers](./api-reference-07-parsers.md)
-- [Next: Module 09 - Webhook Validation](./api-reference-09-webhook-validation.md)
+# Module 08: Pagination
+
+**Level:** Intermediate
+**Category:** GraphQL Query Patterns
+
+## Overview
+
+Cursor-based pagination is essential for efficiently querying large datasets from Fluent Commerce GraphQL API. This module covers auto-pagination configuration, cursor handling, pageInfo management, and best practices for processing millions of records without memory exhaustion or timeouts.
+
+## Table of Contents
+
+- [Why Pagination](#why-pagination)
+- [Relay Connection Specification](#relay-connection-specification)
+- [Auto-Pagination Configuration](#auto-pagination-configuration)
+- [Manual Pagination](#manual-pagination)
+- [Cursor Handling](#cursor-handling)
+- [pageInfo Management](#pageinfo-management)
+- [Performance Considerations](#performance-considerations)
+- [Best Practices](#best-practices)
+- [Common Patterns](#common-patterns)
+- [Troubleshooting](#troubleshooting)
+- [See Also](#see-also)
+
+---
+
+## Why Pagination
+
+Fluent Commerce APIs can return millions of records. Without pagination:
+
+| Problem | Impact |
+|---------|--------|
+| API Timeouts | Requests fail after 30-60 seconds |
+| Memory Exhaustion | Node.js/Deno runs out of memory |
+| Slow Responses | Minutes to return data |
+| Network Overhead | Multi-MB responses block network |
+
+**With Pagination:**
+- Fast response times (<1 second per page)
+- Memory efficient (process chunks)
+- Fault tolerant (resume from cursor)
+- Rate limit friendly
+
+---
+
+## Relay Connection Specification
+
+Fluent Commerce implements the Relay Connection Specification:
+
+```graphql
+type Query {
+  inventoryPositions(first: Int, after: String): InventoryPositionConnection
+}
+
+type InventoryPositionConnection {
+  edges: [InventoryPositionEdge!]!
+  pageInfo: PageInfo!
+}
+
+type InventoryPositionEdge {
+  node: InventoryPosition!
+  cursor: String!
+}
+
+type PageInfo {
+  hasNextPage: Boolean!
+  hasPreviousPage: Boolean!
+  startCursor: String
+  endCursor: String
+}
+```
+
+**Key Concepts:**
+- **edges**: Array of edge objects (each contains node + cursor)
+- **node**: The actual data record
+- **cursor**: Opaque string for resuming pagination
+- **pageInfo**: Metadata about pagination state
+
+---
+
+## Auto-Pagination Configuration
+
+The SDK provides automatic pagination via `FluentClient.graphql()`:
+
+```typescript
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+const client = await createClient({ config });
+
+// Auto-paginate through all results
+const results = await client.graphql({
+  query: `
+    query GetPositions($first: Int, $after: String) {
+      inventoryPositions(first: $first, after: $after) {
+        edges {
+          node {
+            id
+            ref
+            onHand
+            productRef
+            locationRef
+          }
+        }
+        pageInfo {
+          hasNextPage
+          endCursor
+        }
+      }
+    }
+  `,
+  pagination: {
+    pageSize: 100,        // Records per page (default: 100)
+    maxPages: 50,         // Stop after N pages (default: Infinity)
+    delayMs: 100         // Delay between pages (default: 0)
+  }
+});
+
+// Results automatically combined from all pages
+console.log(`Fetched ${results.data.inventoryPositions.edges.length} positions`);
+```
+
+**Configuration Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `pageSize` | number | 100 | Number of records per page (max 250) |
+| `maxPages` | number | Infinity | Stop after N pages |
+| `delayMs` | number | 0 | Milliseconds to wait between pages |
+
+---
+
+## Manual Pagination
+
+For more control, implement pagination manually:
+
+```typescript
+async function* paginateResults(client, query, variables = {}) {
+  let hasNextPage = true;
+  let cursor = null;
+
+  while (hasNextPage) {
+    const result = await client.graphql({
+      query,
+      variables: {
+        ...variables,
+        first: 100,
+        after: cursor
+      }
+    });
+
+    const connection = result.data.inventoryPositions;
+
+    // Yield current page
+    yield connection.edges.map(e => e.node);
+
+    // Update pagination state
+    hasNextPage = connection.pageInfo.hasNextPage;
+    cursor = connection.pageInfo.endCursor;
+  }
+}
+
+// Usage: Process one page at a time
+for await (const page of paginateResults(client, query)) {
+  console.log(`Processing ${page.length} records`);
+  // Process records in chunks
+}
+```
+
+**Benefits of Manual Pagination:**
+- Process each page before fetching next
+- Lower memory footprint
+- Can pause/resume between pages
+- Better error handling per page
+
+---
+
+## Cursor Handling
+
+**Cursor Characteristics:**
+- Opaque strings (do not parse)
+- Base64-encoded (implementation detail)
+- Connection-specific (don't reuse across queries)
+- Stable (same cursor returns same position)
+
+```typescript
+// ✅ CORRECT: Use cursors as-is
+let cursor = pageInfo.endCursor;
+await client.graphql({
+  query,
+  variables: { first: 100, after: cursor }
+});
+
+// ❌ WRONG: Don't parse or manipulate
+const decoded = Buffer.from(cursor, 'base64').toString();  // Don't do this!
+cursor = cursor.substring(0, 10);  // Don't truncate!
+```
+
+**Cursor Storage:**
+
+```typescript
+// Save cursor for resumability
+const stateService = new StateService(kvAdapter);
+
+let cursor = await stateService.get('last_cursor');
+while (hasNextPage) {
+  const result = await client.graphql({
+    query,
+    variables: { first: 100, after: cursor }
+  });
+
+  // Process page...
+
+  cursor = result.data.inventoryPositions.pageInfo.endCursor;
+  await stateService.set('last_cursor', cursor);  // Checkpoint
+}
+```
+
+---
+
+## pageInfo Management
+
+The `pageInfo` object controls pagination flow:
+
+```typescript
+interface PageInfo {
+  hasNextPage: boolean;      // More pages available?
+  hasPreviousPage: boolean;  // Can paginate backwards?
+  startCursor: string | null;  // First cursor in page
+  endCursor: string | null;    // Last cursor in page
+}
+```
+
+**Forward Pagination:**
+```typescript
+// Use endCursor + hasNextPage
+while (pageInfo.hasNextPage) {
+  const result = await client.graphql({
+    query,
+    variables: { first: 100, after: pageInfo.endCursor }
+  });
+  pageInfo = result.data.connection.pageInfo;
+}
+```
+
+**Backward Pagination:**
+```typescript
+// Use startCursor + hasPreviousPage
+while (pageInfo.hasPreviousPage) {
+  const result = await client.graphql({
+    query,
+    variables: { last: 100, before: pageInfo.startCursor }
+  });
+  pageInfo = result.data.connection.pageInfo;
+}
+```
+
+---
+
+## Performance Considerations
+
+### Page Size Selection
+
+| Page Size | Use Case | Pros | Cons |
+|-----------|----------|------|------|
+| 25-50 | Real-time UI | Fast response | Many requests |
+| 100 | Balanced (default) | Good throughput | Moderate memory |
+| 250 | Batch processing | Fewer requests | Higher memory |
+
+```typescript
+// Small pages for UI responsiveness
+const results = await client.graphql({
+  query,
+  pagination: { pageSize: 25 }  // Fast initial render
+});
+
+// Large pages for bulk ETL
+const results = await client.graphql({
+  query,
+  pagination: { pageSize: 250, delayMs: 500 }  // Respect rate limits
+});
+```
+
+### Rate Limiting
+
+Add delays between pages to avoid rate limits:
+
+```typescript
+const results = await client.graphql({
+  query,
+  pagination: {
+    pageSize: 250,
+    delayMs: 500  // 500ms delay between pages
+  }
+});
+```
+
+### Memory Management
+
+Process pages individually for large datasets:
+
+```typescript
+async function processLargeDataset(client, query) {
+  for await (const page of paginateResults(client, query)) {
+    // Process and discard each page
+    await processBatch(page);
+    // page is garbage collected after iteration
+  }
+}
+```
+
+---
+
+## Best Practices
+
+### 1. Always Include pageInfo
+
+```typescript
+// ✅ CORRECT: Include pageInfo
+query GetPositions($first: Int, $after: String) {
+  inventoryPositions(first: $first, after: $after) {
+    edges { node { id ref } }
+    pageInfo { hasNextPage endCursor }  # Required!
+  }
+}
+
+// ❌ WRONG: Missing pageInfo
+query GetPositions {
+  inventoryPositions {
+    edges { node { id ref } }
+    # Can't paginate without pageInfo!
+  }
+}
+```
+
+### 2. Use Variables for Pagination
+
+```typescript
+// ✅ CORRECT: Parameterized pagination
+query GetPositions($first: Int, $after: String) {
+  inventoryPositions(first: $first, after: $after) { ... }
+}
+
+// ❌ WRONG: Hardcoded values
+query GetPositions {
+  inventoryPositions(first: 100, after: "xyz") { ... }
+}
+```
+
+### 3. Handle Empty Pages
+
+```typescript
+const result = await client.graphql({ query, variables });
+
+if (result.data.inventoryPositions.edges.length === 0) {
+  console.log('No results found');
+  return;
+}
+
+// Process results...
+```
+
+### 4. Implement Timeouts
+
+```typescript
+const TIMEOUT_MS = 30000;  // 30 seconds
+
+const controller = new AbortController();
+const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS);
+
+try {
+  const result = await client.graphql({
+    query,
+    variables,
+    signal: controller.signal
+  });
+} finally {
+  clearTimeout(timeout);
+}
+```
+
+---
+
+## Common Patterns
+
+### Pattern 1: Full Dataset Export
+
+```typescript
+async function exportAllPositions(client) {
+  const allRecords = [];
+
+  for await (const page of paginateResults(client, query)) {
+    allRecords.push(...page);
+  }
+
+  return allRecords;
+}
+```
+
+### Pattern 2: Streaming to File
+
+```typescript
+import { createWriteStream } from 'fs';
+
+async function streamToCSV(client, outputPath) {
+  const writer = createWriteStream(outputPath);
+  writer.write('ref,onHand,productRef,locationRef\n');
+
+  for await (const page of paginateResults(client, query)) {
+    for (const record of page) {
+      writer.write(`${record.ref},${record.onHand},${record.productRef},${record.locationRef}\n`);
+    }
+  }
+
+  writer.end();
+}
+```
+
+### Pattern 3: Progress Tracking
+
+```typescript
+async function fetchWithProgress(client, query) {
+  let totalFetched = 0;
+  let pageNum = 0;
+
+  for await (const page of paginateResults(client, query)) {
+    totalFetched += page.length;
+    pageNum++;
+    console.log(`Page ${pageNum}: ${totalFetched} records fetched`);
+  }
+
+  return totalFetched;
+}
+```
+
+---
+
+## Troubleshooting
+
+### Issue 1: Pagination Never Stops
+
+**Symptom:** Loop runs forever despite data being exhausted
+
+**Cause:** Not checking `hasNextPage`
+
+**Solution:**
+```typescript
+// ✅ Check hasNextPage
+while (pageInfo.hasNextPage) {
+  // Fetch next page...
+}
+```
+
+### Issue 2: Duplicate Records
+
+**Symptom:** Same records appear multiple times
+
+**Cause:** Not using cursor correctly
+
+**Solution:**
+```typescript
+// ✅ Always pass endCursor from previous page
+cursor = result.data.connection.pageInfo.endCursor;
+```
+
+### Issue 3: Missing Records
+
+**Symptom:** Some records not fetched
+
+**Cause:** Starting with wrong cursor
+
+**Solution:**
+```typescript
+// ✅ Start with null cursor
+let cursor = null;  // Start from beginning
+```
+
+### Issue 4: Memory Leak
+
+**Symptom:** Memory usage grows indefinitely
+
+**Cause:** Accumulating all pages in memory
+
+**Solution:**
+```typescript
+// ✅ Process pages individually
+for await (const page of paginateResults(client, query)) {
+  await processBatch(page);
+  // page is discarded after iteration
+}
+```
+
+---
+
+## See Also
+
+**Related Modules:**
+- [Module 01: Client API](./api-reference-01-client-api.md) - FluentClient GraphQL methods
+- [Module 05: Services](./api-reference-05-services.md) - ExtractionOrchestrator with auto-pagination
+- [Auto-Pagination Guide](../../auto-pagination/modules/auto-pagination-01-foundations.md) - Deep dive into pagination
+
+**Complete Guides:**
+- [Auto-Pagination Module Series](../../auto-pagination/modules/readme.md) - 7-module learning path
+- [Extraction Guide](../../extraction/extraction-readme.md) - Large dataset exports
+- [GraphQL Best Practices](../../00-START-HERE/getting-started.md#graphql-queries)
+
+**Templates:**
+- [GraphQL Extraction Templates](../../../01-TEMPLATES/versori/workflows/extraction/graphql-queries/) - Production examples
+
+---
+
+**Navigation:**
+- [Back to Module List](./readme.md)
+- [Previous: Module 07 - Parsers](./api-reference-07-parsers.md)
+- [Next: Module 09 - Webhook Validation](./api-reference-09-webhook-validation.md)