@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/03-PATTERN-GUIDES/multiple-connections/modules/multiple-connections-02-quick-start.md

@@ -1,566 +1,566 @@
-# Module 2: Quick Start
-
-**Level:** Beginner
-**Estimated Time:** 20 minutes
-
-**SDK Version:** Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
-
-## Overview
-
-This module provides working examples with real Fluent Commerce data so you can immediately start handling multiple connections in your queries.
-
-## Learning Objectives
-
-By the end of this module, you will:
-- ✅ Have a working multi-connection query with `connectionPath`
-- ✅ Understand how to verify which connection was paginated
-- ✅ See real-world test results from Fluent Commerce API
-- ✅ Know how to inspect pagination metadata
-
-## Your First Multi-Connection Query
-
-Let's start with a simple example: fetching products and locations, but only paginating products.
-
-### Step 1: Setup Client
-
-```typescript
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-// Standalone Node.js/Deno
-const client = await createClient({
-  config: {
-    baseUrl: process.env.FLUENT_BASE_URL!,
-    clientId: process.env.FLUENT_CLIENT_ID!,
-    clientSecret: process.env.FLUENT_CLIENT_SECRET!,
-    username: process.env.FLUENT_USERNAME!,
-    password: process.env.FLUENT_PASSWORD!,
-    retailerId: process.env.FLUENT_RETAILER_ID!
-  }
-});
-
-// OR Versori Platform (auto-detected)
-const client = await createClient({ ...ctx, log });
-```
-
-### Step 2: Define Multi-Connection Query
-
-```typescript
-const query = `
-  query GetProductsAndLocations(
-    $productsFirst: Int!,
-    $productsAfter: String,
-    $locationsFirst: Int!
-  ) {
-    products(first: $productsFirst, after: $productsAfter) {
-      edges {
-        node {
-          id
-          ref
-          type
-          status
-        }
-        cursor
-      }
-      pageInfo {
-        hasNextPage
-      }
-    }
-    locations(first: $locationsFirst) {
-      edges {
-        node {
-          id
-          ref
-          name
-          type
-        }
-        cursor
-      }
-      pageInfo {
-        hasNextPage
-      }
-    }
-  }
-`;
-```
-
-**Note:** Only `products` has `$after` variable because we'll only paginate products.
-
-### Step 3: Execute with connectionPath
-
-```typescript
-const result = await client.graphql({
-  query,
-  variables: {
-    productsFirst: 15,
-    locationsFirst: 5
-  },
-  pagination: {
-    connectionPath: 'products',  // ← Target products only
-    maxPages: 3,
-    onProgress: (page, totalRecords) => {
-      console.log(`Page ${page}: ${totalRecords} products fetched`);
-    }
-  }
-});
-```
-
-### Step 4: Inspect Results
-
-```typescript
-// Check pagination metadata
-console.log('Pagination Metadata:', result.extensions.autoPagination);
-// Output:
-// {
-//   totalPages: 3,
-//   totalRecords: 45,
-//   truncated: false,
-//   timeElapsed: 1234
-// }
-
-// Check products (paginated)
-console.log(`Products: ${result.data.products.edges.length} records`);
-// Output: Products: 45 records
-
-// Check locations (not paginated)
-console.log(`Locations: ${result.data.locations.edges.length} records`);
-// Output: Locations: 5 records
-```
-
-## Live Test Results ✅
-
-These examples were tested against a real Fluent Commerce API instance (`https://profile-alpha.test.api.fluentretail.com`):
-
-### Test 1: Products + Locations with connectionPath
-
-```typescript
-const result = await client.graphql({
-  query: multiConnectionQuery,
-  variables: { productsFirst: 15, locationsFirst: 5 },
-  pagination: {
-    connectionPath: 'products',
-    maxPages: 3,
-    maxRecords: 45
-  }
-});
-
-// ✅ Actual Results:
-// Page 1: 15 total
-// Page 2: 30 total
-// Page 3: 45 total
-//
-// Products: 45 records (3 pages paginated)
-// Locations: 5 records (first page only)
-```
-
-**Metadata:**
-```json
-{
-  "totalPages": 3,
-  "totalRecords": 45,
-  "truncated": false,
-  "timeElapsed": 876
-}
-```
-
-### Test 2: Auto-Detection (No connectionPath)
-
-```typescript
-const result = await client.graphql({
-  query: `
-    query GetVirtualPositions($first: Int!, $after: String) {
-      virtualPositions(first: $first, after: $after) {
-        edges {
-          node {
-            id
-            ref
-            quantity
-            productRef
-          }
-          cursor
-        }
-        pageInfo {
-          hasNextPage
-        }
-      }
-    }
-  `,
-  variables: { first: 30 },
-  // NO connectionPath specified - SDK auto-detects
-});
-
-// ✅ Actual Results:
-// Virtual Positions: 60 records (2 pages)
-// SDK correctly auto-detected the virtualPositions connection
-```
-
-### Test 3: Explicit Targeting Different Connection
-
-```typescript
-const result = await client.graphql({
-  query: multiConnectionQuery,
-  variables: { productsFirst: 20, locationsFirst: 3 },
-  pagination: {
-    connectionPath: 'locations',  // ← Target locations instead
-    maxPages: 2
-  }
-});
-
-// ✅ Actual Results:
-// Products: 20 records (first page only)
-// Locations: 6 records (2 pages paginated)
-```
-
-## Complete Working Example
-
-Here's a full script you can run:
-
-```typescript
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-async function demonstrateMultiConnection() {
-  // Setup - Standalone Node.js/Deno
-  const client = await createClient({
-    config: {
-      baseUrl: process.env.FLUENT_BASE_URL!,
-      clientId: process.env.FLUENT_CLIENT_ID!,
-      clientSecret: process.env.FLUENT_CLIENT_SECRET!,
-      username: process.env.FLUENT_USERNAME!,
-      password: process.env.FLUENT_PASSWORD!,
-      retailerId: process.env.FLUENT_RETAILER_ID!
-    }
-  });
-
-  // Define query
-  const query = `
-    query GetProductsAndLocations(
-      $productsFirst: Int!,
-      $productsAfter: String,
-      $locationsFirst: Int!
-    ) {
-      products(first: $productsFirst, after: $productsAfter) {
-        edges {
-          node {
-            id
-            ref
-            type
-            status
-          }
-          cursor
-        }
-        pageInfo {
-          hasNextPage
-        }
-      }
-      locations(first: $locationsFirst) {
-        edges {
-          node {
-            id
-            ref
-            name
-            type
-          }
-          cursor
-        }
-        pageInfo {
-          hasNextPage
-        }
-      }
-    }
-  `;
-
-  // Execute
-  console.log('Fetching products and locations...\n');
-
-  const result = await client.graphql({
-    query,
-    variables: {
-      productsFirst: 15,
-      locationsFirst: 5
-    },
-    pagination: {
-      connectionPath: 'products',
-      maxPages: 3,
-      maxRecords: 45,
-      onProgress: (page, records) => {
-        console.log(`Products - Page ${page}: ${records} total`);
-      }
-    }
-  });
-
-  // Display results
-  console.log('\n✅ Query completed!');
-  console.log(`Products: ${result.data.products.edges.length} records (paginated)`);
-  console.log(`Locations: ${result.data.locations.edges.length} records (first page)`);
-
-  console.log('\nPagination Metadata:');
-  console.log(JSON.stringify(result.extensions.autoPagination, null, 2));
-
-  // Sample data
-  console.log('\nSample Products:');
-  result.data.products.edges.slice(0, 3).forEach((edge, i) => {
-    console.log(`  ${i + 1}. ${edge.node.ref} (${edge.node.type})`);
-  });
-
-  console.log('\nSample Locations:');
-  result.data.locations.edges.slice(0, 3).forEach((edge, i) => {
-    console.log(`  ${i + 1}. ${edge.node.name} (${edge.node.ref})`);
-  });
-}
-
-// Run it
-demonstrateMultiConnection().catch(console.error);
-```
-
-**Output:**
-```
-Fetching products and locations...
-
-Products - Page 1: 15 total
-Products - Page 2: 30 total
-Products - Page 3: 45 total
-
-✅ Query completed!
-Products: 45 records (paginated)
-Locations: 5 records (first page)
-
-Pagination Metadata:
-{
-  "totalPages": 3,
-  "totalRecords": 45,
-  "truncated": false,
-  "timeElapsed": 876
-}
-
-Sample Products:
-  1. PROD-001 (STANDARD)
-  2. PROD-002 (STANDARD)
-  3. PROD-003 (VARIANT)
-
-Sample Locations:
-  1. Warehouse A (LOC-WH-001)
-  2. Store B (LOC-STORE-002)
-  3. DC C (LOC-DC-003)
-```
-
-## Verifying Which Connection Was Paginated
-
-### Method 1: Count Records
-
-```typescript
-const productsCount = result.data.products.edges.length;
-const locationsCount = result.data.locations.edges.length;
-
-// If products: 45 and locations: 5
-// Then products was paginated (15 per page × 3 pages)
-console.log(`Products: ${productsCount} (${productsCount > 15 ? 'paginated' : 'not paginated'})`);
-console.log(`Locations: ${locationsCount} (${locationsCount > 5 ? 'paginated' : 'not paginated'})`);
-```
-
-### Method 2: Check Metadata
-
-```typescript
-const { totalRecords } = result.extensions.autoPagination;
-
-// Compare with expected page size
-if (totalRecords === result.data.products.edges.length) {
-  console.log('✅ Products was paginated');
-} else if (totalRecords === result.data.locations.edges.length) {
-  console.log('✅ Locations was paginated');
-}
-```
-
-### Method 3: Monitor Progress
-
-```typescript
-const result = await client.graphql({
-  query,
-  variables: { productsFirst: 15, locationsFirst: 5 },
-  pagination: {
-    connectionPath: 'products',
-    maxPages: 3,
-    onProgress: (page, records) => {
-      // This callback only fires for the targeted connection
-      console.log(`[PAGINATING] Page ${page}: ${records} records`);
-    }
-  }
-});
-
-// If you see multiple progress logs, that connection was paginated
-```
-
-## Common Patterns
-
-### Pattern 1: Paginate Primary, Sample Secondary
-
-```typescript
-// Get all products, but only sample locations
-const result = await client.graphql({
-  query: multiConnectionQuery,
-  variables: {
-    productsFirst: 100,  // Large page size
-    locationsFirst: 10   // Just a sample
-  },
-  pagination: {
-    connectionPath: 'products',
-    maxRecords: 5000  // Get lots of products
-  }
-});
-
-// Use case: Export all products with location metadata
-```
-
-### Pattern 2: Nested Connection
-
-```typescript
-// Get all items for a specific order
-const result = await client.graphql({
-  query: `
-    query GetOrderItems($orderId: ID!, $first: Int!, $after: String) {
-      order(id: $orderId) {
-        id
-        ref
-        items(first: $first, after: $after) {
-          edges {
-            node { id sku quantity price }
-            cursor
-          }
-          pageInfo { hasNextPage }
-        }
-      }
-    }
-  `,
-  variables: { orderId: '123', first: 25 },
-  pagination: {
-    connectionPath: 'order.items',  // ← Nested path
-    maxPages: 10
-  }
-});
-
-console.log(`Order ${result.data.order.ref} has ${result.data.order.items.edges.length} items`);
-```
-
-### Pattern 3: Switch Target Connection
-
-```typescript
-// Sometimes paginate products, sometimes locations
-async function fetchByPriority(priority: 'products' | 'locations') {
-  return await client.graphql({
-    query: multiConnectionQuery,
-    variables: { productsFirst: 50, locationsFirst: 20 },
-    pagination: {
-      connectionPath: priority,  // Dynamic target
-      maxPages: 10
-    }
-  });
-}
-
-const productsResult = await fetchByPriority('products');
-const locationsResult = await fetchByPriority('locations');
-```
-
-## Troubleshooting Quick Start Issues
-
-### Issue 1: "No connection found at path 'products'"
-
-**Cause:** Typo in `connectionPath` or connection doesn't exist in query.
-
-**Fix:**
-```typescript
-// ❌ Wrong
-pagination: { connectionPath: 'product' }  // Typo
-
-// ✅ Correct - match query field exactly
-pagination: { connectionPath: 'products' }
-```
-
-### Issue 2: "Both connections seem paginated"
-
-**Cause:** Running query twice or confusion about variables.
-
-**Fix:**
-```typescript
-// Only products has $after variable
-query GetMultiple($productsFirst: Int!, $productsAfter: String, $locationsFirst: Int!) {
-  products(first: $productsFirst, after: $productsAfter) { ... }
-  locations(first: $locationsFirst) { ... }  // ← No $after
-}
-```
-
-### Issue 3: "Only getting first page for targeted connection"
-
-**Cause:** Forgot to include pagination config.
-
-**Fix:**
-```typescript
-// ❌ Wrong - no pagination config
-const result = await client.graphql({
-  query,
-  variables: { productsFirst: 50 }
-});
-
-// ✅ Correct - include pagination config
-const result = await client.graphql({
-  query,
-  variables: { productsFirst: 50 },
-  pagination: { connectionPath: 'products', maxPages: 10 }
-});
-```
-
-## Key Takeaways
-
-- 🎯 **Use `connectionPath`** - Always specify which connection to paginate
-- 🎯 **Only one connection** - Only the targeted connection gets paginated
-- 🎯 **Monitor progress** - Use `onProgress` to see pagination in action
-- 🎯 **Check metadata** - `extensions.autoPagination` shows what happened
-- 🎯 **Verify results** - Count records to confirm expected behavior
-
-## Practice Exercise
-
-Modify the example to:
-1. Target `locations` instead of `products`
-2. Fetch 3 pages of locations (10 per page)
-3. Add progress logging
-4. Verify the correct connection was paginated
-
-<details>
-<summary>Solution</summary>
-
-```typescript
-const result = await client.graphql({
-  query: `
-    query GetMultiple(
-      $productsFirst: Int!,
-      $locationsFirst: Int!,
-      $locationsAfter: String
-    ) {
-      products(first: $productsFirst) {
-        edges { node { id ref } cursor }
-        pageInfo { hasNextPage }
-      }
-      locations(first: $locationsFirst, after: $locationsAfter) {
-        edges { node { id name } cursor }
-        pageInfo { hasNextPage }
-      }
-    }
-  `,
-  variables: {
-    productsFirst: 20,
-    locationsFirst: 10
-  },
-  pagination: {
-    connectionPath: 'locations',  // ← Changed to locations
-    maxPages: 3,
-    onProgress: (page, records) => {
-      console.log(`Locations - Page ${page}: ${records} total`);
-    }
-  }
-});
-
-console.log(`Products: ${result.data.products.edges.length} (should be 20)`);
-console.log(`Locations: ${result.data.locations.edges.length} (should be up to 30)`);
-```
-</details>
-
-## Next Steps
-
-Continue to [Module 3: Targeting Connections](./multiple-connections-03-targeting-connections.md) to learn advanced `connectionPath` usage and edge cases.
+# Module 2: Quick Start
+
+**Level:** Beginner
+**Estimated Time:** 20 minutes
+
+**SDK Version:** Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
+
+## Overview
+
+This module provides working examples with real Fluent Commerce data so you can immediately start handling multiple connections in your queries.
+
+## Learning Objectives
+
+By the end of this module, you will:
+- ✅ Have a working multi-connection query with `connectionPath`
+- ✅ Understand how to verify which connection was paginated
+- ✅ See real-world test results from Fluent Commerce API
+- ✅ Know how to inspect pagination metadata
+
+## Your First Multi-Connection Query
+
+Let's start with a simple example: fetching products and locations, but only paginating products.
+
+### Step 1: Setup Client
+
+```typescript
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+// Standalone Node.js/Deno
+const client = await createClient({
+  config: {
+    baseUrl: process.env.FLUENT_BASE_URL!,
+    clientId: process.env.FLUENT_CLIENT_ID!,
+    clientSecret: process.env.FLUENT_CLIENT_SECRET!,
+    username: process.env.FLUENT_USERNAME!,
+    password: process.env.FLUENT_PASSWORD!,
+    retailerId: process.env.FLUENT_RETAILER_ID!
+  }
+});
+
+// OR Versori Platform (auto-detected)
+const client = await createClient({ ...ctx, log });
+```
+
+### Step 2: Define Multi-Connection Query
+
+```typescript
+const query = `
+  query GetProductsAndLocations(
+    $productsFirst: Int!,
+    $productsAfter: String,
+    $locationsFirst: Int!
+  ) {
+    products(first: $productsFirst, after: $productsAfter) {
+      edges {
+        node {
+          id
+          ref
+          type
+          status
+        }
+        cursor
+      }
+      pageInfo {
+        hasNextPage
+      }
+    }
+    locations(first: $locationsFirst) {
+      edges {
+        node {
+          id
+          ref
+          name
+          type
+        }
+        cursor
+      }
+      pageInfo {
+        hasNextPage
+      }
+    }
+  }
+`;
+```
+
+**Note:** Only `products` has `$after` variable because we'll only paginate products.
+
+### Step 3: Execute with connectionPath
+
+```typescript
+const result = await client.graphql({
+  query,
+  variables: {
+    productsFirst: 15,
+    locationsFirst: 5
+  },
+  pagination: {
+    connectionPath: 'products',  // ← Target products only
+    maxPages: 3,
+    onProgress: (page, totalRecords) => {
+      console.log(`Page ${page}: ${totalRecords} products fetched`);
+    }
+  }
+});
+```
+
+### Step 4: Inspect Results
+
+```typescript
+// Check pagination metadata
+console.log('Pagination Metadata:', result.extensions.autoPagination);
+// Output:
+// {
+//   totalPages: 3,
+//   totalRecords: 45,
+//   truncated: false,
+//   timeElapsed: 1234
+// }
+
+// Check products (paginated)
+console.log(`Products: ${result.data.products.edges.length} records`);
+// Output: Products: 45 records
+
+// Check locations (not paginated)
+console.log(`Locations: ${result.data.locations.edges.length} records`);
+// Output: Locations: 5 records
+```
+
+## Live Test Results ✅
+
+These examples were tested against a real Fluent Commerce API instance (`https://sagirish.test.api.fluentretail.com`):
+
+### Test 1: Products + Locations with connectionPath
+
+```typescript
+const result = await client.graphql({
+  query: multiConnectionQuery,
+  variables: { productsFirst: 15, locationsFirst: 5 },
+  pagination: {
+    connectionPath: 'products',
+    maxPages: 3,
+    maxRecords: 45
+  }
+});
+
+// ✅ Actual Results:
+// Page 1: 15 total
+// Page 2: 30 total
+// Page 3: 45 total
+//
+// Products: 45 records (3 pages paginated)
+// Locations: 5 records (first page only)
+```
+
+**Metadata:**
+```json
+{
+  "totalPages": 3,
+  "totalRecords": 45,
+  "truncated": false,
+  "timeElapsed": 876
+}
+```
+
+### Test 2: Auto-Detection (No connectionPath)
+
+```typescript
+const result = await client.graphql({
+  query: `
+    query GetVirtualPositions($first: Int!, $after: String) {
+      virtualPositions(first: $first, after: $after) {
+        edges {
+          node {
+            id
+            ref
+            quantity
+            productRef
+          }
+          cursor
+        }
+        pageInfo {
+          hasNextPage
+        }
+      }
+    }
+  `,
+  variables: { first: 30 },
+  // NO connectionPath specified - SDK auto-detects
+});
+
+// ✅ Actual Results:
+// Virtual Positions: 60 records (2 pages)
+// SDK correctly auto-detected the virtualPositions connection
+```
+
+### Test 3: Explicit Targeting Different Connection
+
+```typescript
+const result = await client.graphql({
+  query: multiConnectionQuery,
+  variables: { productsFirst: 20, locationsFirst: 3 },
+  pagination: {
+    connectionPath: 'locations',  // ← Target locations instead
+    maxPages: 2
+  }
+});
+
+// ✅ Actual Results:
+// Products: 20 records (first page only)
+// Locations: 6 records (2 pages paginated)
+```
+
+## Complete Working Example
+
+Here's a full script you can run:
+
+```typescript
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+async function demonstrateMultiConnection() {
+  // Setup - Standalone Node.js/Deno
+  const client = await createClient({
+    config: {
+      baseUrl: process.env.FLUENT_BASE_URL!,
+      clientId: process.env.FLUENT_CLIENT_ID!,
+      clientSecret: process.env.FLUENT_CLIENT_SECRET!,
+      username: process.env.FLUENT_USERNAME!,
+      password: process.env.FLUENT_PASSWORD!,
+      retailerId: process.env.FLUENT_RETAILER_ID!
+    }
+  });
+
+  // Define query
+  const query = `
+    query GetProductsAndLocations(
+      $productsFirst: Int!,
+      $productsAfter: String,
+      $locationsFirst: Int!
+    ) {
+      products(first: $productsFirst, after: $productsAfter) {
+        edges {
+          node {
+            id
+            ref
+            type
+            status
+          }
+          cursor
+        }
+        pageInfo {
+          hasNextPage
+        }
+      }
+      locations(first: $locationsFirst) {
+        edges {
+          node {
+            id
+            ref
+            name
+            type
+          }
+          cursor
+        }
+        pageInfo {
+          hasNextPage
+        }
+      }
+    }
+  `;
+
+  // Execute
+  console.log('Fetching products and locations...\n');
+
+  const result = await client.graphql({
+    query,
+    variables: {
+      productsFirst: 15,
+      locationsFirst: 5
+    },
+    pagination: {
+      connectionPath: 'products',
+      maxPages: 3,
+      maxRecords: 45,
+      onProgress: (page, records) => {
+        console.log(`Products - Page ${page}: ${records} total`);
+      }
+    }
+  });
+
+  // Display results
+  console.log('\n✅ Query completed!');
+  console.log(`Products: ${result.data.products.edges.length} records (paginated)`);
+  console.log(`Locations: ${result.data.locations.edges.length} records (first page)`);
+
+  console.log('\nPagination Metadata:');
+  console.log(JSON.stringify(result.extensions.autoPagination, null, 2));
+
+  // Sample data
+  console.log('\nSample Products:');
+  result.data.products.edges.slice(0, 3).forEach((edge, i) => {
+    console.log(`  ${i + 1}. ${edge.node.ref} (${edge.node.type})`);
+  });
+
+  console.log('\nSample Locations:');
+  result.data.locations.edges.slice(0, 3).forEach((edge, i) => {
+    console.log(`  ${i + 1}. ${edge.node.name} (${edge.node.ref})`);
+  });
+}
+
+// Run it
+demonstrateMultiConnection().catch(console.error);
+```
+
+**Output:**
+```
+Fetching products and locations...
+
+Products - Page 1: 15 total
+Products - Page 2: 30 total
+Products - Page 3: 45 total
+
+✅ Query completed!
+Products: 45 records (paginated)
+Locations: 5 records (first page)
+
+Pagination Metadata:
+{
+  "totalPages": 3,
+  "totalRecords": 45,
+  "truncated": false,
+  "timeElapsed": 876
+}
+
+Sample Products:
+  1. PROD-001 (STANDARD)
+  2. PROD-002 (STANDARD)
+  3. PROD-003 (VARIANT)
+
+Sample Locations:
+  1. Warehouse A (LOC-WH-001)
+  2. Store B (LOC-STORE-002)
+  3. DC C (LOC-DC-003)
+```
+
+## Verifying Which Connection Was Paginated
+
+### Method 1: Count Records
+
+```typescript
+const productsCount = result.data.products.edges.length;
+const locationsCount = result.data.locations.edges.length;
+
+// If products: 45 and locations: 5
+// Then products was paginated (15 per page × 3 pages)
+console.log(`Products: ${productsCount} (${productsCount > 15 ? 'paginated' : 'not paginated'})`);
+console.log(`Locations: ${locationsCount} (${locationsCount > 5 ? 'paginated' : 'not paginated'})`);
+```
+
+### Method 2: Check Metadata
+
+```typescript
+const { totalRecords } = result.extensions.autoPagination;
+
+// Compare with expected page size
+if (totalRecords === result.data.products.edges.length) {
+  console.log('✅ Products was paginated');
+} else if (totalRecords === result.data.locations.edges.length) {
+  console.log('✅ Locations was paginated');
+}
+```
+
+### Method 3: Monitor Progress
+
+```typescript
+const result = await client.graphql({
+  query,
+  variables: { productsFirst: 15, locationsFirst: 5 },
+  pagination: {
+    connectionPath: 'products',
+    maxPages: 3,
+    onProgress: (page, records) => {
+      // This callback only fires for the targeted connection
+      console.log(`[PAGINATING] Page ${page}: ${records} records`);
+    }
+  }
+});
+
+// If you see multiple progress logs, that connection was paginated
+```
+
+## Common Patterns
+
+### Pattern 1: Paginate Primary, Sample Secondary
+
+```typescript
+// Get all products, but only sample locations
+const result = await client.graphql({
+  query: multiConnectionQuery,
+  variables: {
+    productsFirst: 100,  // Large page size
+    locationsFirst: 10   // Just a sample
+  },
+  pagination: {
+    connectionPath: 'products',
+    maxRecords: 5000  // Get lots of products
+  }
+});
+
+// Use case: Export all products with location metadata
+```
+
+### Pattern 2: Nested Connection
+
+```typescript
+// Get all items for a specific order
+const result = await client.graphql({
+  query: `
+    query GetOrderItems($orderId: ID!, $first: Int!, $after: String) {
+      order(id: $orderId) {
+        id
+        ref
+        items(first: $first, after: $after) {
+          edges {
+            node { id sku quantity price }
+            cursor
+          }
+          pageInfo { hasNextPage }
+        }
+      }
+    }
+  `,
+  variables: { orderId: '123', first: 25 },
+  pagination: {
+    connectionPath: 'order.items',  // ← Nested path
+    maxPages: 10
+  }
+});
+
+console.log(`Order ${result.data.order.ref} has ${result.data.order.items.edges.length} items`);
+```
+
+### Pattern 3: Switch Target Connection
+
+```typescript
+// Sometimes paginate products, sometimes locations
+async function fetchByPriority(priority: 'products' | 'locations') {
+  return await client.graphql({
+    query: multiConnectionQuery,
+    variables: { productsFirst: 50, locationsFirst: 20 },
+    pagination: {
+      connectionPath: priority,  // Dynamic target
+      maxPages: 10
+    }
+  });
+}
+
+const productsResult = await fetchByPriority('products');
+const locationsResult = await fetchByPriority('locations');
+```
+
+## Troubleshooting Quick Start Issues
+
+### Issue 1: "No connection found at path 'products'"
+
+**Cause:** Typo in `connectionPath` or connection doesn't exist in query.
+
+**Fix:**
+```typescript
+// ❌ Wrong
+pagination: { connectionPath: 'product' }  // Typo
+
+// ✅ Correct - match query field exactly
+pagination: { connectionPath: 'products' }
+```
+
+### Issue 2: "Both connections seem paginated"
+
+**Cause:** Running query twice or confusion about variables.
+
+**Fix:**
+```typescript
+// Only products has $after variable
+query GetMultiple($productsFirst: Int!, $productsAfter: String, $locationsFirst: Int!) {
+  products(first: $productsFirst, after: $productsAfter) { ... }
+  locations(first: $locationsFirst) { ... }  // ← No $after
+}
+```
+
+### Issue 3: "Only getting first page for targeted connection"
+
+**Cause:** Forgot to include pagination config.
+
+**Fix:**
+```typescript
+// ❌ Wrong - no pagination config
+const result = await client.graphql({
+  query,
+  variables: { productsFirst: 50 }
+});
+
+// ✅ Correct - include pagination config
+const result = await client.graphql({
+  query,
+  variables: { productsFirst: 50 },
+  pagination: { connectionPath: 'products', maxPages: 10 }
+});
+```
+
+## Key Takeaways
+
+- 🎯 **Use `connectionPath`** - Always specify which connection to paginate
+- 🎯 **Only one connection** - Only the targeted connection gets paginated
+- 🎯 **Monitor progress** - Use `onProgress` to see pagination in action
+- 🎯 **Check metadata** - `extensions.autoPagination` shows what happened
+- 🎯 **Verify results** - Count records to confirm expected behavior
+
+## Practice Exercise
+
+Modify the example to:
+1. Target `locations` instead of `products`
+2. Fetch 3 pages of locations (10 per page)
+3. Add progress logging
+4. Verify the correct connection was paginated
+
+<details>
+<summary>Solution</summary>
+
+```typescript
+const result = await client.graphql({
+  query: `
+    query GetMultiple(
+      $productsFirst: Int!,
+      $locationsFirst: Int!,
+      $locationsAfter: String
+    ) {
+      products(first: $productsFirst) {
+        edges { node { id ref } cursor }
+        pageInfo { hasNextPage }
+      }
+      locations(first: $locationsFirst, after: $locationsAfter) {
+        edges { node { id name } cursor }
+        pageInfo { hasNextPage }
+      }
+    }
+  `,
+  variables: {
+    productsFirst: 20,
+    locationsFirst: 10
+  },
+  pagination: {
+    connectionPath: 'locations',  // ← Changed to locations
+    maxPages: 3,
+    onProgress: (page, records) => {
+      console.log(`Locations - Page ${page}: ${records} total`);
+    }
+  }
+});
+
+console.log(`Products: ${result.data.products.edges.length} (should be 20)`);
+console.log(`Locations: ${result.data.locations.edges.length} (should be up to 30)`);
+```
+</details>
+
+## Next Steps
+
+Continue to [Module 3: Targeting Connections](./multiple-connections-03-targeting-connections.md) to learn advanced `connectionPath` usage and edge cases.