npm - @fluentcommerce/fc-connect-sdk - Versions diffs - 0.1.53 → 0.1.55 - Mend

@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (495) hide show

package/docs/02-CORE-GUIDES/auto-pagination/modules/auto-pagination-01-foundations.md CHANGED Viewed

@@ -1,470 +1,470 @@
-# Module 1: Foundations
-> **Learning Objective:** Understand why pagination is essential, how Relay-style pagination works, and how Fluent Commerce implements it.
->
-> **Level:** Beginner
-## Table of Contents
-1. [Why Pagination Matters](#why-pagination-matters)
-2. [The Problem Without Pagination](#the-problem-without-pagination)
-3. [The Relay Connection Specification](#the-relay-connection-specification)
-4. [How Fluent Commerce Implements Relay](#how-fluent-commerce-implements-relay)
-5. [Cursor-Based vs Offset-Based](#cursor-based-vs-offset-based)
-6. [Key Terminology](#key-terminology)
-7. [Next Steps](#next-steps)
----
-## Why Pagination Matters
-Fluent Commerce APIs can return thousands or even millions of records:
-- **Inventory positions**: 50,000+ SKU locations across warehouses
-- **Orders**: 100,000+ orders per day for large retailers
-- **Products**: 250,000+ product catalog with variants
-- **Fulfillment events**: Millions of historical events
-Without pagination, fetching large datasets causes:
-### ❌ Performance Problems
-| Issue                 | Impact                            | Example                           |
-| --------------------- | --------------------------------- | --------------------------------- |
-| **API Timeouts**      | Requests fail after 30-60 seconds | Query for 50K positions times out |
-| **Memory Exhaustion** | Node.js/Deno runs out of memory   | 100K orders = OOM crash           |
-| **Slow Responses**    | Minutes to return data            | 5+ minutes for product catalog    |
-| **Network Overhead**  | Multi-MB responses over the wire  | 10MB JSON response blocks network |
-### ✅ With Pagination
-| Benefit                 | Result                             |
-| ----------------------- | ---------------------------------- |
-| **Fast Response Times** | Each page returns in <1 second     |
-| **Memory Efficient**    | Process data in manageable chunks  |
-| **Fault Tolerant**      | Resume from last cursor on failure |
-| **Rate Limit Friendly** | Spread requests over time          |
----
-## The Problem Without Pagination
-### Real-World Scenario
-Imagine fetching all virtual positions (inventory) for a large retailer:
-```typescript
-// ❌ WRONG: Attempting to fetch everything at once
-const result = await client.graphql({
-  query: `
-    query GetAllPositions {
-      virtualPositions {
-        edges {
-          node {
-            id
-            productRef
-            quantity
-            groupRef
-          }
-        }
-      }
-    }
-  `,
-});
-// What happens?
-// 1. API attempts to load 50,000+ positions into memory
-// 2. Query takes 3+ minutes to execute
-// 3. Returns 15MB JSON response
-// 4. Likely times out or crashes with OOM error
-```
-### Consequences
-1. **Database Load**: Single query scans entire table
-2. **API Server Strain**: Serializing huge JSON response
-3. **Network Bandwidth**: Transferring multi-MB payload
-4. **Client Memory**: Deserializing and storing all records
-5. **User Experience**: Long wait times, failed requests
----
-## The Relay Connection Specification
-Fluent Commerce follows the **[Relay Cursor Connections Specification](https://relay.dev/graphql/connections.htm)**, a GraphQL best practice for pagination.
-### Core Concepts
-#### 1. Connection Object
-A "connection" is a pageable collection with metadata:
-```graphql
-type VirtualPositionConnection {
-  edges: [VirtualPositionEdge!]! # Array of items with cursors
-  pageInfo: PageInfo! # Pagination metadata
-}
-```
-#### 2. Edge Object
-An "edge" wraps each item with a cursor (position marker):
-```graphql
-type VirtualPositionEdge {
-  node: VirtualPosition! # The actual data
-  cursor: String! # Opaque position marker
-}
-```
-#### 3. PageInfo Object
-Metadata about pagination state:
-```graphql
-type PageInfo {
-  hasNextPage: Boolean! # More data available forward?
-  hasPreviousPage: Boolean! # More data available backward?
-  # NOTE: Fluent Commerce does NOT return startCursor/endCursor in pageInfo
-  # Cursors are in edges[].cursor instead (edge-based cursors)
-}
-```
-**Fluent Commerce Implementation Note:**
-Unlike the full Relay spec, Fluent uses **edge-based cursors only**. The SDK extracts cursors from `edges[].cursor`, not from `pageInfo.startCursor`/`endCursor`.
-#### 4. Pagination Arguments
-Arguments for requesting pages:
-```graphql
-virtualPositions(
-  first: Int          # Forward pagination: fetch N items
-  after: String       # Start after this cursor
-  last: Int           # Backward pagination: fetch last N items
-  before: String      # Start before this cursor
-): VirtualPositionConnection
-```
-### Visual Representation
-```
-Full Dataset: [Item1, Item2, Item3, Item4, Item5, Item6, Item7, Item8, Item9, Item10]
-                      ↓
-            ┌─────────────────────┐
-Page 1      │ first: 3            │
-            │ after: null         │
-            └─────────────────────┘
-            Returns: [Item1, Item2, Item3]
-            edges[2].cursor: "cursor-3" (last edge)
-            hasNextPage: true
-                      ↓
-            ┌─────────────────────┐
-Page 2      │ first: 3            │
-            │ after: "cursor-3"   │
-            └─────────────────────┘
-            Returns: [Item4, Item5, Item6]
-            edges[2].cursor: "cursor-6" (last edge)
-            hasNextPage: true
-                      ↓
-            ┌─────────────────────┐
-Page 3      │ first: 3            │
-            │ after: "cursor-6"   │
-            └─────────────────────┘
-            Returns: [Item7, Item8, Item9]
-            edges[2].cursor: "cursor-9" (last edge)
-            hasNextPage: true
-                      ↓
-            ┌─────────────────────┐
-Page 4      │ first: 3            │
-            │ after: "cursor-9"   │
-            └─────────────────────┘
-            Returns: [Item10]
-            edges[0].cursor: "cursor-10" (last edge)
-            hasNextPage: false  ← No more pages!
-**Note:** Cursors come from edges[].cursor (Fluent uses edge-based cursors)
-```
----
-## How Fluent Commerce Implements Relay
-### Standard Query Pattern
-Every pageable query in Fluent follows this pattern:
-```graphql
-query GetVirtualPositions($first: Int!, $after: String) {
-  virtualPositions(first: $first, after: $after) {
-    edges {
-      node {
-        # Actual data fields
-        id
-        productRef
-        quantity
-      }
-      cursor # Position marker
-    }
-    pageInfo {
-      hasNextPage # More pages available?
-    }
-  }
-}
-```
-### Key Fluent Behaviors
-#### 1. Cursor Format
-Fluent uses **opaque base64-encoded cursors**:
-```typescript
-// Example cursor (base64 encoded position)
-'Y3Vyc29yOjE2MzI0NTY3ODk=';
-// ⚠️ NEVER manually parse or construct cursors!
-// They're opaque strings managed by the API
-```
-#### 2. Edge-Based Cursors Only
-Unlike full Relay spec, Fluent **does NOT return `startCursor`/`endCursor` in `pageInfo`**:
-```typescript
-// ❌ NOT available in Fluent
-pageInfo {
-  startCursor  // Not returned
-  endCursor    // Not returned
-}
-// ✅ Use edge cursors instead
-edges[0].cursor        // First cursor
-edges[edges.length-1].cursor  // Last cursor
-```
-#### 3. Default Page Size
-If `first` is omitted, Fluent defaults to **100 items per page**.
-#### 4. Maximum Page Size
-Fluent enforces a maximum of **250 items per page**:
-```typescript
-// ✅ Valid
-{
-  first: 100;
-}
-// ✅ Valid (max allowed)
-{
-  first: 250;
-}
-// ❌ Error: exceeds max page size
-{
-  first: 500;
-}
-```
----
-## Cursor-Based vs Offset-Based
-### Offset-Based Pagination (Traditional)
-```sql
--- Page 1
-SELECT * FROM items LIMIT 100 OFFSET 0;
--- Page 2
-SELECT * FROM items LIMIT 100 OFFSET 100;
--- Page 3
-SELECT * FROM items LIMIT 100 OFFSET 200;
-```
-**Problems:**
-- ❌ Slow for large offsets (must scan all skipped rows)
-- ❌ Inconsistent results if data changes between pages
-- ❌ Duplicate or missing items if items are added/deleted
-### Cursor-Based Pagination (Relay)
-```graphql
-# Page 1
-query {
-  items(first: 100) {
-    edges {
-      cursor
-    }
-  }
-}
-# Page 2 (using last cursor from page 1)
-query {
-  items(first: 100, after: "cursor-100") {
-    edges {
-      cursor
-    }
-  }
-}
-# Page 3 (using last cursor from page 2)
-query {
-  items(first: 100, after: "cursor-200") {
-    edges {
-      cursor
-    }
-  }
-}
-```
-**Advantages:**
-- ✅ Fast for any page (indexed cursor lookup)
-- ✅ Consistent snapshots (cursor marks exact position)
-- ✅ No duplicates or skipped items
-- ✅ Stable across concurrent data changes
----
-## Key Terminology
-| Term                    | Definition                   | Example                                |
-| ----------------------- | ---------------------------- | -------------------------------------- |
-| **Connection**          | Pageable collection of items | `virtualPositions`                     |
-| **Edge**                | Item wrapper with cursor     | `{ node: {...}, cursor: "abc123" }`    |
-| **Node**                | The actual data object       | `{ id: "123", productRef: "SKU-001" }` |
-| **Cursor**              | Opaque position marker       | `"Y3Vyc29yOjE2MzI0NTY3ODk="`           |
-| **PageInfo**            | Pagination metadata          | `{ hasNextPage: true }`                |
-| **Forward Pagination**  | Using `first` and `after`    | Most common pattern                    |
-| **Backward Pagination** | Using `last` and `before`    | Less common, reverse order             |
-| **Page Size**           | Number of items per page     | `first: 100`                           |
----
-## How SDK Auto-Pagination Helps
-Without the SDK, you'd need to write this manually:
-```typescript
-// Manual pagination (15-20 lines, error-prone)
-let allRecords = [];
-let hasMore = true;
-let cursor = null;
-while (hasMore) {
-  const result = await client.graphql({
-    query,
-    variables: { first: 100, after: cursor },
-  });
-  allRecords.push(...result.data.virtualPositions.edges);
-  const lastEdge =
-    result.data.virtualPositions.edges[result.data.virtualPositions.edges.length - 1];
-  cursor = lastEdge?.cursor;
-  hasMore = result.data.virtualPositions.pageInfo.hasNextPage;
-  // What about errors? Rate limits? Infinite loops? Memory?
-  if (allRecords.length > 10000) break; // Manual safety
-}
-```
-With the SDK, it's just:
-```typescript
-// Auto-pagination (3 lines, built-in safety)
-const result = await client.graphql({
-  query,
-  variables: { first: 100 },
-  pagination: { maxRecords: 10000 },
-});
-const allRecords = result.data.virtualPositions.edges;
-```
-The SDK handles:
-- ✅ Cursor tracking and management
-- ✅ Injects $first automatically when omitted and manages $after between pages
-- ✅ Loop control and termination
-- ✅ Error handling and retries
-- ✅ Safety limits (pages, records, timeout)
-- ✅ Deduplication (by node ID)
-- ✅ Infinite loop protection
-- ✅ Progress callbacks
-- ✅ Memory-efficient merging
----
-## Understanding the Flow
-Here's what happens when you use auto-pagination:
-```
-1. SDK receives your query with pagination variables ($first, $after)
-   ↓
-2. SDK detects query is pageable (has pagination variables)
-   ↓
-3. SDK makes first request with your variables
-   ↓
-4. SDK checks response:
-   - Extracts edges and cursor
-   - Checks pageInfo.hasNextPage
-   - Checks safety limits (maxPages, maxRecords, timeout)
-   ↓
-5. If hasNextPage == true AND limits not reached:
-   - Extract last edge cursor
-   - Make next request with after: cursor
-   - Repeat step 4
-   ↓
-6. When done (hasNextPage == false OR limit reached):
-   - Merge all pages into single response
-   - Deduplicate nodes by ID
-   - Add metadata to response.extensions.autoPagination
-   - Return complete result
-```
----
-## Quick Comparison
-| Feature                      | Manual Pagination         | SDK Auto-Pagination |
-| ---------------------------- | ------------------------- | ------------------- |
-| **Code Lines**               | 15-20 lines               | 3 lines             |
-| **Cursor Management**        | Manual tracking           | Automatic           |
-| **Error Handling**           | Manual try-catch per page | Built-in fail-fast  |
-| **Safety Limits**            | Manual break conditions   | Built-in OR-logic   |
-| **Deduplication**            | Manual Set management     | Automatic by ID     |
-| **Progress Tracking**        | Manual logging            | Built-in callbacks  |
-| **Infinite Loop Protection** | Manual cursor checking    | Automatic           |
-| **Memory Management**        | Manual chunking           | Built-in limits     |
----
-## Next Steps
-Now that you understand the foundations, you're ready to write your first auto-paginated query!
-**Continue to:** [Module 2: Quick Start →](./auto-pagination-02-quick-start.md)
-Or explore:
-- [Module 3: Configuration](./auto-pagination-03-configuration.md) - Deep dive into config options
-- [Examples](../examples/) - See working code samples
----
-## Additional Resources
-- [Relay Cursor Connections Spec](https://relay.dev/graphql/connections.htm) - Official specification
-- [GraphQL Pagination Best Practices](https://graphql.org/learn/pagination/) - GraphQL.org guide
-- [Fluent API Documentation](https://docs.fluentcommerce.com/) - Official Fluent docs
----
-[← Back to Index](../../advanced-services/advanced-services-readme.md) | [Next: Quick Start →](./auto-pagination-02-quick-start.md)
+# Module 1: Foundations
+> **Learning Objective:** Understand why pagination is essential, how Relay-style pagination works, and how Fluent Commerce implements it.
+>
+> **Level:** Beginner
+## Table of Contents
+1. [Why Pagination Matters](#why-pagination-matters)
+2. [The Problem Without Pagination](#the-problem-without-pagination)
+3. [The Relay Connection Specification](#the-relay-connection-specification)
+4. [How Fluent Commerce Implements Relay](#how-fluent-commerce-implements-relay)
+5. [Cursor-Based vs Offset-Based](#cursor-based-vs-offset-based)
+6. [Key Terminology](#key-terminology)
+7. [Next Steps](#next-steps)
+---
+## Why Pagination Matters
+Fluent Commerce APIs can return thousands or even millions of records:
+- **Inventory positions**: 50,000+ SKU locations across warehouses
+- **Orders**: 100,000+ orders per day for large retailers
+- **Products**: 250,000+ product catalog with variants
+- **Fulfillment events**: Millions of historical events
+Without pagination, fetching large datasets causes:
+### ❌ Performance Problems
+| Issue                 | Impact                            | Example                           |
+| --------------------- | --------------------------------- | --------------------------------- |
+| **API Timeouts**      | Requests fail after 30-60 seconds | Query for 50K positions times out |
+| **Memory Exhaustion** | Node.js/Deno runs out of memory   | 100K orders = OOM crash           |
+| **Slow Responses**    | Minutes to return data            | 5+ minutes for product catalog    |
+| **Network Overhead**  | Multi-MB responses over the wire  | 10MB JSON response blocks network |
+### ✅ With Pagination
+| Benefit                 | Result                             |
+| ----------------------- | ---------------------------------- |
+| **Fast Response Times** | Each page returns in <1 second     |
+| **Memory Efficient**    | Process data in manageable chunks  |
+| **Fault Tolerant**      | Resume from last cursor on failure |
+| **Rate Limit Friendly** | Spread requests over time          |
+---
+## The Problem Without Pagination
+### Real-World Scenario
+Imagine fetching all virtual positions (inventory) for a large retailer:
+```typescript
+// ❌ WRONG: Attempting to fetch everything at once
+const result = await client.graphql({
+  query: `
+    query GetAllPositions {
+      virtualPositions {
+        edges {
+          node {
+            id
+            productRef
+            quantity
+            groupRef
+          }
+        }
+      }
+    }
+  `,
+});
+// What happens?
+// 1. API attempts to load 50,000+ positions into memory
+// 2. Query takes 3+ minutes to execute
+// 3. Returns 15MB JSON response
+// 4. Likely times out or crashes with OOM error
+```
+### Consequences
+1. **Database Load**: Single query scans entire table
+2. **API Server Strain**: Serializing huge JSON response
+3. **Network Bandwidth**: Transferring multi-MB payload
+4. **Client Memory**: Deserializing and storing all records
+5. **User Experience**: Long wait times, failed requests
+---
+## The Relay Connection Specification
+Fluent Commerce follows the **[Relay Cursor Connections Specification](https://relay.dev/graphql/connections.htm)**, a GraphQL best practice for pagination.
+### Core Concepts
+#### 1. Connection Object
+A "connection" is a pageable collection with metadata:
+```graphql
+type VirtualPositionConnection {
+  edges: [VirtualPositionEdge!]! # Array of items with cursors
+  pageInfo: PageInfo! # Pagination metadata
+}
+```
+#### 2. Edge Object
+An "edge" wraps each item with a cursor (position marker):
+```graphql
+type VirtualPositionEdge {
+  node: VirtualPosition! # The actual data
+  cursor: String! # Opaque position marker
+}
+```
+#### 3. PageInfo Object
+Metadata about pagination state:
+```graphql
+type PageInfo {
+  hasNextPage: Boolean! # More data available forward?
+  hasPreviousPage: Boolean! # More data available backward?
+  # NOTE: Fluent Commerce does NOT return startCursor/endCursor in pageInfo
+  # Cursors are in edges[].cursor instead (edge-based cursors)
+}
+```
+**Fluent Commerce Implementation Note:**
+Unlike the full Relay spec, Fluent uses **edge-based cursors only**. The SDK extracts cursors from `edges[].cursor`, not from `pageInfo.startCursor`/`endCursor`.
+#### 4. Pagination Arguments
+Arguments for requesting pages:
+```graphql
+virtualPositions(
+  first: Int          # Forward pagination: fetch N items
+  after: String       # Start after this cursor
+  last: Int           # Backward pagination: fetch last N items
+  before: String      # Start before this cursor
+): VirtualPositionConnection
+```
+### Visual Representation
+```
+Full Dataset: [Item1, Item2, Item3, Item4, Item5, Item6, Item7, Item8, Item9, Item10]
+                      ↓
+            ┌─────────────────────┐
+Page 1      │ first: 3            │
+            │ after: null         │
+            └─────────────────────┘
+            Returns: [Item1, Item2, Item3]
+            edges[2].cursor: "cursor-3" (last edge)
+            hasNextPage: true
+                      ↓
+            ┌─────────────────────┐
+Page 2      │ first: 3            │
+            │ after: "cursor-3"   │
+            └─────────────────────┘
+            Returns: [Item4, Item5, Item6]
+            edges[2].cursor: "cursor-6" (last edge)
+            hasNextPage: true
+                      ↓
+            ┌─────────────────────┐
+Page 3      │ first: 3            │
+            │ after: "cursor-6"   │
+            └─────────────────────┘
+            Returns: [Item7, Item8, Item9]
+            edges[2].cursor: "cursor-9" (last edge)
+            hasNextPage: true
+                      ↓
+            ┌─────────────────────┐
+Page 4      │ first: 3            │
+            │ after: "cursor-9"   │
+            └─────────────────────┘
+            Returns: [Item10]
+            edges[0].cursor: "cursor-10" (last edge)
+            hasNextPage: false  ← No more pages!
+**Note:** Cursors come from edges[].cursor (Fluent uses edge-based cursors)
+```
+---
+## How Fluent Commerce Implements Relay
+### Standard Query Pattern
+Every pageable query in Fluent follows this pattern:
+```graphql
+query GetVirtualPositions($first: Int!, $after: String) {
+  virtualPositions(first: $first, after: $after) {
+    edges {
+      node {
+        # Actual data fields
+        id
+        productRef
+        quantity
+      }
+      cursor # Position marker
+    }
+    pageInfo {
+      hasNextPage # More pages available?
+    }
+  }
+}
+```
+### Key Fluent Behaviors
+#### 1. Cursor Format
+Fluent uses **opaque base64-encoded cursors**:
+```typescript
+// Example cursor (base64 encoded position)
+'Y3Vyc29yOjE2MzI0NTY3ODk=';
+// ⚠️ NEVER manually parse or construct cursors!
+// They're opaque strings managed by the API
+```
+#### 2. Edge-Based Cursors Only
+Unlike full Relay spec, Fluent **does NOT return `startCursor`/`endCursor` in `pageInfo`**:
+```typescript
+// ❌ NOT available in Fluent
+pageInfo {
+  startCursor  // Not returned
+  endCursor    // Not returned
+}
+// ✅ Use edge cursors instead
+edges[0].cursor        // First cursor
+edges[edges.length-1].cursor  // Last cursor
+```
+#### 3. Default Page Size
+If `first` is omitted, Fluent defaults to **100 items per page**.
+#### 4. Maximum Page Size
+Fluent enforces a maximum of **250 items per page**:
+```typescript
+// ✅ Valid
+{
+  first: 100;
+}
+// ✅ Valid (max allowed)
+{
+  first: 250;
+}
+// ❌ Error: exceeds max page size
+{
+  first: 500;
+}
+```
+---
+## Cursor-Based vs Offset-Based
+### Offset-Based Pagination (Traditional)
+```sql
+-- Page 1
+SELECT * FROM items LIMIT 100 OFFSET 0;
+-- Page 2
+SELECT * FROM items LIMIT 100 OFFSET 100;
+-- Page 3
+SELECT * FROM items LIMIT 100 OFFSET 200;
+```
+**Problems:**
+- ❌ Slow for large offsets (must scan all skipped rows)
+- ❌ Inconsistent results if data changes between pages
+- ❌ Duplicate or missing items if items are added/deleted
+### Cursor-Based Pagination (Relay)
+```graphql
+# Page 1
+query {
+  items(first: 100) {
+    edges {
+      cursor
+    }
+  }
+}
+# Page 2 (using last cursor from page 1)
+query {
+  items(first: 100, after: "cursor-100") {
+    edges {
+      cursor
+    }
+  }
+}
+# Page 3 (using last cursor from page 2)
+query {
+  items(first: 100, after: "cursor-200") {
+    edges {
+      cursor
+    }
+  }
+}
+```
+**Advantages:**
+- ✅ Fast for any page (indexed cursor lookup)
+- ✅ Consistent snapshots (cursor marks exact position)
+- ✅ No duplicates or skipped items
+- ✅ Stable across concurrent data changes
+---
+## Key Terminology
+| Term                    | Definition                   | Example                                |
+| ----------------------- | ---------------------------- | -------------------------------------- |
+| **Connection**          | Pageable collection of items | `virtualPositions`                     |
+| **Edge**                | Item wrapper with cursor     | `{ node: {...}, cursor: "abc123" }`    |
+| **Node**                | The actual data object       | `{ id: "123", productRef: "SKU-001" }` |
+| **Cursor**              | Opaque position marker       | `"Y3Vyc29yOjE2MzI0NTY3ODk="`           |
+| **PageInfo**            | Pagination metadata          | `{ hasNextPage: true }`                |
+| **Forward Pagination**  | Using `first` and `after`    | Most common pattern                    |
+| **Backward Pagination** | Using `last` and `before`    | Less common, reverse order             |
+| **Page Size**           | Number of items per page     | `first: 100`                           |
+---
+## How SDK Auto-Pagination Helps
+Without the SDK, you'd need to write this manually:
+```typescript
+// Manual pagination (15-20 lines, error-prone)
+let allRecords = [];
+let hasMore = true;
+let cursor = null;
+while (hasMore) {
+  const result = await client.graphql({
+    query,
+    variables: { first: 100, after: cursor },
+  });
+  allRecords.push(...result.data.virtualPositions.edges);
+  const lastEdge =
+    result.data.virtualPositions.edges[result.data.virtualPositions.edges.length - 1];
+  cursor = lastEdge?.cursor;
+  hasMore = result.data.virtualPositions.pageInfo.hasNextPage;
+  // What about errors? Rate limits? Infinite loops? Memory?
+  if (allRecords.length > 10000) break; // Manual safety
+}
+```
+With the SDK, it's just:
+```typescript
+// Auto-pagination (3 lines, built-in safety)
+const result = await client.graphql({
+  query,
+  variables: { first: 100 },
+  pagination: { maxRecords: 10000 },
+});
+const allRecords = result.data.virtualPositions.edges;
+```
+The SDK handles:
+- ✅ Cursor tracking and management
+- ✅ Injects $first automatically when omitted and manages $after between pages
+- ✅ Loop control and termination
+- ✅ Error handling and retries
+- ✅ Safety limits (pages, records, timeout)
+- ✅ Deduplication (by node ID)
+- ✅ Infinite loop protection
+- ✅ Progress callbacks
+- ✅ Memory-efficient merging
+---
+## Understanding the Flow
+Here's what happens when you use auto-pagination:
+```
+1. SDK receives your query with pagination variables ($first, $after)
+   ↓
+2. SDK detects query is pageable (has pagination variables)
+   ↓
+3. SDK makes first request with your variables
+   ↓
+4. SDK checks response:
+   - Extracts edges and cursor
+   - Checks pageInfo.hasNextPage
+   - Checks safety limits (maxPages, maxRecords, timeout)
+   ↓
+5. If hasNextPage == true AND limits not reached:
+   - Extract last edge cursor
+   - Make next request with after: cursor
+   - Repeat step 4
+   ↓
+6. When done (hasNextPage == false OR limit reached):
+   - Merge all pages into single response
+   - Deduplicate nodes by ID
+   - Add metadata to response.extensions.autoPagination
+   - Return complete result
+```
+---
+## Quick Comparison
+| Feature                      | Manual Pagination         | SDK Auto-Pagination |
+| ---------------------------- | ------------------------- | ------------------- |
+| **Code Lines**               | 15-20 lines               | 3 lines             |
+| **Cursor Management**        | Manual tracking           | Automatic           |
+| **Error Handling**           | Manual try-catch per page | Built-in fail-fast  |
+| **Safety Limits**            | Manual break conditions   | Built-in OR-logic   |
+| **Deduplication**            | Manual Set management     | Automatic by ID     |
+| **Progress Tracking**        | Manual logging            | Built-in callbacks  |
+| **Infinite Loop Protection** | Manual cursor checking    | Automatic           |
+| **Memory Management**        | Manual chunking           | Built-in limits     |
+---
+## Next Steps
+Now that you understand the foundations, you're ready to write your first auto-paginated query!
+**Continue to:** [Module 2: Quick Start →](./auto-pagination-02-quick-start.md)
+Or explore:
+- [Module 3: Configuration](./auto-pagination-03-configuration.md) - Deep dive into config options
+- [Examples](../examples/) - See working code samples
+---
+## Additional Resources
+- [Relay Cursor Connections Spec](https://relay.dev/graphql/connections.htm) - Official specification
+- [GraphQL Pagination Best Practices](https://graphql.org/learn/pagination/) - GraphQL.org guide
+- [Fluent API Documentation](https://docs.fluentcommerce.com/) - Official Fluent docs
+---
+[← Back to Index](../../advanced-services/advanced-services-readme.md) | [Next: Quick Start →](./auto-pagination-02-quick-start.md)