@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

package/docs/03-PATTERN-GUIDES/multiple-connections/modules/multiple-connections-01-foundations.md

@@ -1,378 +1,378 @@
-# Module 1: Foundations
-
-**Level:** Beginner
-**Estimated Time:** 15 minutes
-
-**SDK Version:** Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
-
-> **📝 Note:** This module is about **GraphQL pagination** with multiple paginated fields in a single query. It is **NOT** about multi-tenant connections or credential management.
-
-## Overview
-
-This module explains the fundamentals of handling multiple paginated connections in GraphQL queries, the current SDK behavior, and when you need special handling.
-
-## Learning Objectives
-
-By the end of this module, you will:
-- ✅ Understand what "multiple connections" means in GraphQL context
-- ✅ Know when the SDK auto-detects vs when you need `connectionPath`
-- ✅ Understand the single-connection-per-query design decision
-- ✅ Recognize scenarios requiring parallel queries
-
-## What Are Multiple Connections?
-
-A GraphQL query has **multiple connections** when it requests more than one paginated field at the same level:
-
-### Example: Multiple Root Connections
-
-```graphql
-query GetMultiple($productsFirst: Int!, $locationsFirst: Int!) {
-  # Connection 1: products
-  products(first: $productsFirst) {
-    edges { node { id ref } cursor }
-    pageInfo { hasNextPage }
-  }
-
-  # Connection 2: locations
-  locations(first: $locationsFirst) {
-    edges { node { id name } cursor }
-    pageInfo { hasNextPage }
-  }
-}
-```
-
-This query has **TWO root-level connections**: `products` and `locations`.
-
-### Example: Nested Connection
-
-```graphql
-query GetOrderWithItems($orderId: ID!, $itemsFirst: Int!) {
-  order(id: $orderId) {
-    id
-    ref
-    # Nested connection: items inside order
-    items(first: $itemsFirst) {
-      edges { node { id sku quantity } cursor }
-      pageInfo { hasNextPage }
-    }
-  }
-}
-```
-
-This query has **ONE nested connection**: `order.items`.
-
-## Current SDK Behavior: Single connectionPath
-
-The auto-pagination feature targets **ONLY ONE connection per query execution**. This is by design.
-
-### How It Works
-
-```typescript
-const result = await client.graphql({
-  query: multiConnectionQuery,
-  variables: { productsFirst: 50, locationsFirst: 10 },
-  pagination: {
-    connectionPath: 'products',  // ← Explicitly target products
-    maxPages: 5
-  }
-});
-
-// Result:
-// - products: 5 pages × 50 records/page = up to 250 records ✅ PAGINATED
-// - locations: 1 page × 10 records = 10 records ⚠️ NOT PAGINATED
-```
-
-**Key Insight:** Other connections remain at their **first page only**.
-
-### Why This Design?
-
-1. **Cursor Independence**
-   - Different connections may complete at different page counts
-   - `products` might have 10 pages while `locations` has 2 pages
-   - Managing multiple cursor states simultaneously is complex
-
-2. **Variable Complexity**
-   - Each connection needs its own `$after` variable
-   - `$productsAfter`, `$locationsAfter`, etc.
-   - Automatic variable generation would be error-prone
-
-3. **Predictability**
-   - Single-target behavior is deterministic
-   - Clear metadata in `extensions.autoPagination`
-   - Easier to debug and reason about
-
-4. **Workaround Exists**
-   - Parallel queries provide full control
-   - More flexible for complex scenarios
-   - Better performance in many cases
-
-## Auto-Detection vs Explicit Path
-
-### Scenario 1: Auto-Detection (No connectionPath)
-
-When you **don't specify** `connectionPath`, the SDK recursively searches the response and paginates the **first connection found**:
-
-```typescript
-const result = await client.graphql({
-  query: `
-    query GetMultiple($first: Int!, $after: String) {
-      products(first: $first, after: $after) {
-        edges { node { id } cursor }
-        pageInfo { hasNextPage }
-      }
-      locations(first: $first) {
-        edges { node { id } cursor }
-        pageInfo { hasNextPage }
-      }
-    }
-  `,
-  variables: { first: 100 },
-  // NO connectionPath specified
-});
-
-// SDK auto-detects 'products' (first connection in response)
-```
-
-**Order depends on:**
-- Response structure (usually matches query order)
-- GraphQL execution order (varies by server)
-
-**⚠️ Risk:** Unpredictable which connection gets paginated!
-
-### Scenario 2: Explicit Path (Recommended)
-
-**Always use `connectionPath`** when multiple connections exist:
-
-```typescript
-const result = await client.graphql({
-  query: multiConnectionQuery,
-  variables: { productsFirst: 50, locationsFirst: 10 },
-  pagination: {
-    connectionPath: 'products',  // ✅ Explicit and predictable
-    maxPages: 5
-  }
-});
-```
-
-**Benefits:**
-- ✅ Predictable behavior
-- ✅ Clear intent in code
-- ✅ Easier to debug
-- ✅ Self-documenting
-
-## Connection Path Syntax
-
-### Root-Level Connections
-
-Use simple string for root connections:
-
-```typescript
-// Target 'products'
-pagination: { connectionPath: 'products' }
-
-// Target 'locations'
-pagination: { connectionPath: 'locations' }
-
-// Target 'virtualPositions'
-pagination: { connectionPath: 'virtualPositions' }
-```
-
-### Nested Connections
-
-Use **dot notation** for nested paths:
-
-```typescript
-// Target items inside order
-pagination: { connectionPath: 'order.items' }
-
-// Target positions inside product
-pagination: { connectionPath: 'product.virtualPositions' }
-
-// Deeply nested
-pagination: { connectionPath: 'order.fulfilments.items' }
-```
-
-## What Gets Paginated?
-
-### With connectionPath
-
-```typescript
-pagination: { connectionPath: 'products', maxPages: 5 }
-```
-
-**Paginated:** ✅ `products` connection (up to 5 pages)
-**Not Paginated:** ❌ All other connections (first page only)
-
-### Without connectionPath
-
-```typescript
-pagination: { maxPages: 5 }
-```
-
-**Paginated:** ✅ First connection found in response
-**Not Paginated:** ❌ All other connections (first page only)
-
-## When Do You Need Special Handling?
-
-### Use Case 1: All Connections Need Full Pagination
-
-**Scenario:** Export all products AND all locations
-
-**Solution:** Parallel queries (Module 4)
-
-```typescript
-const [products, locations] = await Promise.all([
-  client.graphql({ query: productsQuery, pagination: { maxPages: 10 } }),
-  client.graphql({ query: locationsQuery, pagination: { maxPages: 5 } })
-]);
-```
-
-### Use Case 2: One Connection Paginated, Others First Page OK
-
-**Scenario:** Export all products but only first page of metadata
-
-**Solution:** Single query with `connectionPath`
-
-```typescript
-const result = await client.graphql({
-  query: multiConnectionQuery,
-  pagination: {
-    connectionPath: 'products',  // Only products paginated
-    maxPages: 10
-  }
-});
-```
-
-### Use Case 3: Nested Connection Pagination
-
-**Scenario:** Get all items for a specific order
-
-**Solution:** Single query with dot notation
-
-```typescript
-const result = await client.graphql({
-  query: orderItemsQuery,
-  variables: { orderId: '123' },
-  pagination: {
-    connectionPath: 'order.items',  // Nested path
-    maxPages: 20
-  }
-});
-```
-
-## Detection Logic Internals
-
-For developers who want to understand how auto-detection works:
-
-1. **Check if pagination variables exist** (`$first`, `$after`, etc.)
-   - If no pagination variables → No auto-pagination
-
-2. **If `connectionPath` specified:**
-   - Navigate to that path in response
-   - Paginate that connection only
-
-3. **If `connectionPath` NOT specified:**
-   - Recursively search response for first connection structure
-   - Connection must have: `edges`, `pageInfo.hasNextPage`
-   - Use first match found
-
-## Common Misconceptions
-
-### ❌ Misconception 1: "All connections auto-paginate"
-
-**Reality:** Only the **targeted** connection (or first found) paginates.
-
-```typescript
-// This will NOT paginate both:
-const result = await client.graphql({
-  query: multiConnectionQuery,
-  pagination: { maxPages: 5 }
-});
-// Only products OR locations paginated (whichever is first)
-```
-
-### ❌ Misconception 2: "Array syntax works"
-
-**Reality:** `connectionPath` only accepts a **string**, not an array.
-
-```typescript
-// ❌ NOT SUPPORTED
-pagination: {
-  connectionPath: ['products', 'locations']
-}
-
-// ✅ CORRECT - Use parallel queries instead
-const [products, locations] = await Promise.all([...]);
-```
-
-### ❌ Misconception 3: "Nested connections auto-detect"
-
-**Reality:** Nested connections require **explicit dot notation**.
-
-```typescript
-// ❌ Won't find nested connection
-pagination: { maxPages: 5 }
-
-// ✅ Explicit nested path
-pagination: { connectionPath: 'order.items', maxPages: 5 }
-```
-
-## Key Takeaways
-
-- 🎯 **One connection per query** - SDK design choice for simplicity
-- 🎯 **Use `connectionPath`** - Always be explicit with multiple connections
-- 🎯 **Dot notation for nesting** - `"order.items"` targets nested connections
-- 🎯 **Parallel queries for all** - Use `Promise.all()` to paginate multiple connections
-- 🎯 **Auto-detection is risky** - Predictability matters in production
-
-## Practice Exercise
-
-Try to identify how many connections these queries have and which would be paginated:
-
-### Exercise 1
-```typescript
-await client.graphql({
-  query: `
-    query GetData($first: Int!) {
-      products(first: $first) { ... }
-      locations(first: $first) { ... }
-    }
-  `,
-  variables: { first: 100 }
-  // No pagination config specified
-});
-```
-
-**Question:** Which connection gets paginated?
-
-<details>
-<summary>Answer</summary>
-
-**None.** Without `pagination` config, auto-pagination is disabled even if variables exist. You need:
-
-```typescript
-pagination: { maxPages: 5 }  // Auto-detect first connection
-// OR
-pagination: { connectionPath: 'products', maxPages: 5 }  // Explicit
-```
-</details>
-
-### Exercise 2
-```typescript
-await client.graphql({
-  query: multiConnectionQuery,
-  pagination: { connectionPath: 'locations', maxPages: 3 }
-});
-```
-
-**Question:** How many pages of `products` will you get?
-
-<details>
-<summary>Answer</summary>
-
-**One page.** Only `locations` is paginated (up to 3 pages). `products` remains at first page only.
-</details>
-
-## Next Steps
-
-Continue to [Module 2: Quick Start](.././modules/multiple-connections-02-quick-start.md) to see working examples with real Fluent Commerce data.
+# Module 1: Foundations
+
+**Level:** Beginner
+**Estimated Time:** 15 minutes
+
+**SDK Version:** Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
+
+> **📝 Note:** This module is about **GraphQL pagination** with multiple paginated fields in a single query. It is **NOT** about multi-tenant connections or credential management.
+
+## Overview
+
+This module explains the fundamentals of handling multiple paginated connections in GraphQL queries, the current SDK behavior, and when you need special handling.
+
+## Learning Objectives
+
+By the end of this module, you will:
+- ✅ Understand what "multiple connections" means in GraphQL context
+- ✅ Know when the SDK auto-detects vs when you need `connectionPath`
+- ✅ Understand the single-connection-per-query design decision
+- ✅ Recognize scenarios requiring parallel queries
+
+## What Are Multiple Connections?
+
+A GraphQL query has **multiple connections** when it requests more than one paginated field at the same level:
+
+### Example: Multiple Root Connections
+
+```graphql
+query GetMultiple($productsFirst: Int!, $locationsFirst: Int!) {
+  # Connection 1: products
+  products(first: $productsFirst) {
+    edges { node { id ref } cursor }
+    pageInfo { hasNextPage }
+  }
+
+  # Connection 2: locations
+  locations(first: $locationsFirst) {
+    edges { node { id name } cursor }
+    pageInfo { hasNextPage }
+  }
+}
+```
+
+This query has **TWO root-level connections**: `products` and `locations`.
+
+### Example: Nested Connection
+
+```graphql
+query GetOrderWithItems($orderId: ID!, $itemsFirst: Int!) {
+  order(id: $orderId) {
+    id
+    ref
+    # Nested connection: items inside order
+    items(first: $itemsFirst) {
+      edges { node { id sku quantity } cursor }
+      pageInfo { hasNextPage }
+    }
+  }
+}
+```
+
+This query has **ONE nested connection**: `order.items`.
+
+## Current SDK Behavior: Single connectionPath
+
+The auto-pagination feature targets **ONLY ONE connection per query execution**. This is by design.
+
+### How It Works
+
+```typescript
+const result = await client.graphql({
+  query: multiConnectionQuery,
+  variables: { productsFirst: 50, locationsFirst: 10 },
+  pagination: {
+    connectionPath: 'products',  // ← Explicitly target products
+    maxPages: 5
+  }
+});
+
+// Result:
+// - products: 5 pages × 50 records/page = up to 250 records ✅ PAGINATED
+// - locations: 1 page × 10 records = 10 records ⚠️ NOT PAGINATED
+```
+
+**Key Insight:** Other connections remain at their **first page only**.
+
+### Why This Design?
+
+1. **Cursor Independence**
+   - Different connections may complete at different page counts
+   - `products` might have 10 pages while `locations` has 2 pages
+   - Managing multiple cursor states simultaneously is complex
+
+2. **Variable Complexity**
+   - Each connection needs its own `$after` variable
+   - `$productsAfter`, `$locationsAfter`, etc.
+   - Automatic variable generation would be error-prone
+
+3. **Predictability**
+   - Single-target behavior is deterministic
+   - Clear metadata in `extensions.autoPagination`
+   - Easier to debug and reason about
+
+4. **Workaround Exists**
+   - Parallel queries provide full control
+   - More flexible for complex scenarios
+   - Better performance in many cases
+
+## Auto-Detection vs Explicit Path
+
+### Scenario 1: Auto-Detection (No connectionPath)
+
+When you **don't specify** `connectionPath`, the SDK recursively searches the response and paginates the **first connection found**:
+
+```typescript
+const result = await client.graphql({
+  query: `
+    query GetMultiple($first: Int!, $after: String) {
+      products(first: $first, after: $after) {
+        edges { node { id } cursor }
+        pageInfo { hasNextPage }
+      }
+      locations(first: $first) {
+        edges { node { id } cursor }
+        pageInfo { hasNextPage }
+      }
+    }
+  `,
+  variables: { first: 100 },
+  // NO connectionPath specified
+});
+
+// SDK auto-detects 'products' (first connection in response)
+```
+
+**Order depends on:**
+- Response structure (usually matches query order)
+- GraphQL execution order (varies by server)
+
+**⚠️ Risk:** Unpredictable which connection gets paginated!
+
+### Scenario 2: Explicit Path (Recommended)
+
+**Always use `connectionPath`** when multiple connections exist:
+
+```typescript
+const result = await client.graphql({
+  query: multiConnectionQuery,
+  variables: { productsFirst: 50, locationsFirst: 10 },
+  pagination: {
+    connectionPath: 'products',  // ✅ Explicit and predictable
+    maxPages: 5
+  }
+});
+```
+
+**Benefits:**
+- ✅ Predictable behavior
+- ✅ Clear intent in code
+- ✅ Easier to debug
+- ✅ Self-documenting
+
+## Connection Path Syntax
+
+### Root-Level Connections
+
+Use simple string for root connections:
+
+```typescript
+// Target 'products'
+pagination: { connectionPath: 'products' }
+
+// Target 'locations'
+pagination: { connectionPath: 'locations' }
+
+// Target 'virtualPositions'
+pagination: { connectionPath: 'virtualPositions' }
+```
+
+### Nested Connections
+
+Use **dot notation** for nested paths:
+
+```typescript
+// Target items inside order
+pagination: { connectionPath: 'order.items' }
+
+// Target positions inside product
+pagination: { connectionPath: 'product.virtualPositions' }
+
+// Deeply nested
+pagination: { connectionPath: 'order.fulfilments.items' }
+```
+
+## What Gets Paginated?
+
+### With connectionPath
+
+```typescript
+pagination: { connectionPath: 'products', maxPages: 5 }
+```
+
+**Paginated:** ✅ `products` connection (up to 5 pages)
+**Not Paginated:** ❌ All other connections (first page only)
+
+### Without connectionPath
+
+```typescript
+pagination: { maxPages: 5 }
+```
+
+**Paginated:** ✅ First connection found in response
+**Not Paginated:** ❌ All other connections (first page only)
+
+## When Do You Need Special Handling?
+
+### Use Case 1: All Connections Need Full Pagination
+
+**Scenario:** Export all products AND all locations
+
+**Solution:** Parallel queries (Module 4)
+
+```typescript
+const [products, locations] = await Promise.all([
+  client.graphql({ query: productsQuery, pagination: { maxPages: 10 } }),
+  client.graphql({ query: locationsQuery, pagination: { maxPages: 5 } })
+]);
+```
+
+### Use Case 2: One Connection Paginated, Others First Page OK
+
+**Scenario:** Export all products but only first page of metadata
+
+**Solution:** Single query with `connectionPath`
+
+```typescript
+const result = await client.graphql({
+  query: multiConnectionQuery,
+  pagination: {
+    connectionPath: 'products',  // Only products paginated
+    maxPages: 10
+  }
+});
+```
+
+### Use Case 3: Nested Connection Pagination
+
+**Scenario:** Get all items for a specific order
+
+**Solution:** Single query with dot notation
+
+```typescript
+const result = await client.graphql({
+  query: orderItemsQuery,
+  variables: { orderId: '123' },
+  pagination: {
+    connectionPath: 'order.items',  // Nested path
+    maxPages: 20
+  }
+});
+```
+
+## Detection Logic Internals
+
+For developers who want to understand how auto-detection works:
+
+1. **Check if pagination variables exist** (`$first`, `$after`, etc.)
+   - If no pagination variables → No auto-pagination
+
+2. **If `connectionPath` specified:**
+   - Navigate to that path in response
+   - Paginate that connection only
+
+3. **If `connectionPath` NOT specified:**
+   - Recursively search response for first connection structure
+   - Connection must have: `edges`, `pageInfo.hasNextPage`
+   - Use first match found
+
+## Common Misconceptions
+
+### ❌ Misconception 1: "All connections auto-paginate"
+
+**Reality:** Only the **targeted** connection (or first found) paginates.
+
+```typescript
+// This will NOT paginate both:
+const result = await client.graphql({
+  query: multiConnectionQuery,
+  pagination: { maxPages: 5 }
+});
+// Only products OR locations paginated (whichever is first)
+```
+
+### ❌ Misconception 2: "Array syntax works"
+
+**Reality:** `connectionPath` only accepts a **string**, not an array.
+
+```typescript
+// ❌ NOT SUPPORTED
+pagination: {
+  connectionPath: ['products', 'locations']
+}
+
+// ✅ CORRECT - Use parallel queries instead
+const [products, locations] = await Promise.all([...]);
+```
+
+### ❌ Misconception 3: "Nested connections auto-detect"
+
+**Reality:** Nested connections require **explicit dot notation**.
+
+```typescript
+// ❌ Won't find nested connection
+pagination: { maxPages: 5 }
+
+// ✅ Explicit nested path
+pagination: { connectionPath: 'order.items', maxPages: 5 }
+```
+
+## Key Takeaways
+
+- 🎯 **One connection per query** - SDK design choice for simplicity
+- 🎯 **Use `connectionPath`** - Always be explicit with multiple connections
+- 🎯 **Dot notation for nesting** - `"order.items"` targets nested connections
+- 🎯 **Parallel queries for all** - Use `Promise.all()` to paginate multiple connections
+- 🎯 **Auto-detection is risky** - Predictability matters in production
+
+## Practice Exercise
+
+Try to identify how many connections these queries have and which would be paginated:
+
+### Exercise 1
+```typescript
+await client.graphql({
+  query: `
+    query GetData($first: Int!) {
+      products(first: $first) { ... }
+      locations(first: $first) { ... }
+    }
+  `,
+  variables: { first: 100 }
+  // No pagination config specified
+});
+```
+
+**Question:** Which connection gets paginated?
+
+<details>
+<summary>Answer</summary>
+
+**None.** Without `pagination` config, auto-pagination is disabled even if variables exist. You need:
+
+```typescript
+pagination: { maxPages: 5 }  // Auto-detect first connection
+// OR
+pagination: { connectionPath: 'products', maxPages: 5 }  // Explicit
+```
+</details>
+
+### Exercise 2
+```typescript
+await client.graphql({
+  query: multiConnectionQuery,
+  pagination: { connectionPath: 'locations', maxPages: 3 }
+});
+```
+
+**Question:** How many pages of `products` will you get?
+
+<details>
+<summary>Answer</summary>
+
+**One page.** Only `locations` is paginated (up to 3 pages). `products` remains at first page only.
+</details>
+
+## Next Steps
+
+Continue to [Module 2: Quick Start](.././modules/multiple-connections-02-quick-start.md) to see working examples with real Fluent Commerce data.