@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

package/docs/02-CORE-GUIDES/auto-pagination/modules/auto-pagination-02-quick-start.md

@@ -1,713 +1,713 @@
-# Module 2: Quick Start
-
-> **Learning Objective:** Write and run your first auto-paginated query using real Fluent schema fields.
->
-> **Level:** Beginner
-
-## Table of Contents
-
-1. [Prerequisites](#prerequisites)
-2. [Step 1: Discover Schema Fields](#step-1-discover-schema-fields)
-3. [Step 2: Your First Auto-Paginated Query](#step-2-your-first-auto-paginated-query)
-4. [Step 3: Understanding the Response](#step-3-understanding-the-response)
-5. [Step 4: Add Safety Limits](#step-4-add-safety-limits)
-6. [Common Mistakes to Avoid](#common-mistakes-to-avoid)
-7. [Next Steps](#next-steps)
-
----
-
-## Prerequisites
-
-Before starting, ensure you have:
-
-```bash
-# 1. SDK installed
-npm install @fluentcommerce/fc-connect-sdk
-
-# 2. Environment variables set (.env file)
-FLUENT_BASE_URL=https://your-account.api.fluentretail.com
-FLUENT_CLIENT_ID=your-client-id
-FLUENT_CLIENT_SECRET=your-client-secret
-FLUENT_RETAILER_ID=your-retailer-id
-```
-
----
-
-## Step 1: Discover Schema Fields
-
-**⚠️ CRITICAL:** Never guess field names! Always introspect the schema first to discover available fields.
-
-### Option A: Use SDK CLI Tool (Recommended)
-
-```bash
-npx fc-connect introspect-schema \
-  --endpoint https://your-account.api.fluentretail.com/graphql \
-  --client-id your-client-id \
-  --client-secret your-client-secret \
-  --output schema.json
-
-# Output: schema.json with all types, fields, and descriptions
-```
-
-### Option B: Use GraphQL Playground
-
-1. Navigate to your Fluent GraphQL endpoint in browser
-2. Open "Docs" sidebar
-3. Search for entity (e.g., `VirtualPosition`)
-4. View available fields and their types
-
-### Real Schema Example: VirtualPosition
-
-Based on actual Fluent Commerce schema introspection:
-
-```typescript
-// ✅ REAL FIELDS (from schema.json)
-type VirtualPosition {
-  id: ID!
-  ref: String!
-  productRef: String
-  quantity: Int
-  groupRef: String
-  status: String
-  type: String
-  createdOn: DateTime
-  updatedOn: DateTime
-  catalogue: VirtualCatalogue
-  attributes: [Attribute]
-}
-
-// ❌ DON'T GUESS FIELDS LIKE:
-// name, title, description - these DON'T exist on VirtualPosition!
-```
-
----
-
-## Step 2: Your First Auto-Paginated Query
-
-Create a file `paginate-inventory.ts`:
-
-```typescript
-/**
- * Example: Fetch all virtual positions (inventory) with auto-pagination
- * Uses REAL schema fields verified via introspection
- */
-
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-import * as dotenv from 'dotenv';
-
-// Load environment variables
-dotenv.config();
-
-async function paginateInventory() {
-  // Create client (auto-detects Node.js/Deno/Versori context)
-  const client = await createClient({
-    config: {
-      baseUrl: process.env.FLUENT_BASE_URL!,
-      clientId: process.env.FLUENT_CLIENT_ID!,
-      clientSecret: process.env.FLUENT_CLIENT_SECRET!,
-      retailerId: process.env.FLUENT_RETAILER_ID!,
-    },
-  });
-
-  console.log('Starting inventory pagination...\n');
-
-  // ✅ Query using REAL schema fields
-  const result = await client.graphql({
-    query: `
-      query GetVirtualPositions($first: Int!, $after: String) {
-        virtualPositions(first: $first, after: $after) {
-          edges {
-            node {
-              id
-              ref           # Real field ✓ - Business reference (required)
-              productRef    # Real field ✓
-              quantity      # Real field ✓
-              groupRef      # Real field ✓
-              status        # Real field ✓
-            }
-            cursor
-          }
-          pageInfo {
-            hasNextPage
-          }
-        }
-      }
-    `,
-    variables: {
-      first: 100, // Page size: 100 records per page
-    },
-  });
-
-  // Auto-pagination automatically fetches ALL pages and merges them!
-  const positions = result.data.virtualPositions.edges;
-  const metadata = result.extensions.autoPagination;
-
-  // Display results
-  console.log('✅ Pagination Complete!\n');
-  console.log(`Total Records: ${metadata.totalRecords}`);
-  console.log(`Total Pages: ${metadata.totalPages}`);
-  console.log(`Truncated: ${metadata.truncated}`);
-  if (metadata.truncated) {
-    console.log(`Truncation Reason: ${metadata.truncationReason}\n`);
-  } else {
-    console.log('');
-  }
-
-  // Process first 5 records
-  console.log('Sample Records:');
-  positions.slice(0, 5).forEach((edge, index) => {
-    const { id, productRef, quantity, groupRef, status } = edge.node;
-    console.log(
-      `${index + 1}. Product ${productRef}: ${quantity} units at ${groupRef} (${status})`
-    );
-  });
-}
-
-// Run the pagination
-paginateInventory()
-  .then(() => console.log('\n✅ Done!'))
-  .catch(error => {
-    console.error('❌ Error:', error.message);
-    process.exit(1);
-  });
-```
-
-### Run It
-
-```bash
-# Using ts-node
-npx ts-node paginate-inventory.ts
-
-# Or compile and run
-npx tsc paginate-inventory.ts
-node paginate-inventory.js
-```
-
-### Expected Output
-
-```
-Starting inventory pagination...
-
-✅ Pagination Complete!
-
-Total Records: 1487
-Total Pages: 15
-Truncated: false
-
-Sample Records:
-1. Product SKU-001: 150 units at WH-EAST (ACTIVE)
-2. Product SKU-002: 75 units at WH-WEST (ACTIVE)
-3. Product SKU-003: 200 units at WH-CENTRAL (ACTIVE)
-4. Product SKU-004: 0 units at WH-EAST (DEPLETED)
-5. Product SKU-005: 450 units at WH-WEST (ACTIVE)
-
-✅ Done!
-```
-
----
-
-## Step 3: Understanding the Response
-
-### Response Structure
-
-```typescript
-{
-  data: {
-    virtualPositions: {
-      edges: [
-        {
-          node: {
-            id: "1234",
-            productRef: "SKU-001",
-            quantity: 150,
-            groupRef: "WH-EAST",
-            status: "ACTIVE"
-          },
-          cursor: "Y3Vyc29yOjE="  // Opaque cursor
-        },
-        // ... all pages merged here automatically!
-      ],
-      pageInfo: {
-        hasNextPage: false  // For forward pagination, false at end
-      }
-    }
-  },
-  extensions: {
-    autoPagination: {
-      totalPages: 15,           // SDK made 15 requests
-      totalRecords: 1487,       // Total items across all pages
-      truncated: false,         // false = fetched everything
-      truncationReason: undefined,  // "maxPages" | "maxRecords" | "timeout" if truncated
-      direction: "forward"      // Pagination direction used
-    }
-  }
-}
-
-// Note: duration/timeElapsed NOT included - calculate using Date.now() if needed
-```
-
-### Key Points
-
-1. **All Pages Merged**: `edges` array contains items from ALL pages
-2. **Deduplication**: SDK automatically removes duplicates by node.id
-3. **Metadata**: `extensions.autoPagination` provides pagination stats
-4. **hasNextPage**: Always `false` at the end (SDK fetched everything)
-
----
-
-## Step 4: Add Safety Limits
-
-**⚠️ IMPORTANT:** Always set safety limits to prevent runaway queries!
-
-```typescript
-const result = await client.graphql({
-  query: virtualPositionsQuery,
-  variables: { first: 100 },
-
-  // Safety limits (OR-logic: first limit reached stops pagination)
-  pagination: {
-    maxPages: 50, // Stop after 50 pages
-    maxRecords: 5000, // OR stop after 5000 records
-    timeoutMs: 60000, // OR stop after 60 seconds
-  },
-});
-
-// Check if truncated
-if (result.extensions.autoPagination.truncated) {
-  console.warn('⚠️ Results truncated!');
-  console.warn(`Reason: ${result.extensions.autoPagination.truncationReason}`);
-  // Possible reasons: "maxPages" | "maxRecords" | "timeout"
-}
-```
-
-### Recommended Safety Limits by Use Case
-
-| Use Case                | maxPages | maxRecords | timeoutMs | Rationale                          |
-| ----------------------- | -------- | ---------- | --------- | ---------------------------------- |
-| **Testing/Development** | 5        | 500        | 10000     | Fast feedback, avoid large pulls   |
-| **Production Export**   | 100      | 10000      | 300000    | Conservative limits for safety     |
-| **Background Job**      | 500      | 50000      | 600000    | Higher limits for batch processing |
-| **Real-Time API**       | 10       | 1000       | 5000      | Fast response for user-facing APIs |
-
----
-
-## Common Mistakes to Avoid
-
-### ❌ Mistake 1: Guessing Field Names
-
-```typescript
-// ❌ WRONG: Guessing fields that don't exist
-query GetOrders($first: Int!, $after: String) {
-  orders(first: $first, after: $after) {
-    edges {
-      node {
-        id
-        name           # ❌ Orders don't have "name"
-        description    # ❌ Orders don't have "description"
-      }
-    }
-  }
-}
-
-// ✅ CORRECT: Use real schema fields
-query GetOrders($first: Int!, $after: String) {
-  orders(first: $first, after: $after) {
-    edges {
-      node {
-        id
-        ref            # ✓ Real field
-        status         # ✓ Real field
-        totalPrice     # ✓ Real field
-      }
-    }
-  }
-}
-```
-
-### ❌ Mistake 2: Forgetting Pagination Variables
-
-```typescript
-// ❌ WRONG: No pagination variables = no auto-pagination!
-query GetVirtualPositions {
-  virtualPositions(first: 100) {  # Hardcoded, won't paginate
-    edges { node { id ref productRef quantity } }
-  }
-}
-
-// ✅ CORRECT: Include $first and $after variables
-query GetVirtualPositions($first: Int!, $after: String) {
-  virtualPositions(first: $first, after: $after) {
-    edges { node { id ref productRef quantity } }
-    pageInfo { hasNextPage }
-  }
-}
-```
-
-### ❌ Mistake 3: Missing pageInfo
-
-```typescript
-// ❌ WRONG: Missing pageInfo.hasNextPage
-query GetVirtualPositions($first: Int!, $after: String) {
-  virtualPositions(first: $first, after: $after) {
-    edges {
-      node { id ref productRef quantity }
-      cursor
-    }
-    # Missing pageInfo!
-  }
-}
-
-// ✅ CORRECT: Include pageInfo with hasNextPage
-query GetVirtualPositions($first: Int!, $after: String) {
-  virtualPositions(first: $first, after: $after) {
-    edges {
-      node { id ref productRef quantity }
-      cursor
-    }
-    pageInfo {
-      hasNextPage  # Required for pagination detection!
-    }
-  }
-}
-```
-
-### ❌ Mistake 4: No Safety Limits
-
-### ❌ Mistake 5: Missing Backward Pagination Requirements
-
-```graphql
-// ❌ WRONG: Using backward direction without required variables
-query GetItems($last: Int!, $before: String) {
-  items(last: $last, before: $before) {
-    edges { node { id } cursor }
-    # Missing pageInfo.hasPreviousPage
-  }
-}
-
-// ✅ CORRECT: Include hasPreviousPage for backward pagination
-query GetItems($last: Int!, $before: String) {
-  items(last: $last, before: $before) {
-    edges { node { id } cursor }
-    pageInfo { hasPreviousPage }
-  }
-}
-```
-
-```typescript
-// ❌ RISKY: No limits, could fetch 100,000+ records
-const result = await client.graphql({
-  query,
-  variables: { first: 100 },
-  // No pagination limits!
-});
-
-// ✅ SAFE: Always set safety limits
-const result = await client.graphql({
-  query,
-  variables: { first: 100 },
-  pagination: {
-    maxPages: 100,
-    maxRecords: 10000,
-    timeoutMs: 60000,
-  },
-});
-```
-
----
-
-## Quick Reference: Verified Entity Queries
-
-Here are copy-paste ready queries for common Fluent entities (all fields verified via schema introspection):
-
-### Virtual Positions (Inventory)
-
-```graphql
-query GetVirtualPositions($first: Int!, $after: String) {
-  virtualPositions(first: $first, after: $after) {
-    edges {
-      node {
-        id
-        ref
-        productRef
-        quantity
-        groupRef
-        status
-        type
-        createdOn
-        updatedOn
-      }
-      cursor
-    }
-    pageInfo {
-      hasNextPage
-    }
-  }
-}
-```
-
-### Locations
-
-```graphql
-query GetLocations($first: Int!, $after: String) {
-  locations(first: $first, after: $after) {
-    edges {
-      node {
-        id
-        ref
-        name
-        type
-        status
-        defaultCarrier
-      }
-      cursor
-    }
-    pageInfo {
-      hasNextPage
-    }
-  }
-}
-```
-
-### Products
-
-```graphql
-query GetProducts($first: Int!, $after: String) {
-  products(first: $first, after: $after) {
-    edges {
-      node {
-        id
-        ref
-        type
-        status
-        gtin
-      }
-      cursor
-    }
-    pageInfo {
-      hasNextPage
-    }
-  }
-}
-```
-
-### Orders
-
-```graphql
-query GetOrders($first: Int!, $after: String) {
-  orders(first: $first, after: $after) {
-    edges {
-      node {
-        id
-        ref
-        status
-        type
-        totalPrice
-        totalTax
-        createdOn
-        retailer {
-          id
-        }
-      }
-      cursor
-    }
-    pageInfo {
-      hasNextPage
-    }
-  }
-}
-```
-
----
-
-## Complete Working Example
-
-Save this as `examples/quick-start-complete.ts`:
-
-```typescript
-/**
- * Complete Quick Start Example
- * Demonstrates auto-pagination with real schema fields and safety limits
- */
-
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-import * as dotenv from 'dotenv';
-
-dotenv.config();
-
-async function main() {
-  // 1. Create client
-  const client = await createClient({
-    config: {
-      baseUrl: process.env.FLUENT_BASE_URL!,
-      clientId: process.env.FLUENT_CLIENT_ID!,
-      clientSecret: process.env.FLUENT_CLIENT_SECRET!,
-      retailerId: process.env.FLUENT_RETAILER_ID!,
-    },
-  });
-
-  // 2. Define query with REAL schema fields
-  const query = `
-    query GetVirtualPositions($first: Int!, $after: String) {
-      virtualPositions(first: $first, after: $after) {
-        edges {
-          node {
-            id
-            productRef
-            quantity
-            groupRef
-            status
-          }
-          cursor
-        }
-        pageInfo {
-          hasNextPage
-        }
-      }
-    }
-  `;
-
-  // 3. Execute with auto-pagination and safety limits
-  console.log('🚀 Starting pagination...\n');
-
-  const result = await client.graphql({
-    query,
-    variables: { first: 100 },
-    pagination: {
-      maxPages: 50,
-      maxRecords: 5000,
-      timeoutMs: 60000,
-      onProgress: (page, totalRecords) => {
-        process.stdout.write(`\r📄 Page ${page}: ${totalRecords} records...`);
-      },
-    },
-  });
-
-  // 4. Process results
-  console.log('\n\n✅ Pagination Complete!\n');
-
-  const { totalRecords, totalPages, truncated, truncationReason } =
-    result.extensions.autoPagination;
-
-  console.log('📊 Statistics:');
-  console.log(`   Total Records: ${totalRecords}`);
-  console.log(`   Total Pages: ${totalPages}`);
-  console.log(`   Truncated: ${truncated}${truncated ? ` (${truncationReason})` : ''}\n`);
-
-  // 5. Analyze data
-  const positions = result.data.virtualPositions.edges;
-
-  const activeCount = positions.filter(e => e.node.status === 'ACTIVE').length;
-  const totalQty = positions.reduce((sum, e) => sum + (e.node.quantity || 0), 0);
-
-  console.log('📦 Inventory Summary:');
-  console.log(`   Active Positions: ${activeCount}`);
-  console.log(`   Total Quantity: ${totalQty} units\n`);
-
-  // 6. Display sample
-  console.log('📝 Sample Records:');
-  positions.slice(0, 3).forEach((edge, i) => {
-    const { productRef, quantity, groupRef, status } = edge.node;
-    console.log(`   ${i + 1}. ${productRef}: ${quantity} units @ ${groupRef} [${status}]`);
-  });
-}
-
-main().catch(console.error);
-```
-
----
-
-## Testing Your Setup
-
-Run this test to verify everything works:
-
-```bash
-# Test connectivity and pagination
-node quick-start-complete.js
-```
-
-Expected output:
-
-```
-🚀 Starting pagination...
-
-📄 Page 15: 1487 records...
-
-✅ Pagination Complete!
-
-📊 Statistics:
-   Total Records: 1487
-   Total Pages: 15
-   Truncated: false
-
-📦 Inventory Summary:
-   Active Positions: 1342
-   Total Quantity: 245670 units
-
-📝 Sample Records:
-   1. SKU-001: 150 units @ WH-EAST [ACTIVE]
-   2. SKU-002: 75 units @ WH-WEST [ACTIVE]
-   3. SKU-003: 200 units @ WH-CENTRAL [ACTIVE]
-```
-
----
-
-## Troubleshooting
-
-### Problem: "Field 'X' doesn't exist on type 'Y'"
-
-**Solution:** Field name is wrong. Introspect schema first:
-
-```bash
-npx fc-connect introspect-schema --endpoint YOUR_URL --output schema.json
-# Then search schema.json for correct field names
-```
-
-### Problem: "Variable '$first' is never used"
-
-**Solution:** Include variable in query arguments:
-
-```graphql
-# ❌ WRONG
-query GetItems($first: Int!) {
-  items { ... }  # Not using $first
-}
-
-# ✅ CORRECT
-query GetItems($first: Int!) {
-  items(first: $first) { ... }  # Using $first
-}
-```
-
-### Problem: Auto-pagination not activating
-
-**Solution:** Ensure query has pagination variables:
-
-```typescript
-// Check this returns true
-const hasVariables = query.includes('$first') || query.includes('$after');
-```
-
----
-
-## Next Steps
-
-Congratulations! You've successfully implemented auto-pagination. Next:
-
-- **Learn Configuration Options:** [Module 3: Configuration →](./auto-pagination-03-configuration.md)
-- **Try Advanced Patterns:** [Module 4: Advanced Patterns →](./auto-pagination-04-advanced-patterns.md)
-- **Explore More Examples:** [Examples Directory →](../examples/)
-
----
-
-## Key Takeaways
-
-✅ **Always introspect schema** - Never guess field names
-✅ **Include pagination variables** - `$first`, `$after` in query
-✅ **Include pageInfo** - Required for pagination detection
-✅ **Set safety limits** - maxPages, maxRecords, timeoutMs
-✅ **Monitor progress** - Use onProgress callbacks
-✅ **Check truncation** - Verify `extensions.autoPagination.truncated`
-
----
-
-[← Back to Index](../../advanced-services/advanced-services-readme.md) | [← Previous: Foundations](./auto-pagination-01-foundations.md) | [Next: Configuration →](./auto-pagination-03-configuration.md)
+# Module 2: Quick Start
+
+> **Learning Objective:** Write and run your first auto-paginated query using real Fluent schema fields.
+>
+> **Level:** Beginner
+
+## Table of Contents
+
+1. [Prerequisites](#prerequisites)
+2. [Step 1: Discover Schema Fields](#step-1-discover-schema-fields)
+3. [Step 2: Your First Auto-Paginated Query](#step-2-your-first-auto-paginated-query)
+4. [Step 3: Understanding the Response](#step-3-understanding-the-response)
+5. [Step 4: Add Safety Limits](#step-4-add-safety-limits)
+6. [Common Mistakes to Avoid](#common-mistakes-to-avoid)
+7. [Next Steps](#next-steps)
+
+---
+
+## Prerequisites
+
+Before starting, ensure you have:
+
+```bash
+# 1. SDK installed
+npm install @fluentcommerce/fc-connect-sdk
+
+# 2. Environment variables set (.env file)
+FLUENT_BASE_URL=https://your-account.api.fluentretail.com
+FLUENT_CLIENT_ID=your-client-id
+FLUENT_CLIENT_SECRET=your-client-secret
+FLUENT_RETAILER_ID=your-retailer-id
+```
+
+---
+
+## Step 1: Discover Schema Fields
+
+**⚠️ CRITICAL:** Never guess field names! Always introspect the schema first to discover available fields.
+
+### Option A: Use SDK CLI Tool (Recommended)
+
+```bash
+npx fc-connect introspect-schema \
+  --endpoint https://your-account.api.fluentretail.com/graphql \
+  --client-id your-client-id \
+  --client-secret your-client-secret \
+  --output schema.json
+
+# Output: schema.json with all types, fields, and descriptions
+```
+
+### Option B: Use GraphQL Playground
+
+1. Navigate to your Fluent GraphQL endpoint in browser
+2. Open "Docs" sidebar
+3. Search for entity (e.g., `VirtualPosition`)
+4. View available fields and their types
+
+### Real Schema Example: VirtualPosition
+
+Based on actual Fluent Commerce schema introspection:
+
+```typescript
+// ✅ REAL FIELDS (from schema.json)
+type VirtualPosition {
+  id: ID!
+  ref: String!
+  productRef: String
+  quantity: Int
+  groupRef: String
+  status: String
+  type: String
+  createdOn: DateTime
+  updatedOn: DateTime
+  catalogue: VirtualCatalogue
+  attributes: [Attribute]
+}
+
+// ❌ DON'T GUESS FIELDS LIKE:
+// name, title, description - these DON'T exist on VirtualPosition!
+```
+
+---
+
+## Step 2: Your First Auto-Paginated Query
+
+Create a file `paginate-inventory.ts`:
+
+```typescript
+/**
+ * Example: Fetch all virtual positions (inventory) with auto-pagination
+ * Uses REAL schema fields verified via introspection
+ */
+
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+import * as dotenv from 'dotenv';
+
+// Load environment variables
+dotenv.config();
+
+async function paginateInventory() {
+  // Create client (auto-detects Node.js/Deno/Versori context)
+  const client = await createClient({
+    config: {
+      baseUrl: process.env.FLUENT_BASE_URL!,
+      clientId: process.env.FLUENT_CLIENT_ID!,
+      clientSecret: process.env.FLUENT_CLIENT_SECRET!,
+      retailerId: process.env.FLUENT_RETAILER_ID!,
+    },
+  });
+
+  console.log('Starting inventory pagination...\n');
+
+  // ✅ Query using REAL schema fields
+  const result = await client.graphql({
+    query: `
+      query GetVirtualPositions($first: Int!, $after: String) {
+        virtualPositions(first: $first, after: $after) {
+          edges {
+            node {
+              id
+              ref           # Real field ✓ - Business reference (required)
+              productRef    # Real field ✓
+              quantity      # Real field ✓
+              groupRef      # Real field ✓
+              status        # Real field ✓
+            }
+            cursor
+          }
+          pageInfo {
+            hasNextPage
+          }
+        }
+      }
+    `,
+    variables: {
+      first: 100, // Page size: 100 records per page
+    },
+  });
+
+  // Auto-pagination automatically fetches ALL pages and merges them!
+  const positions = result.data.virtualPositions.edges;
+  const metadata = result.extensions.autoPagination;
+
+  // Display results
+  console.log('✅ Pagination Complete!\n');
+  console.log(`Total Records: ${metadata.totalRecords}`);
+  console.log(`Total Pages: ${metadata.totalPages}`);
+  console.log(`Truncated: ${metadata.truncated}`);
+  if (metadata.truncated) {
+    console.log(`Truncation Reason: ${metadata.truncationReason}\n`);
+  } else {
+    console.log('');
+  }
+
+  // Process first 5 records
+  console.log('Sample Records:');
+  positions.slice(0, 5).forEach((edge, index) => {
+    const { id, productRef, quantity, groupRef, status } = edge.node;
+    console.log(
+      `${index + 1}. Product ${productRef}: ${quantity} units at ${groupRef} (${status})`
+    );
+  });
+}
+
+// Run the pagination
+paginateInventory()
+  .then(() => console.log('\n✅ Done!'))
+  .catch(error => {
+    console.error('❌ Error:', error.message);
+    process.exit(1);
+  });
+```
+
+### Run It
+
+```bash
+# Using ts-node
+npx ts-node paginate-inventory.ts
+
+# Or compile and run
+npx tsc paginate-inventory.ts
+node paginate-inventory.js
+```
+
+### Expected Output
+
+```
+Starting inventory pagination...
+
+✅ Pagination Complete!
+
+Total Records: 1487
+Total Pages: 15
+Truncated: false
+
+Sample Records:
+1. Product SKU-001: 150 units at WH-EAST (ACTIVE)
+2. Product SKU-002: 75 units at WH-WEST (ACTIVE)
+3. Product SKU-003: 200 units at WH-CENTRAL (ACTIVE)
+4. Product SKU-004: 0 units at WH-EAST (DEPLETED)
+5. Product SKU-005: 450 units at WH-WEST (ACTIVE)
+
+✅ Done!
+```
+
+---
+
+## Step 3: Understanding the Response
+
+### Response Structure
+
+```typescript
+{
+  data: {
+    virtualPositions: {
+      edges: [
+        {
+          node: {
+            id: "1234",
+            productRef: "SKU-001",
+            quantity: 150,
+            groupRef: "WH-EAST",
+            status: "ACTIVE"
+          },
+          cursor: "Y3Vyc29yOjE="  // Opaque cursor
+        },
+        // ... all pages merged here automatically!
+      ],
+      pageInfo: {
+        hasNextPage: false  // For forward pagination, false at end
+      }
+    }
+  },
+  extensions: {
+    autoPagination: {
+      totalPages: 15,           // SDK made 15 requests
+      totalRecords: 1487,       // Total items across all pages
+      truncated: false,         // false = fetched everything
+      truncationReason: undefined,  // "maxPages" | "maxRecords" | "timeout" if truncated
+      direction: "forward"      // Pagination direction used
+    }
+  }
+}
+
+// Note: duration/timeElapsed NOT included - calculate using Date.now() if needed
+```
+
+### Key Points
+
+1. **All Pages Merged**: `edges` array contains items from ALL pages
+2. **Deduplication**: SDK automatically removes duplicates by node.id
+3. **Metadata**: `extensions.autoPagination` provides pagination stats
+4. **hasNextPage**: Always `false` at the end (SDK fetched everything)
+
+---
+
+## Step 4: Add Safety Limits
+
+**⚠️ IMPORTANT:** Always set safety limits to prevent runaway queries!
+
+```typescript
+const result = await client.graphql({
+  query: virtualPositionsQuery,
+  variables: { first: 100 },
+
+  // Safety limits (OR-logic: first limit reached stops pagination)
+  pagination: {
+    maxPages: 50, // Stop after 50 pages
+    maxRecords: 5000, // OR stop after 5000 records
+    timeoutMs: 60000, // OR stop after 60 seconds
+  },
+});
+
+// Check if truncated
+if (result.extensions.autoPagination.truncated) {
+  console.warn('⚠️ Results truncated!');
+  console.warn(`Reason: ${result.extensions.autoPagination.truncationReason}`);
+  // Possible reasons: "maxPages" | "maxRecords" | "timeout"
+}
+```
+
+### Recommended Safety Limits by Use Case
+
+| Use Case                | maxPages | maxRecords | timeoutMs | Rationale                          |
+| ----------------------- | -------- | ---------- | --------- | ---------------------------------- |
+| **Testing/Development** | 5        | 500        | 10000     | Fast feedback, avoid large pulls   |
+| **Production Export**   | 100      | 10000      | 300000    | Conservative limits for safety     |
+| **Background Job**      | 500      | 50000      | 600000    | Higher limits for batch processing |
+| **Real-Time API**       | 10       | 1000       | 5000      | Fast response for user-facing APIs |
+
+---
+
+## Common Mistakes to Avoid
+
+### ❌ Mistake 1: Guessing Field Names
+
+```typescript
+// ❌ WRONG: Guessing fields that don't exist
+query GetOrders($first: Int!, $after: String) {
+  orders(first: $first, after: $after) {
+    edges {
+      node {
+        id
+        name           # ❌ Orders don't have "name"
+        description    # ❌ Orders don't have "description"
+      }
+    }
+  }
+}
+
+// ✅ CORRECT: Use real schema fields
+query GetOrders($first: Int!, $after: String) {
+  orders(first: $first, after: $after) {
+    edges {
+      node {
+        id
+        ref            # ✓ Real field
+        status         # ✓ Real field
+        totalPrice     # ✓ Real field
+      }
+    }
+  }
+}
+```
+
+### ❌ Mistake 2: Forgetting Pagination Variables
+
+```typescript
+// ❌ WRONG: No pagination variables = no auto-pagination!
+query GetVirtualPositions {
+  virtualPositions(first: 100) {  # Hardcoded, won't paginate
+    edges { node { id ref productRef quantity } }
+  }
+}
+
+// ✅ CORRECT: Include $first and $after variables
+query GetVirtualPositions($first: Int!, $after: String) {
+  virtualPositions(first: $first, after: $after) {
+    edges { node { id ref productRef quantity } }
+    pageInfo { hasNextPage }
+  }
+}
+```
+
+### ❌ Mistake 3: Missing pageInfo
+
+```typescript
+// ❌ WRONG: Missing pageInfo.hasNextPage
+query GetVirtualPositions($first: Int!, $after: String) {
+  virtualPositions(first: $first, after: $after) {
+    edges {
+      node { id ref productRef quantity }
+      cursor
+    }
+    # Missing pageInfo!
+  }
+}
+
+// ✅ CORRECT: Include pageInfo with hasNextPage
+query GetVirtualPositions($first: Int!, $after: String) {
+  virtualPositions(first: $first, after: $after) {
+    edges {
+      node { id ref productRef quantity }
+      cursor
+    }
+    pageInfo {
+      hasNextPage  # Required for pagination detection!
+    }
+  }
+}
+```
+
+### ❌ Mistake 4: No Safety Limits
+
+### ❌ Mistake 5: Missing Backward Pagination Requirements
+
+```graphql
+// ❌ WRONG: Using backward direction without required variables
+query GetItems($last: Int!, $before: String) {
+  items(last: $last, before: $before) {
+    edges { node { id } cursor }
+    # Missing pageInfo.hasPreviousPage
+  }
+}
+
+// ✅ CORRECT: Include hasPreviousPage for backward pagination
+query GetItems($last: Int!, $before: String) {
+  items(last: $last, before: $before) {
+    edges { node { id } cursor }
+    pageInfo { hasPreviousPage }
+  }
+}
+```
+
+```typescript
+// ❌ RISKY: No limits, could fetch 100,000+ records
+const result = await client.graphql({
+  query,
+  variables: { first: 100 },
+  // No pagination limits!
+});
+
+// ✅ SAFE: Always set safety limits
+const result = await client.graphql({
+  query,
+  variables: { first: 100 },
+  pagination: {
+    maxPages: 100,
+    maxRecords: 10000,
+    timeoutMs: 60000,
+  },
+});
+```
+
+---
+
+## Quick Reference: Verified Entity Queries
+
+Here are copy-paste ready queries for common Fluent entities (all fields verified via schema introspection):
+
+### Virtual Positions (Inventory)
+
+```graphql
+query GetVirtualPositions($first: Int!, $after: String) {
+  virtualPositions(first: $first, after: $after) {
+    edges {
+      node {
+        id
+        ref
+        productRef
+        quantity
+        groupRef
+        status
+        type
+        createdOn
+        updatedOn
+      }
+      cursor
+    }
+    pageInfo {
+      hasNextPage
+    }
+  }
+}
+```
+
+### Locations
+
+```graphql
+query GetLocations($first: Int!, $after: String) {
+  locations(first: $first, after: $after) {
+    edges {
+      node {
+        id
+        ref
+        name
+        type
+        status
+        defaultCarrier
+      }
+      cursor
+    }
+    pageInfo {
+      hasNextPage
+    }
+  }
+}
+```
+
+### Products
+
+```graphql
+query GetProducts($first: Int!, $after: String) {
+  products(first: $first, after: $after) {
+    edges {
+      node {
+        id
+        ref
+        type
+        status
+        gtin
+      }
+      cursor
+    }
+    pageInfo {
+      hasNextPage
+    }
+  }
+}
+```
+
+### Orders
+
+```graphql
+query GetOrders($first: Int!, $after: String) {
+  orders(first: $first, after: $after) {
+    edges {
+      node {
+        id
+        ref
+        status
+        type
+        totalPrice
+        totalTax
+        createdOn
+        retailer {
+          id
+        }
+      }
+      cursor
+    }
+    pageInfo {
+      hasNextPage
+    }
+  }
+}
+```
+
+---
+
+## Complete Working Example
+
+Save this as `examples/quick-start-complete.ts`:
+
+```typescript
+/**
+ * Complete Quick Start Example
+ * Demonstrates auto-pagination with real schema fields and safety limits
+ */
+
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+import * as dotenv from 'dotenv';
+
+dotenv.config();
+
+async function main() {
+  // 1. Create client
+  const client = await createClient({
+    config: {
+      baseUrl: process.env.FLUENT_BASE_URL!,
+      clientId: process.env.FLUENT_CLIENT_ID!,
+      clientSecret: process.env.FLUENT_CLIENT_SECRET!,
+      retailerId: process.env.FLUENT_RETAILER_ID!,
+    },
+  });
+
+  // 2. Define query with REAL schema fields
+  const query = `
+    query GetVirtualPositions($first: Int!, $after: String) {
+      virtualPositions(first: $first, after: $after) {
+        edges {
+          node {
+            id
+            productRef
+            quantity
+            groupRef
+            status
+          }
+          cursor
+        }
+        pageInfo {
+          hasNextPage
+        }
+      }
+    }
+  `;
+
+  // 3. Execute with auto-pagination and safety limits
+  console.log('🚀 Starting pagination...\n');
+
+  const result = await client.graphql({
+    query,
+    variables: { first: 100 },
+    pagination: {
+      maxPages: 50,
+      maxRecords: 5000,
+      timeoutMs: 60000,
+      onProgress: (page, totalRecords) => {
+        process.stdout.write(`\r📄 Page ${page}: ${totalRecords} records...`);
+      },
+    },
+  });
+
+  // 4. Process results
+  console.log('\n\n✅ Pagination Complete!\n');
+
+  const { totalRecords, totalPages, truncated, truncationReason } =
+    result.extensions.autoPagination;
+
+  console.log('📊 Statistics:');
+  console.log(`   Total Records: ${totalRecords}`);
+  console.log(`   Total Pages: ${totalPages}`);
+  console.log(`   Truncated: ${truncated}${truncated ? ` (${truncationReason})` : ''}\n`);
+
+  // 5. Analyze data
+  const positions = result.data.virtualPositions.edges;
+
+  const activeCount = positions.filter(e => e.node.status === 'ACTIVE').length;
+  const totalQty = positions.reduce((sum, e) => sum + (e.node.quantity || 0), 0);
+
+  console.log('📦 Inventory Summary:');
+  console.log(`   Active Positions: ${activeCount}`);
+  console.log(`   Total Quantity: ${totalQty} units\n`);
+
+  // 6. Display sample
+  console.log('📝 Sample Records:');
+  positions.slice(0, 3).forEach((edge, i) => {
+    const { productRef, quantity, groupRef, status } = edge.node;
+    console.log(`   ${i + 1}. ${productRef}: ${quantity} units @ ${groupRef} [${status}]`);
+  });
+}
+
+main().catch(console.error);
+```
+
+---
+
+## Testing Your Setup
+
+Run this test to verify everything works:
+
+```bash
+# Test connectivity and pagination
+node quick-start-complete.js
+```
+
+Expected output:
+
+```
+🚀 Starting pagination...
+
+📄 Page 15: 1487 records...
+
+✅ Pagination Complete!
+
+📊 Statistics:
+   Total Records: 1487
+   Total Pages: 15
+   Truncated: false
+
+📦 Inventory Summary:
+   Active Positions: 1342
+   Total Quantity: 245670 units
+
+📝 Sample Records:
+   1. SKU-001: 150 units @ WH-EAST [ACTIVE]
+   2. SKU-002: 75 units @ WH-WEST [ACTIVE]
+   3. SKU-003: 200 units @ WH-CENTRAL [ACTIVE]
+```
+
+---
+
+## Troubleshooting
+
+### Problem: "Field 'X' doesn't exist on type 'Y'"
+
+**Solution:** Field name is wrong. Introspect schema first:
+
+```bash
+npx fc-connect introspect-schema --endpoint YOUR_URL --output schema.json
+# Then search schema.json for correct field names
+```
+
+### Problem: "Variable '$first' is never used"
+
+**Solution:** Include variable in query arguments:
+
+```graphql
+# ❌ WRONG
+query GetItems($first: Int!) {
+  items { ... }  # Not using $first
+}
+
+# ✅ CORRECT
+query GetItems($first: Int!) {
+  items(first: $first) { ... }  # Using $first
+}
+```
+
+### Problem: Auto-pagination not activating
+
+**Solution:** Ensure query has pagination variables:
+
+```typescript
+// Check this returns true
+const hasVariables = query.includes('$first') || query.includes('$after');
+```
+
+---
+
+## Next Steps
+
+Congratulations! You've successfully implemented auto-pagination. Next:
+
+- **Learn Configuration Options:** [Module 3: Configuration →](./auto-pagination-03-configuration.md)
+- **Try Advanced Patterns:** [Module 4: Advanced Patterns →](./auto-pagination-04-advanced-patterns.md)
+- **Explore More Examples:** [Examples Directory →](../examples/)
+
+---
+
+## Key Takeaways
+
+✅ **Always introspect schema** - Never guess field names
+✅ **Include pagination variables** - `$first`, `$after` in query
+✅ **Include pageInfo** - Required for pagination detection
+✅ **Set safety limits** - maxPages, maxRecords, timeoutMs
+✅ **Monitor progress** - Use onProgress callbacks
+✅ **Check truncation** - Verify `extensions.autoPagination.truncated`
+
+---
+
+[← Back to Index](../../advanced-services/advanced-services-readme.md) | [← Previous: Foundations](./auto-pagination-01-foundations.md) | [Next: Configuration →](./auto-pagination-03-configuration.md)