@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/02-CORE-GUIDES/auto-pagination/modules/auto-pagination-04-advanced-patterns.md

@@ -1,732 +1,732 @@
-# Module 4: Advanced Query Patterns
-
-> **Learning Objective:** Master complex pagination scenarios including nested connections, fragments, aliases, and multiple connections.
->
-> **Level:** Advanced
-
-## Table of Contents
-
-1. [Nested Connections](#nested-connections)
-2. [Multiple Connections](#multiple-connections)
-3. [Using Fragments](#using-fragments)
-4. [Query Aliases](#query-aliases)
-5. [Inline Fragments](#inline-fragments)
-6. [Custom Variable Names](#custom-variable-names)
-7. [Filtering with Pagination](#filtering-with-pagination)
-8. [Backward Pagination](#backward-pagination)
-
----
-
-## Nested Connections
-
-Paginate nested collections (e.g., order → items).
-
-### Example: Order Items Pagination
-
-```typescript
-const result = await client.graphql({
-  query: `
-    query GetOrderItems($orderId: ID!, $first: Int!, $after: String) {
-      order(id: $orderId) {
-        id
-        ref
-        status
-        items(first: $first, after: $after) {
-          edges {
-            node {
-              id
-              productRef
-              quantity
-              price
-            }
-            cursor
-          }
-          pageInfo {
-            hasNextPage
-          }
-        }
-      }
-    }
-  `,
-  variables: {
-    orderId: 'ORDER-123',
-    first: 50
-  },
-  pagination: {
-    connectionPath: 'order.items',  // Target nested connection!
-    maxPages: 20,
-    maxRecords: 1000
-  }
-});
-
-// Access nested items
-const items = result.data.order.items.edges;
-console.log(`Total items: ${result.extensions.autoPagination.totalRecords}`);
-```
-
-### Multi-Level Nesting
-
-```typescript
-// Query with multiple nesting levels
-const result = await client.graphql({
-  query: `
-    query GetFulfilmentArticles($fulfilmentId: ID!, $first: Int!, $after: String) {
-      fulfilment(id: $fulfilmentId) {
-        id
-        order {
-          id
-          ref
-        }
-        articles(first: $first, after: $after) {
-          edges {
-            node {
-              id
-              requestedQuantity
-            }
-            cursor
-          }
-          pageInfo {
-            hasNextPage
-          }
-        }
-      }
-    }
-  `,
-  variables: { fulfilmentId: 'FUL-456', first: 30 },
-  pagination: {
-    connectionPath: 'fulfilment.articles',
-    maxPages: 15
-  }
-});
-```
-
----
-
-## Multiple Connections
-
-Handle queries with multiple pageable connections.
-
-### Pattern 1: Paginate One Connection
-
-```typescript
-// Multiple connections - paginate only locations
-const result = await client.graphql({
-  query: `
-    query GetMultiple($first: Int!, $after: String) {
-      locations(first: $first, after: $after) {
-        edges {
-          node { id ref name }
-          cursor
-        }
-        pageInfo { hasNextPage }
-      }
-      products(first: 10) {  # Not paginated - fixed size
-        edges {
-          node { id ref }
-        }
-      }
-    }
-  `,
-  variables: { first: 100 },
-  pagination: {
-    connectionPath: 'locations',  // Paginate locations only
-    maxPages: 50
-  }
-});
-
-// result.data.locations.edges - fully paginated
-// result.data.products.edges - only first 10 items
-```
-
-### Pattern 2: Sequential Pagination
-
-Paginate multiple connections sequentially (separate queries):
-
-```typescript
-// Fetch all locations
-const locationsResult = await client.graphql({
-  query: `
-    query GetLocations($first: Int!, $after: String) {
-      locations(first: $first, after: $after) {
-        edges {
-          node { id ref }
-          cursor
-        }
-        pageInfo { hasNextPage }
-      }
-    }
-  `,
-  variables: { first: 100 },
-  pagination: { maxRecords: 5000 }
-});
-
-// Then fetch all products
-const productsResult = await client.graphql({
-  query: `
-    query GetProducts($first: Int!, $after: String) {
-      products(first: $first, after: $after) {
-        edges {
-          node { id ref }
-          cursor
-        }
-        pageInfo { hasNextPage }
-      }
-    }
-  `,
-  variables: { first: 100 },
-  pagination: { maxRecords: 10000 }
-});
-```
-
----
-
-## Using Fragments
-
-Auto-pagination works seamlessly with GraphQL fragments.
-
-### Named Fragments
-
-```typescript
-const result = await client.graphql({
-  query: `
-    fragment LocationFields on Location {
-      id
-      ref
-      name
-      type
-      status
-      defaultCarrier
-    }
-
-    query GetLocations($first: Int!, $after: String) {
-      locations(first: $first, after: $after) {
-        edges {
-          node {
-            ...LocationFields
-          }
-          cursor
-        }
-        pageInfo {
-          hasNextPage
-        }
-      }
-    }
-  `,
-  variables: { first: 100 },
-  pagination: { maxPages: 50 }
-});
-```
-
-### Nested Fragments
-
-```typescript
-const result = await client.graphql({
-  query: `
-    fragment ProductBasic on Product {
-      id
-      ref
-      type
-      gtin
-    }
-
-    fragment ProductDetails on Product {
-      ...ProductBasic
-      status
-      createdOn
-      updatedOn
-    }
-
-    query GetProducts($first: Int!, $after: String) {
-      products(first: $first, after: $after) {
-        edges {
-          node {
-            ...ProductDetails
-          }
-          cursor
-        }
-        pageInfo {
-          hasNextPage
-        }
-      }
-    }
-  `,
-  variables: { first: 75 },
-  pagination: { maxRecords: 5000 }
-});
-```
-
----
-
-## Query Aliases
-
-Use aliases to rename fields in responses.
-
-### Basic Aliases
-
-```typescript
-const result = await client.graphql({
-  query: `
-    query GetLocations($first: Int!, $after: String) {
-      allLocations: locations(first: $first, after: $after) {
-        edges {
-          node {
-            locationId: id
-            locationRef: ref
-            locationName: name
-          }
-          cursor
-        }
-        pageInfo {
-          hasNextPage
-        }
-      }
-    }
-  `,
-  variables: { first: 100 },
-  pagination: {
-    connectionPath: 'allLocations',  // Use the alias!
-    maxPages: 50
-  }
-});
-
-// Access via alias
-const locations = result.data.allLocations.edges;
-console.log(locations[0].node.locationName);  // Aliased field
-```
-
-### Multiple Queries with Aliases
-
-```typescript
-const result = await client.graphql({
-  query: `
-    query GetData($first: Int!, $after: String) {
-      activeLocations: locations(first: $first, after: $after, status: "ACTIVE") {
-        edges {
-          node { id ref status }
-          cursor
-        }
-        pageInfo { hasNextPage }
-      }
-      inactiveLocations: locations(first: $first, status: "INACTIVE") {
-        edges {
-          node { id ref status }
-        }
-      }
-    }
-  `,
-  variables: { first: 100 },
-  pagination: {
-    connectionPath: 'activeLocations',  // Paginate only active
-    maxPages: 50
-  }
-});
-```
-
----
-
-## Inline Fragments
-
-Use inline fragments for interface/union types.
-
-```typescript
-const result = await client.graphql({
-  query: `
-    query GetProducts($first: Int!, $after: String) {
-      products(first: $first, after: $after) {
-        edges {
-          node {
-            id
-            ref
-            ... on StandardProduct {
-              gtin
-              attributes {
-                name
-                value
-              }
-            }
-            ... on VariantProduct {
-              gtin
-              options {
-                name
-                value
-              }
-            }
-          }
-          cursor
-        }
-        pageInfo {
-          hasNextPage
-        }
-      }
-    }
-  `,
-  variables: { first: 75 },
-  pagination: { maxPages: 50 }
-});
-```
-
----
-
-## Custom Variable Names
-
-SDK detects pagination variables even with custom names.
-
-### Pattern Detection
-
-SDK recognizes these patterns:
-- `$first` or `$*First` (e.g., `$itemsFirst`)
-- `$after` or `$*After` (e.g., `$itemsAfter`)
-- `$last` or `$*Last` (e.g., `$itemsLast`)
-- `$before` or `$*Before` (e.g., `$itemsBefore`)
-
-### Example with Custom Names
-
-```typescript
-const result = await client.graphql({
-  query: `
-    query GetItems($itemsFirst: Int!, $itemsAfter: String) {
-      items(first: $itemsFirst, after: $itemsAfter) {
-        edges {
-          node { id ref }
-          cursor
-        }
-        pageInfo { hasNextPage }
-      }
-    }
-  `,
-  variables: { itemsFirst: 100 },  // Custom variable name
-  pagination: { maxPages: 50 }
-  // SDK automatically detects $itemsFirst and $itemsAfter!
-});
-```
-
----
-
-## Filtering with Pagination
-
-Combine filters with pagination for targeted queries.
-
-### Date Range Filtering
-
-```typescript
-const result = await client.graphql({
-  query: `
-    query GetRecentOrders($first: Int!, $after: String, $from: DateTime!, $to: DateTime!) {
-      orders(
-        first: $first
-        after: $after
-        createdOn: { from: $from, to: $to }
-      ) {
-        edges {
-          node {
-            id
-            ref
-            status
-            createdOn
-          }
-          cursor
-        }
-        pageInfo { hasNextPage }
-      }
-    }
-  `,
-  variables: {
-    first: 100,
-    from: '2024-01-01T00:00:00Z',
-    to: '2024-12-31T23:59:59Z'
-  },
-  pagination: { maxRecords: 10000 }
-});
-```
-
-### Status Filtering
-
-```typescript
-const result = await client.graphql({
-  query: `
-    query GetActivePositions($first: Int!, $after: String, $status: [String!]) {
-      virtualPositions(
-        first: $first
-        after: $after
-        status: $status
-      ) {
-        edges {
-          node {
-            id
-            ref
-            productRef
-            quantity
-            status
-          }
-          cursor
-        }
-        pageInfo { hasNextPage }
-      }
-    }
-  `,
-  variables: {
-    first: 150,
-    status: ['ACTIVE', 'AVAILABLE']
-  },
-  pagination: { maxPages: 100 }
-});
-```
-
-### Reference List Filtering
-
-```typescript
-const result = await client.graphql({
-  query: `
-    query GetSpecificProducts($first: Int!, $after: String, $refs: [String!]!) {
-      products(
-        first: $first
-        after: $after
-        ref: $refs
-      ) {
-        edges {
-          node {
-            id
-            ref
-            type
-          }
-          cursor
-        }
-        pageInfo { hasNextPage }
-      }
-    }
-  `,
-  variables: {
-    first: 100,
-    refs: ['PROD-001', 'PROD-002', 'PROD-003']
-  },
-  pagination: { maxPages: 10 }
-});
-```
-
----
-
-## Backward Pagination
-
-Paginate in reverse order using `last` and `before`.
-
-### Basic Backward Pagination
-
-```typescript
-const result = await client.graphql({
-  query: `
-    query GetLatestItems($last: Int!, $before: String) {
-      items(last: $last, before: $before) {
-        edges {
-          node { id ref createdOn }
-          cursor
-        }
-        pageInfo {
-          hasPreviousPage
-        }
-      }
-    }
-  `,
-  variables: { last: 100 },
-  pagination: {
-    direction: 'backward',  // Required!
-    maxPages: 50
-  }
-});
-
-// Items are in reverse chronological order
-```
-
-### Reverse then Forward
-
-Get last page first, then paginate backward:
-
-```typescript
-// Step 1: Get cursor of last item
-const lastPageResult = await client.graphql({
-  query: `
-    query GetLastPage($last: Int!) {
-      items(last: $last) {
-        edges {
-          cursor
-          node { id ref }
-        }
-        pageInfo { hasPreviousPage }
-      }
-    }
-  `,
-  variables: { last: 1 },
-  pagination: { enabled: false }  // Disable auto-pagination
-});
-
-const lastCursor = lastPageResult.data.items.edges[0]?.cursor;
-
-// Step 2: Paginate backward from last cursor
-const backwardResult = await client.graphql({
-  query: `
-    query GetItemsBackward($last: Int!, $before: String) {
-      items(last: $last, before: $before) {
-        edges {
-          node { id ref }
-          cursor
-        }
-        pageInfo { hasPreviousPage }
-      }
-    }
-  `,
-  variables: { last: 100, before: lastCursor },
-  pagination: {
-    direction: 'backward',
-    maxPages: 50
-  }
-});
-```
-
----
-
-## Complete Real-World Examples
-
-### Example 1: Multi-Warehouse Inventory Export
-
-```typescript
-async function exportWarehouseInventory(warehouseRefs: string[]) {
-  const results = [];
-
-  for (const warehouseRef of warehouseRefs) {
-    console.log(`\n📦 Exporting inventory for ${warehouseRef}...`);
-
-    const result = await client.graphql({
-      query: `
-        query GetWarehouseInventory($first: Int!, $after: String, $groupRef: String!) {
-          virtualPositions(
-            first: $first
-            after: $after
-            groupRef: $groupRef
-            status: ["ACTIVE", "AVAILABLE"]
-          ) {
-            edges {
-              node {
-                id
-                productRef
-                quantity
-                groupRef
-                status
-              }
-              cursor
-            }
-            pageInfo { hasNextPage }
-          }
-        }
-      `,
-      variables: {
-        first: 150,
-        groupRef: warehouseRef
-      },
-      pagination: {
-        maxRecords: 10000,
-        onProgress: (page, records) => {
-          process.stdout.write(`\r  Page ${page}: ${records} positions...`);
-        }
-      }
-    });
-
-    results.push({
-      warehouse: warehouseRef,
-      positions: result.data.virtualPositions.edges,
-      stats: result.extensions.autoPagination
-    });
-
-    console.log(`\n  ✅ ${result.extensions.autoPagination.totalRecords} positions exported`);
-  }
-
-  return results;
-}
-
-// Usage
-const warehouseData = await exportWarehouseInventory(['WH-EAST', 'WH-WEST', 'WH-CENTRAL']);
-```
-
-### Example 2: Recent Orders with Items
-
-```typescript
-async function getRecentOrdersWithItems(daysSince: number) {
-  const fromDate = new Date();
-  fromDate.setDate(fromDate.getDate() - daysSince);
-
-  const result = await client.graphql({
-    query: `
-      query GetRecentOrders($first: Int!, $after: String, $from: DateTime!) {
-        orders(
-          first: $first
-          after: $after
-          createdOn: { from: $from }
-          status: ["BOOKED", "ALLOCATED"]
-        ) {
-          edges {
-            node {
-              id
-              ref
-              status
-              createdOn
-              totalPrice
-              items {
-                edges {
-                  node {
-                    id
-                    productRef
-                    quantity
-                    price
-                  }
-                }
-              }
-            }
-            cursor
-          }
-          pageInfo { hasNextPage }
-        }
-      }
-    `,
-    variables: {
-      first: 25,  // Small page size for complex query
-      from: fromDate.toISOString()
-    },
-    pagination: {
-      maxPages: 40,
-      maxRecords: 1000,
-      delayMs: 100,  // Rate limiting for complex query
-      onProgress: (page, records) => {
-        console.log(`📄 Fetched ${records} orders across ${page} pages`);
-      }
-    }
-  });
-
-  return result.data.orders.edges;
-}
-
-// Usage
-const orders = await getRecentOrdersWithItems(7);  // Last 7 days
-console.log(`Total orders: ${orders.length}`);
-```
-
----
-
-## Key Takeaways
-
-✅ **Nested connections**: Use `connectionPath` with dot notation
-✅ **Multiple connections**: Specify which to paginate with `connectionPath`
-✅ **Fragments**: Work seamlessly with auto-pagination
-✅ **Aliases**: Update `connectionPath` to match alias
-✅ **Custom variables**: SDK auto-detects `$*First`, `$*After` patterns
-✅ **Filtering**: Combine filters with pagination variables
-✅ **Backward pagination**: Use `direction: 'backward'` with `$last`/`$before`
-
----
-
-## Next Steps
-
-Learn how to integrate pagination with other SDK services:
-
-**Continue to:** [Module 5: SDK Integration →](./auto-pagination-05-sdk-integration.md)
-
----
-
-[← Back to Index](../../advanced-services/advanced-services-readme.md) | [← Previous: Configuration](./auto-pagination-03-configuration.md) | [Next: SDK Integration →](./auto-pagination-05-sdk-integration.md)
+# Module 4: Advanced Query Patterns
+
+> **Learning Objective:** Master complex pagination scenarios including nested connections, fragments, aliases, and multiple connections.
+>
+> **Level:** Advanced
+
+## Table of Contents
+
+1. [Nested Connections](#nested-connections)
+2. [Multiple Connections](#multiple-connections)
+3. [Using Fragments](#using-fragments)
+4. [Query Aliases](#query-aliases)
+5. [Inline Fragments](#inline-fragments)
+6. [Custom Variable Names](#custom-variable-names)
+7. [Filtering with Pagination](#filtering-with-pagination)
+8. [Backward Pagination](#backward-pagination)
+
+---
+
+## Nested Connections
+
+Paginate nested collections (e.g., order → items).
+
+### Example: Order Items Pagination
+
+```typescript
+const result = await client.graphql({
+  query: `
+    query GetOrderItems($orderId: ID!, $first: Int!, $after: String) {
+      order(id: $orderId) {
+        id
+        ref
+        status
+        items(first: $first, after: $after) {
+          edges {
+            node {
+              id
+              productRef
+              quantity
+              price
+            }
+            cursor
+          }
+          pageInfo {
+            hasNextPage
+          }
+        }
+      }
+    }
+  `,
+  variables: {
+    orderId: 'ORDER-123',
+    first: 50
+  },
+  pagination: {
+    connectionPath: 'order.items',  // Target nested connection!
+    maxPages: 20,
+    maxRecords: 1000
+  }
+});
+
+// Access nested items
+const items = result.data.order.items.edges;
+console.log(`Total items: ${result.extensions.autoPagination.totalRecords}`);
+```
+
+### Multi-Level Nesting
+
+```typescript
+// Query with multiple nesting levels
+const result = await client.graphql({
+  query: `
+    query GetFulfilmentArticles($fulfilmentId: ID!, $first: Int!, $after: String) {
+      fulfilment(id: $fulfilmentId) {
+        id
+        order {
+          id
+          ref
+        }
+        articles(first: $first, after: $after) {
+          edges {
+            node {
+              id
+              requestedQuantity
+            }
+            cursor
+          }
+          pageInfo {
+            hasNextPage
+          }
+        }
+      }
+    }
+  `,
+  variables: { fulfilmentId: 'FUL-456', first: 30 },
+  pagination: {
+    connectionPath: 'fulfilment.articles',
+    maxPages: 15
+  }
+});
+```
+
+---
+
+## Multiple Connections
+
+Handle queries with multiple pageable connections.
+
+### Pattern 1: Paginate One Connection
+
+```typescript
+// Multiple connections - paginate only locations
+const result = await client.graphql({
+  query: `
+    query GetMultiple($first: Int!, $after: String) {
+      locations(first: $first, after: $after) {
+        edges {
+          node { id ref name }
+          cursor
+        }
+        pageInfo { hasNextPage }
+      }
+      products(first: 10) {  # Not paginated - fixed size
+        edges {
+          node { id ref }
+        }
+      }
+    }
+  `,
+  variables: { first: 100 },
+  pagination: {
+    connectionPath: 'locations',  // Paginate locations only
+    maxPages: 50
+  }
+});
+
+// result.data.locations.edges - fully paginated
+// result.data.products.edges - only first 10 items
+```
+
+### Pattern 2: Sequential Pagination
+
+Paginate multiple connections sequentially (separate queries):
+
+```typescript
+// Fetch all locations
+const locationsResult = await client.graphql({
+  query: `
+    query GetLocations($first: Int!, $after: String) {
+      locations(first: $first, after: $after) {
+        edges {
+          node { id ref }
+          cursor
+        }
+        pageInfo { hasNextPage }
+      }
+    }
+  `,
+  variables: { first: 100 },
+  pagination: { maxRecords: 5000 }
+});
+
+// Then fetch all products
+const productsResult = await client.graphql({
+  query: `
+    query GetProducts($first: Int!, $after: String) {
+      products(first: $first, after: $after) {
+        edges {
+          node { id ref }
+          cursor
+        }
+        pageInfo { hasNextPage }
+      }
+    }
+  `,
+  variables: { first: 100 },
+  pagination: { maxRecords: 10000 }
+});
+```
+
+---
+
+## Using Fragments
+
+Auto-pagination works seamlessly with GraphQL fragments.
+
+### Named Fragments
+
+```typescript
+const result = await client.graphql({
+  query: `
+    fragment LocationFields on Location {
+      id
+      ref
+      name
+      type
+      status
+      defaultCarrier
+    }
+
+    query GetLocations($first: Int!, $after: String) {
+      locations(first: $first, after: $after) {
+        edges {
+          node {
+            ...LocationFields
+          }
+          cursor
+        }
+        pageInfo {
+          hasNextPage
+        }
+      }
+    }
+  `,
+  variables: { first: 100 },
+  pagination: { maxPages: 50 }
+});
+```
+
+### Nested Fragments
+
+```typescript
+const result = await client.graphql({
+  query: `
+    fragment ProductBasic on Product {
+      id
+      ref
+      type
+      gtin
+    }
+
+    fragment ProductDetails on Product {
+      ...ProductBasic
+      status
+      createdOn
+      updatedOn
+    }
+
+    query GetProducts($first: Int!, $after: String) {
+      products(first: $first, after: $after) {
+        edges {
+          node {
+            ...ProductDetails
+          }
+          cursor
+        }
+        pageInfo {
+          hasNextPage
+        }
+      }
+    }
+  `,
+  variables: { first: 75 },
+  pagination: { maxRecords: 5000 }
+});
+```
+
+---
+
+## Query Aliases
+
+Use aliases to rename fields in responses.
+
+### Basic Aliases
+
+```typescript
+const result = await client.graphql({
+  query: `
+    query GetLocations($first: Int!, $after: String) {
+      allLocations: locations(first: $first, after: $after) {
+        edges {
+          node {
+            locationId: id
+            locationRef: ref
+            locationName: name
+          }
+          cursor
+        }
+        pageInfo {
+          hasNextPage
+        }
+      }
+    }
+  `,
+  variables: { first: 100 },
+  pagination: {
+    connectionPath: 'allLocations',  // Use the alias!
+    maxPages: 50
+  }
+});
+
+// Access via alias
+const locations = result.data.allLocations.edges;
+console.log(locations[0].node.locationName);  // Aliased field
+```
+
+### Multiple Queries with Aliases
+
+```typescript
+const result = await client.graphql({
+  query: `
+    query GetData($first: Int!, $after: String) {
+      activeLocations: locations(first: $first, after: $after, status: "ACTIVE") {
+        edges {
+          node { id ref status }
+          cursor
+        }
+        pageInfo { hasNextPage }
+      }
+      inactiveLocations: locations(first: $first, status: "INACTIVE") {
+        edges {
+          node { id ref status }
+        }
+      }
+    }
+  `,
+  variables: { first: 100 },
+  pagination: {
+    connectionPath: 'activeLocations',  // Paginate only active
+    maxPages: 50
+  }
+});
+```
+
+---
+
+## Inline Fragments
+
+Use inline fragments for interface/union types.
+
+```typescript
+const result = await client.graphql({
+  query: `
+    query GetProducts($first: Int!, $after: String) {
+      products(first: $first, after: $after) {
+        edges {
+          node {
+            id
+            ref
+            ... on StandardProduct {
+              gtin
+              attributes {
+                name
+                value
+              }
+            }
+            ... on VariantProduct {
+              gtin
+              options {
+                name
+                value
+              }
+            }
+          }
+          cursor
+        }
+        pageInfo {
+          hasNextPage
+        }
+      }
+    }
+  `,
+  variables: { first: 75 },
+  pagination: { maxPages: 50 }
+});
+```
+
+---
+
+## Custom Variable Names
+
+SDK detects pagination variables even with custom names.
+
+### Pattern Detection
+
+SDK recognizes these patterns:
+- `$first` or `$*First` (e.g., `$itemsFirst`)
+- `$after` or `$*After` (e.g., `$itemsAfter`)
+- `$last` or `$*Last` (e.g., `$itemsLast`)
+- `$before` or `$*Before` (e.g., `$itemsBefore`)
+
+### Example with Custom Names
+
+```typescript
+const result = await client.graphql({
+  query: `
+    query GetItems($itemsFirst: Int!, $itemsAfter: String) {
+      items(first: $itemsFirst, after: $itemsAfter) {
+        edges {
+          node { id ref }
+          cursor
+        }
+        pageInfo { hasNextPage }
+      }
+    }
+  `,
+  variables: { itemsFirst: 100 },  // Custom variable name
+  pagination: { maxPages: 50 }
+  // SDK automatically detects $itemsFirst and $itemsAfter!
+});
+```
+
+---
+
+## Filtering with Pagination
+
+Combine filters with pagination for targeted queries.
+
+### Date Range Filtering
+
+```typescript
+const result = await client.graphql({
+  query: `
+    query GetRecentOrders($first: Int!, $after: String, $from: DateTime!, $to: DateTime!) {
+      orders(
+        first: $first
+        after: $after
+        createdOn: { from: $from, to: $to }
+      ) {
+        edges {
+          node {
+            id
+            ref
+            status
+            createdOn
+          }
+          cursor
+        }
+        pageInfo { hasNextPage }
+      }
+    }
+  `,
+  variables: {
+    first: 100,
+    from: '2024-01-01T00:00:00Z',
+    to: '2024-12-31T23:59:59Z'
+  },
+  pagination: { maxRecords: 10000 }
+});
+```
+
+### Status Filtering
+
+```typescript
+const result = await client.graphql({
+  query: `
+    query GetActivePositions($first: Int!, $after: String, $status: [String!]) {
+      virtualPositions(
+        first: $first
+        after: $after
+        status: $status
+      ) {
+        edges {
+          node {
+            id
+            ref
+            productRef
+            quantity
+            status
+          }
+          cursor
+        }
+        pageInfo { hasNextPage }
+      }
+    }
+  `,
+  variables: {
+    first: 150,
+    status: ['ACTIVE', 'AVAILABLE']
+  },
+  pagination: { maxPages: 100 }
+});
+```
+
+### Reference List Filtering
+
+```typescript
+const result = await client.graphql({
+  query: `
+    query GetSpecificProducts($first: Int!, $after: String, $refs: [String!]!) {
+      products(
+        first: $first
+        after: $after
+        ref: $refs
+      ) {
+        edges {
+          node {
+            id
+            ref
+            type
+          }
+          cursor
+        }
+        pageInfo { hasNextPage }
+      }
+    }
+  `,
+  variables: {
+    first: 100,
+    refs: ['PROD-001', 'PROD-002', 'PROD-003']
+  },
+  pagination: { maxPages: 10 }
+});
+```
+
+---
+
+## Backward Pagination
+
+Paginate in reverse order using `last` and `before`.
+
+### Basic Backward Pagination
+
+```typescript
+const result = await client.graphql({
+  query: `
+    query GetLatestItems($last: Int!, $before: String) {
+      items(last: $last, before: $before) {
+        edges {
+          node { id ref createdOn }
+          cursor
+        }
+        pageInfo {
+          hasPreviousPage
+        }
+      }
+    }
+  `,
+  variables: { last: 100 },
+  pagination: {
+    direction: 'backward',  // Required!
+    maxPages: 50
+  }
+});
+
+// Items are in reverse chronological order
+```
+
+### Reverse then Forward
+
+Get last page first, then paginate backward:
+
+```typescript
+// Step 1: Get cursor of last item
+const lastPageResult = await client.graphql({
+  query: `
+    query GetLastPage($last: Int!) {
+      items(last: $last) {
+        edges {
+          cursor
+          node { id ref }
+        }
+        pageInfo { hasPreviousPage }
+      }
+    }
+  `,
+  variables: { last: 1 },
+  pagination: { enabled: false }  // Disable auto-pagination
+});
+
+const lastCursor = lastPageResult.data.items.edges[0]?.cursor;
+
+// Step 2: Paginate backward from last cursor
+const backwardResult = await client.graphql({
+  query: `
+    query GetItemsBackward($last: Int!, $before: String) {
+      items(last: $last, before: $before) {
+        edges {
+          node { id ref }
+          cursor
+        }
+        pageInfo { hasPreviousPage }
+      }
+    }
+  `,
+  variables: { last: 100, before: lastCursor },
+  pagination: {
+    direction: 'backward',
+    maxPages: 50
+  }
+});
+```
+
+---
+
+## Complete Real-World Examples
+
+### Example 1: Multi-Warehouse Inventory Export
+
+```typescript
+async function exportWarehouseInventory(warehouseRefs: string[]) {
+  const results = [];
+
+  for (const warehouseRef of warehouseRefs) {
+    console.log(`\n📦 Exporting inventory for ${warehouseRef}...`);
+
+    const result = await client.graphql({
+      query: `
+        query GetWarehouseInventory($first: Int!, $after: String, $groupRef: String!) {
+          virtualPositions(
+            first: $first
+            after: $after
+            groupRef: $groupRef
+            status: ["ACTIVE", "AVAILABLE"]
+          ) {
+            edges {
+              node {
+                id
+                productRef
+                quantity
+                groupRef
+                status
+              }
+              cursor
+            }
+            pageInfo { hasNextPage }
+          }
+        }
+      `,
+      variables: {
+        first: 150,
+        groupRef: warehouseRef
+      },
+      pagination: {
+        maxRecords: 10000,
+        onProgress: (page, records) => {
+          process.stdout.write(`\r  Page ${page}: ${records} positions...`);
+        }
+      }
+    });
+
+    results.push({
+      warehouse: warehouseRef,
+      positions: result.data.virtualPositions.edges,
+      stats: result.extensions.autoPagination
+    });
+
+    console.log(`\n  ✅ ${result.extensions.autoPagination.totalRecords} positions exported`);
+  }
+
+  return results;
+}
+
+// Usage
+const warehouseData = await exportWarehouseInventory(['WH-EAST', 'WH-WEST', 'WH-CENTRAL']);
+```
+
+### Example 2: Recent Orders with Items
+
+```typescript
+async function getRecentOrdersWithItems(daysSince: number) {
+  const fromDate = new Date();
+  fromDate.setDate(fromDate.getDate() - daysSince);
+
+  const result = await client.graphql({
+    query: `
+      query GetRecentOrders($first: Int!, $after: String, $from: DateTime!) {
+        orders(
+          first: $first
+          after: $after
+          createdOn: { from: $from }
+          status: ["BOOKED", "ALLOCATED"]
+        ) {
+          edges {
+            node {
+              id
+              ref
+              status
+              createdOn
+              totalPrice
+              items {
+                edges {
+                  node {
+                    id
+                    productRef
+                    quantity
+                    price
+                  }
+                }
+              }
+            }
+            cursor
+          }
+          pageInfo { hasNextPage }
+        }
+      }
+    `,
+    variables: {
+      first: 25,  // Small page size for complex query
+      from: fromDate.toISOString()
+    },
+    pagination: {
+      maxPages: 40,
+      maxRecords: 1000,
+      delayMs: 100,  // Rate limiting for complex query
+      onProgress: (page, records) => {
+        console.log(`📄 Fetched ${records} orders across ${page} pages`);
+      }
+    }
+  });
+
+  return result.data.orders.edges;
+}
+
+// Usage
+const orders = await getRecentOrdersWithItems(7);  // Last 7 days
+console.log(`Total orders: ${orders.length}`);
+```
+
+---
+
+## Key Takeaways
+
+✅ **Nested connections**: Use `connectionPath` with dot notation
+✅ **Multiple connections**: Specify which to paginate with `connectionPath`
+✅ **Fragments**: Work seamlessly with auto-pagination
+✅ **Aliases**: Update `connectionPath` to match alias
+✅ **Custom variables**: SDK auto-detects `$*First`, `$*After` patterns
+✅ **Filtering**: Combine filters with pagination variables
+✅ **Backward pagination**: Use `direction: 'backward'` with `$last`/`$before`
+
+---
+
+## Next Steps
+
+Learn how to integrate pagination with other SDK services:
+
+**Continue to:** [Module 5: SDK Integration →](./auto-pagination-05-sdk-integration.md)
+
+---
+
+[← Back to Index](../../advanced-services/advanced-services-readme.md) | [← Previous: Configuration](./auto-pagination-03-configuration.md) | [Next: SDK Integration →](./auto-pagination-05-sdk-integration.md)