@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/03-PATTERN-GUIDES/multiple-connections/modules/multiple-connections-06-api-reference.md

@@ -1,824 +1,824 @@
-# Module 6: API Reference
-
-**Level:** Reference
-**Estimated Time:** As needed
-
-**SDK Version:** Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
-
-> **📝 Note:** This API reference is for **GraphQL pagination** with multiple paginated fields in a single query. It is **NOT** about multi-tenant connections or credential management.
-
-## Overview
-
-This module provides complete API documentation, configuration options, and reference material for multi-connection pagination.
-
-## connectionPath Configuration
-
-### Type Definition
-
-```typescript
-interface PaginationConfig {
-  enabled?: boolean;                    // Enable/disable auto-pagination
-  connectionPath?: string;              // Path to target connection
-  maxPages?: number;                    // Maximum pages to fetch
-  maxRecords?: number;                  // Maximum total records
-  timeoutMs?: number;                   // Maximum time in milliseconds
-  delayMs?: number;                     // Delay between pages
-  direction?: 'forward' | 'backward';   // Pagination direction
-  abortSignal?: AbortSignal;            // Cancel pagination
-  onProgress?: (page: number, totalRecords: number) => void;
-  onWarning?: (message: string) => void; // Warning callback
-}
-```
-
-### enabled Property
-
-**Type:** `boolean | undefined`
-
-**Default:** Auto-detected based on query variables and response structure
-
-**Description:** Explicitly enable or disable auto-pagination. When not specified, the SDK auto-detects whether pagination should be enabled based on the presence of pagination variables (`$first`, `$after`, etc.) in the query.
-
-**Examples:**
-
-```typescript
-// Explicitly enable
-pagination: { enabled: true, maxPages: 10 }
-
-// Explicitly disable
-pagination: { enabled: false }
-
-// Auto-detect (default behavior)
-pagination: { maxPages: 10 }  // enabled is auto-detected
-```
-
-**Use Cases:**
-- Force pagination when auto-detection fails
-- Disable pagination for specific queries
-- Override default behavior
-
-### connectionPath Property
-
-**Type:** `string | undefined`
-
-**Description:** Specifies which connection to paginate when query has multiple connections.
-
-**Syntax:**
-- **Root-level:** Simple field name (e.g., `'products'`)
-- **Nested:** Dot notation (e.g., `'order.items'`)
-- **Deep nested:** Multi-level (e.g., `'order.fulfilments.items'`)
-
-**Default:** If not specified, SDK auto-detects first connection found.
-
-**Examples:**
-
-```typescript
-// Root-level connection
-pagination: { connectionPath: 'products' }
-
-// Nested connection
-pagination: { connectionPath: 'order.items' }
-
-// Deep nested
-pagination: { connectionPath: 'order.fulfilments.items' }
-
-// Using alias
-query { myProducts: products { ... } }
-pagination: { connectionPath: 'myProducts' }
-```
-
-**Constraints:**
-- ✅ Must be a **string** (not array)
-- ✅ Must match actual response structure
-- ✅ Case-sensitive
-- ✅ Must point to a connection (has `edges`, `pageInfo`)
-
-### maxPages Property
-
-**Type:** `number | undefined`
-
-**Description:** Maximum number of pages to fetch before stopping.
-
-**Default:** `Infinity` (no limit)
-
-**Behavior:** Pagination stops when ANY of these conditions is met (OR logic):
-- `maxPages` reached
-- `maxRecords` reached
-- `timeoutMs` elapsed
-- `pageInfo.hasNextPage` is false (no more data)
-
-**Examples:**
-
-```typescript
-// Fetch up to 10 pages
-pagination: { maxPages: 10 }
-
-// Fetch up to 5 pages OR 500 records (whichever first)
-pagination: { maxPages: 5, maxRecords: 500 }
-
-// No page limit (fetch all)
-pagination: { maxRecords: 10000 }  // maxPages defaults to Infinity
-```
-
-### maxRecords Property
-
-**Type:** `number | undefined`
-
-**Description:** Maximum total records to fetch before stopping.
-
-**Default:** `Infinity` (no limit)
-
-**Behavior:** Cumulative count across all pages. Stops when total records >= maxRecords.
-
-**Examples:**
-
-```typescript
-// Fetch up to 1000 records
-pagination: { maxRecords: 1000 }
-
-// Fetch up to 1000 records OR 10 pages (whichever first)
-pagination: { maxPages: 10, maxRecords: 1000 }
-```
-
-### timeoutMs Property
-
-**Type:** `number | undefined`
-
-**Description:** Maximum time (in milliseconds) to spend fetching pages.
-
-**Default:** `Infinity` (no timeout)
-
-**Behavior:** Stops pagination when elapsed time exceeds timeout.
-
-**Examples:**
-
-```typescript
-// Stop after 60 seconds
-pagination: { timeoutMs: 60000 }
-
-// Stop after 30 seconds OR 1000 records (whichever first)
-pagination: { maxRecords: 1000, timeoutMs: 30000 }
-```
-
-### onProgress Callback
-
-**Type:** `((page: number, totalRecords: number) => void) | undefined`
-
-**Description:** Callback function invoked after each page is fetched.
-
-**Parameters:**
-- `page`: Current page number (1-indexed)
-- `totalRecords`: Cumulative total records fetched so far
-
-**Use Cases:**
-- Progress logging
-- UI progress bars
-- Performance monitoring
-- Early termination logic
-
-**Examples:**
-
-```typescript
-// Simple logging
-pagination: {
-  maxPages: 10,
-  onProgress: (page, records) => {
-    console.log(`Page ${page}: ${records} records`);
-  }
-}
-
-// Progress bar
-let progressBar = new ProgressBar();
-pagination: {
-  maxPages: 100,
-  onProgress: (page, records) => {
-    progressBar.update(page / 100);
-  }
-}
-
-// Conditional logging
-pagination: {
-  maxPages: 50,
-  onProgress: (page, records) => {
-    if (page % 5 === 0) {  // Log every 5 pages
-      console.log(`[Checkpoint] Page ${page}: ${records} records`);
-    }
-  }
-}
-```
-
-### delayMs Property
-
-**Type:** `number | undefined`
-
-**Default:** `0` (no delay)
-
-**Description:** Delay in milliseconds between page fetches. Useful for rate limiting to avoid overwhelming the API server.
-
-**Examples:**
-
-```typescript
-// Add 500ms delay between pages
-pagination: {
-  maxPages: 20,
-  delayMs: 500
-}
-
-// Rate limiting for high-volume extraction
-pagination: {
-  maxPages: 100,
-  delayMs: 1000  // 1 second delay
-}
-```
-
-**Use Cases:**
-- API rate limiting
-- Server load management
-- Throttling for large extractions
-
-### direction Property
-
-**Type:** `'forward' | 'backward' | undefined`
-
-**Default:** Auto-detected from query variables
-
-**Description:** Pagination direction. Forward pagination uses `first`/`after`, backward pagination uses `last`/`before`.
-
-**Auto-Detection:**
-- Queries with `$first` and `$after` → `'forward'`
-- Queries with `$last` and `$before` → `'backward'`
-
-**Examples:**
-
-```typescript
-// Forward pagination (explicit)
-pagination: {
-  direction: 'forward',
-  maxPages: 10
-}
-
-// Backward pagination (explicit)
-pagination: {
-  direction: 'backward',
-  maxPages: 10
-}
-
-// Auto-detect from query variables (recommended)
-pagination: { maxPages: 10 }  // direction is auto-detected
-```
-
-**Note:** Forward pagination is recommended and most commonly used.
-
-### abortSignal Property
-
-**Type:** `AbortSignal | undefined`
-
-**Default:** `undefined`
-
-**Description:** AbortSignal for cancelling pagination mid-operation. Allows external cancellation of long-running pagination operations.
-
-**Examples:**
-
-```typescript
-// Basic cancellation
-const controller = new AbortController();
-const promise = client.graphql({
-  query,
-  pagination: {
-    maxPages: 100,
-    abortSignal: controller.signal
-  }
-});
-
-// Cancel after 10 seconds
-setTimeout(() => controller.abort(), 10000);
-
-try {
-  const result = await promise;
-} catch (error) {
-  if (error.name === 'AbortError') {
-    console.log('Pagination cancelled');
-  }
-}
-```
-
-**Use Cases:**
-- User-initiated cancellation (e.g., cancel button)
-- Timeout enforcement
-- Resource cleanup on component unmount
-
-### onWarning Callback
-
-**Type:** `((message: string) => void) | undefined`
-
-**Description:** Callback function invoked when non-fatal warnings occur during pagination. Warnings don't stop pagination but indicate potential issues.
-
-**Examples:**
-
-```typescript
-// Log warnings
-pagination: {
-  maxPages: 10,
-  onWarning: (message) => {
-    console.warn(`[Pagination Warning] ${message}`);
-  }
-}
-
-// Track warnings for reporting
-const warnings: string[] = [];
-pagination: {
-  maxPages: 10,
-  onWarning: (message) => {
-    warnings.push(message);
-  }
-}
-```
-
-**Common Warnings:**
-- Duplicate records detected (deduplication occurred)
-- Unexpected response structure
-- Performance degradation detected
-
-## Response Metadata
-
-### extensions.autoPagination
-
-**Type:**
-
-```typescript
-interface AutoPaginationMetadata {
-  totalPages: number;      // Total pages fetched
-  totalRecords: number;    // Total records fetched
-  truncated: boolean;      // True if stopped due to limit
-  timeElapsed?: number;    // Time taken (ms)
-}
-```
-
-**Location:** `result.extensions.autoPagination`
-
-**Properties:**
-
-#### totalPages
-
-**Type:** `number`
-
-**Description:** Total number of pages fetched during pagination.
-
-**Example:**
-```typescript
-const result = await client.graphql({
-  query,
-  pagination: { maxPages: 10 }
-});
-
-console.log(result.extensions.autoPagination.totalPages);
-// Output: 8 (if only 8 pages existed)
-```
-
-#### totalRecords
-
-**Type:** `number`
-
-**Description:** Total number of records fetched across all pages.
-
-**Example:**
-```typescript
-const result = await client.graphql({
-  query,
-  pagination: { maxRecords: 1000 }
-});
-
-console.log(result.extensions.autoPagination.totalRecords);
-// Output: 873 (actual records fetched)
-```
-
-#### truncated
-
-**Type:** `boolean`
-
-**Description:** `true` if pagination stopped due to a limit (maxPages, maxRecords, timeoutMs). `false` if all available data was fetched.
-
-**Note:** The SDK does NOT provide a `truncationReason` property. To determine which limit was hit, check metadata values:
-- If `totalPages === maxPages` → maxPages limit
-- If `totalRecords >= maxRecords` → maxRecords limit
-- If `timeElapsed >= timeoutMs` → timeout limit
-
-**Examples:**
-
-```typescript
-// Basic truncation check
-const result = await client.graphql({
-  query,
-  pagination: { maxPages: 10, maxRecords: 1000 }
-});
-
-if (result.extensions.autoPagination.truncated) {
-  console.log('⚠️ Hit a limit - more data may exist');
-} else {
-  console.log('✅ Fetched all available data');
-}
-```
-
-```typescript
-// Determine which limit was hit
-const result = await client.graphql({
-  query,
-  pagination: {
-    maxPages: 10,
-    maxRecords: 1000,
-    timeoutMs: 30000
-  }
-});
-
-const metadata = result.extensions.autoPagination;
-
-if (metadata.truncated) {
-  // Check which limit caused truncation
-  if (metadata.totalPages === 10) {
-    console.log('⚠️ Stopped: Reached maxPages limit');
-  } else if (metadata.totalRecords >= 1000) {
-    console.log('⚠️ Stopped: Reached maxRecords limit');
-  } else if (metadata.timeElapsed && metadata.timeElapsed >= 30000) {
-    console.log('⚠️ Stopped: Timeout elapsed');
-  }
-} else {
-  console.log('✅ Fetched all available data');
-}
-```
-
-#### timeElapsed
-
-**Type:** `number | undefined`
-
-**Description:** Time taken (in milliseconds) for the entire pagination operation.
-
-**Example:**
-```typescript
-const result = await client.graphql({
-  query,
-  pagination: { maxPages: 100 }
-});
-
-const seconds = result.extensions.autoPagination.timeElapsed! / 1000;
-console.log(`Completed in ${seconds}s`);
-```
-
-## GraphQL Query Requirements
-
-### Required Structure
-
-For auto-pagination to work, your query must:
-
-1. **Have pagination variables**
-
-```typescript
-// ✅ Required variables
-query GetProducts($first: Int!, $after: String) { ... }
-
-// OR (backward pagination)
-query GetProducts($last: Int!, $before: String) { ... }
-```
-
-2. **Use variables in connection arguments**
-
-```typescript
-// ✅ Correct
-products(first: $first, after: $after) { ... }
-
-// ❌ Wrong - hardcoded values
-products(first: 100) { ... }
-```
-
-3. **Include connection structure**
-
-```typescript
-// ✅ Required structure
-products(first: $first, after: $after) {
-  edges {
-    node { id /* other fields */ }
-    cursor
-  }
-  pageInfo {
-    hasNextPage
-  }
-}
-```
-
-### Relay Specification Compliance
-
-The SDK expects **Relay-style cursor pagination**:
-
-```graphql
-type ProductConnection {
-  edges: [ProductEdge!]!
-  pageInfo: PageInfo!
-}
-
-type ProductEdge {
-  node: Product!
-  cursor: String!
-}
-
-type PageInfo {
-  hasNextPage: Boolean!
-  endCursor: String
-}
-```
-
-**Required fields:**
-- `edges`: Array of edge objects
-- `edges[].node`: The actual data object
-- `edges[].cursor`: Pagination cursor
-- `pageInfo.hasNextPage`: Boolean indicating more pages exist
-
-**Optional but recommended:**
-- `pageInfo.endCursor`: Cursor of last edge
-- `id` field in node for deduplication
-
-## Auto-Detection Algorithm
-
-### How It Works
-
-When `connectionPath` is **not specified**, the SDK:
-
-1. Checks if query has pagination variables (`$first`, `$after`, etc.)
-2. Receives response from first query execution
-3. Recursively searches response object for connection structure
-4. Looks for objects with properties:
-   - `edges` (array)
-   - `pageInfo` (object)
-   - `pageInfo.hasNextPage` (boolean)
-5. Uses **first match found**
-
-### Search Order
-
-**Depth-first traversal:**
-
-```typescript
-const response = {
-  products: {           // ← Checked first
-    edges: [...],
-    pageInfo: {...}
-  },
-  locations: {          // ← Checked second
-    edges: [...],
-    pageInfo: {...}
-  },
-  order: {
-    id: '123',
-    items: {            // ← Checked third (nested)
-      edges: [...],
-      pageInfo: {...}
-    }
-  }
-};
-```
-
-### When Auto-Detection Fails
-
-Auto-detection fails when:
-- No pagination variables in query
-- Response doesn't match Relay structure
-- Multiple connections exist (picks first, may not be desired)
-- Non-standard field names (`items` instead of `edges`)
-
-## Parallel Query Pattern (Promise.all)
-
-### Basic Pattern
-
-```typescript
-const [result1, result2, result3] = await Promise.all([
-  client.graphql({
-    query: query1,
-    pagination: { maxPages: 10 }
-  }),
-  client.graphql({
-    query: query2,
-    pagination: { maxPages: 5 }
-  }),
-  client.graphql({
-    query: query3,
-    pagination: { maxPages: 8 }
-  })
-]);
-```
-
-### Error Handling Pattern
-
-```typescript
-const results = await Promise.allSettled([
-  client.graphql({ query: query1, pagination: { maxPages: 10 } }),
-  client.graphql({ query: query2, pagination: { maxPages: 5 } }),
-  client.graphql({ query: query3, pagination: { maxPages: 8 } })
-]);
-
-results.forEach((result, index) => {
-  if (result.status === 'fulfilled') {
-    console.log(`Query ${index + 1}: ${result.value.extensions.autoPagination.totalRecords} records`);
-  } else {
-    console.error(`Query ${index + 1} failed:`, result.reason);
-  }
-});
-```
-
-## Supported Pagination Directions
-
-### Forward Pagination (Recommended)
-
-```typescript
-query GetProducts($first: Int!, $after: String) {
-  products(first: $first, after: $after) {
-    edges { node { id } cursor }
-    pageInfo {
-      hasNextPage
-      endCursor
-    }
-  }
-}
-```
-
-**Variables:**
-- `first`: Number of records per page
-- `after`: Cursor of last record from previous page
-
-### Backward Pagination
-
-```typescript
-query GetProducts($last: Int!, $before: String) {
-  products(last: $last, before: $before) {
-    edges { node { id } cursor }
-    pageInfo {
-      hasPreviousPage
-      startCursor
-    }
-  }
-}
-```
-
-**Variables:**
-- `last`: Number of records per page
-- `before`: Cursor of first record from next page
-
-**Note:** SDK primarily focuses on forward pagination. Backward pagination is supported but less common.
-
-## Deduplication Behavior
-
-### Automatic Deduplication
-
-The SDK automatically deduplicates records across pages using the `id` field:
-
-```typescript
-// If pages have overlapping records (e.g., due to concurrent writes):
-// Page 1: [{id: '1'}, {id: '2'}, {id: '3'}]
-// Page 2: [{id: '3'}, {id: '4'}, {id: '5'}]  // id:'3' duplicated
-
-// SDK result: [{id: '1'}, {id: '2'}, {id: '3'}, {id: '4'}, {id: '5'}]
-// Duplicate removed automatically
-```
-
-### Requirements
-
-For deduplication to work:
-- ✅ Each record must have an `id` field
-- ✅ `id` must be unique across records
-
-**If `id` is missing:**
-- ⚠️ No deduplication occurs
-- Duplicate records may appear in final result
-
-## Limitations and Constraints
-
-### Current Limitations
-
-1. **Single connection per query**
-   - Can only paginate ONE connection per `client.graphql()` call
-   - Use parallel queries for multiple connections
-
-2. **No array syntax for connectionPath**
-   - `connectionPath: ['products', 'locations']` is NOT supported
-   - Must use separate queries
-
-3. **Relay spec required**
-   - Non-standard pagination structures not supported
-   - Must have `edges`, `pageInfo`, `hasNextPage`
-
-4. **Forward pagination focus**
-   - Backward pagination (`last`, `before`) supported but less tested
-   - Bidirectional pagination not supported
-
-### Performance Constraints
-
-**Recommended limits:**
-- `maxPages`: ≤ 100 for most use cases
-- `maxRecords`: ≤ 10,000 for simple entities
-- `timeoutMs`: ≤ 300,000 (5 minutes)
-- Concurrent parallel queries: ≤ 5
-
-**Resource usage:**
-- Memory: ~1MB per 1,000 simple records
-- Network: Proportional to page count × page size
-- API rate limits: Respect Fluent Commerce limits
-
-## TypeScript Types
-
-### Complete Type Definitions
-
-```typescript
-import { GraphQLClient } from '@fluentcommerce/fc-connect-sdk';
-
-interface PaginationConfig {
-  enabled?: boolean;
-  connectionPath?: string;
-  maxPages?: number;
-  maxRecords?: number;
-  timeoutMs?: number;
-  delayMs?: number;
-  direction?: 'forward' | 'backward';
-  abortSignal?: AbortSignal;
-  onProgress?: (page: number, totalRecords: number) => void;
-  onWarning?: (message: string) => void;
-}
-
-interface GraphQLOptions {
-  query: string;
-  variables?: Record<string, any>;
-  pagination?: PaginationConfig;
-}
-
-interface AutoPaginationMetadata {
-  totalPages: number;
-  totalRecords: number;
-  truncated: boolean;
-  timeElapsed?: number;
-}
-
-interface GraphQLResponse<T = any> {
-  data: T;
-  errors?: any[];
-  extensions: {
-    autoPagination: AutoPaginationMetadata;
-  };
-}
-
-// Usage
-const result: GraphQLResponse<{ products: Connection<Product> }> =
-  await client.graphql({
-    query: productsQuery,
-    variables: { first: 100 },
-    pagination: {
-      connectionPath: 'products',
-      maxPages: 10,
-      delayMs: 500,
-      onWarning: (msg) => console.warn(msg)
-    }
-  });
-```
-
-## Quick Reference Summary
-
-### Configuration Options
-
-| Configuration | Type | Default | Description |
-|---------------|------|---------|-------------|
-| `enabled` | `boolean` | Auto-detect | Enable/disable auto-pagination |
-| `connectionPath` | `string` | Auto-detect | Path to connection to paginate |
-| `maxPages` | `number` | `Infinity` | Max pages to fetch (OR logic) |
-| `maxRecords` | `number` | `Infinity` | Max total records (OR logic) |
-| `timeoutMs` | `number` | `Infinity` | Max time in ms (OR logic) |
-| `delayMs` | `number` | `0` | Delay between pages (ms) |
-| `direction` | `'forward'|'backward'` | Auto-detect | Pagination direction |
-| `abortSignal` | `AbortSignal` | `undefined` | Cancel pagination |
-| `onProgress` | `function` | `undefined` | Callback after each page |
-| `onWarning` | `function` | `undefined` | Callback for warnings |
-
-### Response Metadata
-
-| Metadata | Type | Description |
-|----------|------|-------------|
-| `totalPages` | `number` | Pages fetched |
-| `totalRecords` | `number` | Total records fetched |
-| `truncated` | `boolean` | Stopped due to limit |
-| `timeElapsed` | `number` | Time taken (ms) |
-
-**Note:** There is NO `truncationReason` property. To determine which limit was hit:
-- Check if `totalPages === maxPages` → maxPages limit
-- Check if `totalRecords >= maxRecords` → maxRecords limit
-- Check if `timeElapsed >= timeoutMs` → timeout limit
-
-## Related Documentation
-
-- [Module 1: Foundations](.././modules/multiple-connections-01-foundations.md) - Core concepts
-- [Module 2: Quick Start](.././modules/multiple-connections-02-quick-start.md) - Working examples
-- [Module 3: Targeting Connections](./multiple-connections-03-targeting-connections.md) - connectionPath usage
-- [Module 4: Parallel Queries](./multiple-connections-04-parallel-queries.md) - Promise.all patterns
-- [Module 5: Best Practices](./multiple-connections-05-best-practices.md) - Production patterns
-- [Auto-Pagination Guide](../../../02-CORE-GUIDES/auto-pagination/) - Core pagination documentation
-- [Main Guide](../multiple-connections-readme.md) - Back to multiple connections overview
-
-## Key Takeaways
-
-- 🎯 **connectionPath** - String path to target connection
-- 🎯 **OR-logic limits** - First limit hit stops pagination
-- 🎯 **Auto-detection** - Works but explicit is better
-- 🎯 **Relay structure** - Required for pagination
-- 🎯 **Metadata** - Check `extensions.autoPagination`
-- 🎯 **Deduplication** - Automatic by `id` field
+# Module 6: API Reference
+
+**Level:** Reference
+**Estimated Time:** As needed
+
+**SDK Version:** Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
+
+> **📝 Note:** This API reference is for **GraphQL pagination** with multiple paginated fields in a single query. It is **NOT** about multi-tenant connections or credential management.
+
+## Overview
+
+This module provides complete API documentation, configuration options, and reference material for multi-connection pagination.
+
+## connectionPath Configuration
+
+### Type Definition
+
+```typescript
+interface PaginationConfig {
+  enabled?: boolean;                    // Enable/disable auto-pagination
+  connectionPath?: string;              // Path to target connection
+  maxPages?: number;                    // Maximum pages to fetch
+  maxRecords?: number;                  // Maximum total records
+  timeoutMs?: number;                   // Maximum time in milliseconds
+  delayMs?: number;                     // Delay between pages
+  direction?: 'forward' | 'backward';   // Pagination direction
+  abortSignal?: AbortSignal;            // Cancel pagination
+  onProgress?: (page: number, totalRecords: number) => void;
+  onWarning?: (message: string) => void; // Warning callback
+}
+```
+
+### enabled Property
+
+**Type:** `boolean | undefined`
+
+**Default:** Auto-detected based on query variables and response structure
+
+**Description:** Explicitly enable or disable auto-pagination. When not specified, the SDK auto-detects whether pagination should be enabled based on the presence of pagination variables (`$first`, `$after`, etc.) in the query.
+
+**Examples:**
+
+```typescript
+// Explicitly enable
+pagination: { enabled: true, maxPages: 10 }
+
+// Explicitly disable
+pagination: { enabled: false }
+
+// Auto-detect (default behavior)
+pagination: { maxPages: 10 }  // enabled is auto-detected
+```
+
+**Use Cases:**
+- Force pagination when auto-detection fails
+- Disable pagination for specific queries
+- Override default behavior
+
+### connectionPath Property
+
+**Type:** `string | undefined`
+
+**Description:** Specifies which connection to paginate when query has multiple connections.
+
+**Syntax:**
+- **Root-level:** Simple field name (e.g., `'products'`)
+- **Nested:** Dot notation (e.g., `'order.items'`)
+- **Deep nested:** Multi-level (e.g., `'order.fulfilments.items'`)
+
+**Default:** If not specified, SDK auto-detects first connection found.
+
+**Examples:**
+
+```typescript
+// Root-level connection
+pagination: { connectionPath: 'products' }
+
+// Nested connection
+pagination: { connectionPath: 'order.items' }
+
+// Deep nested
+pagination: { connectionPath: 'order.fulfilments.items' }
+
+// Using alias
+query { myProducts: products { ... } }
+pagination: { connectionPath: 'myProducts' }
+```
+
+**Constraints:**
+- ✅ Must be a **string** (not array)
+- ✅ Must match actual response structure
+- ✅ Case-sensitive
+- ✅ Must point to a connection (has `edges`, `pageInfo`)
+
+### maxPages Property
+
+**Type:** `number | undefined`
+
+**Description:** Maximum number of pages to fetch before stopping.
+
+**Default:** `Infinity` (no limit)
+
+**Behavior:** Pagination stops when ANY of these conditions is met (OR logic):
+- `maxPages` reached
+- `maxRecords` reached
+- `timeoutMs` elapsed
+- `pageInfo.hasNextPage` is false (no more data)
+
+**Examples:**
+
+```typescript
+// Fetch up to 10 pages
+pagination: { maxPages: 10 }
+
+// Fetch up to 5 pages OR 500 records (whichever first)
+pagination: { maxPages: 5, maxRecords: 500 }
+
+// No page limit (fetch all)
+pagination: { maxRecords: 10000 }  // maxPages defaults to Infinity
+```
+
+### maxRecords Property
+
+**Type:** `number | undefined`
+
+**Description:** Maximum total records to fetch before stopping.
+
+**Default:** `Infinity` (no limit)
+
+**Behavior:** Cumulative count across all pages. Stops when total records >= maxRecords.
+
+**Examples:**
+
+```typescript
+// Fetch up to 1000 records
+pagination: { maxRecords: 1000 }
+
+// Fetch up to 1000 records OR 10 pages (whichever first)
+pagination: { maxPages: 10, maxRecords: 1000 }
+```
+
+### timeoutMs Property
+
+**Type:** `number | undefined`
+
+**Description:** Maximum time (in milliseconds) to spend fetching pages.
+
+**Default:** `Infinity` (no timeout)
+
+**Behavior:** Stops pagination when elapsed time exceeds timeout.
+
+**Examples:**
+
+```typescript
+// Stop after 60 seconds
+pagination: { timeoutMs: 60000 }
+
+// Stop after 30 seconds OR 1000 records (whichever first)
+pagination: { maxRecords: 1000, timeoutMs: 30000 }
+```
+
+### onProgress Callback
+
+**Type:** `((page: number, totalRecords: number) => void) | undefined`
+
+**Description:** Callback function invoked after each page is fetched.
+
+**Parameters:**
+- `page`: Current page number (1-indexed)
+- `totalRecords`: Cumulative total records fetched so far
+
+**Use Cases:**
+- Progress logging
+- UI progress bars
+- Performance monitoring
+- Early termination logic
+
+**Examples:**
+
+```typescript
+// Simple logging
+pagination: {
+  maxPages: 10,
+  onProgress: (page, records) => {
+    console.log(`Page ${page}: ${records} records`);
+  }
+}
+
+// Progress bar
+let progressBar = new ProgressBar();
+pagination: {
+  maxPages: 100,
+  onProgress: (page, records) => {
+    progressBar.update(page / 100);
+  }
+}
+
+// Conditional logging
+pagination: {
+  maxPages: 50,
+  onProgress: (page, records) => {
+    if (page % 5 === 0) {  // Log every 5 pages
+      console.log(`[Checkpoint] Page ${page}: ${records} records`);
+    }
+  }
+}
+```
+
+### delayMs Property
+
+**Type:** `number | undefined`
+
+**Default:** `0` (no delay)
+
+**Description:** Delay in milliseconds between page fetches. Useful for rate limiting to avoid overwhelming the API server.
+
+**Examples:**
+
+```typescript
+// Add 500ms delay between pages
+pagination: {
+  maxPages: 20,
+  delayMs: 500
+}
+
+// Rate limiting for high-volume extraction
+pagination: {
+  maxPages: 100,
+  delayMs: 1000  // 1 second delay
+}
+```
+
+**Use Cases:**
+- API rate limiting
+- Server load management
+- Throttling for large extractions
+
+### direction Property
+
+**Type:** `'forward' | 'backward' | undefined`
+
+**Default:** Auto-detected from query variables
+
+**Description:** Pagination direction. Forward pagination uses `first`/`after`, backward pagination uses `last`/`before`.
+
+**Auto-Detection:**
+- Queries with `$first` and `$after` → `'forward'`
+- Queries with `$last` and `$before` → `'backward'`
+
+**Examples:**
+
+```typescript
+// Forward pagination (explicit)
+pagination: {
+  direction: 'forward',
+  maxPages: 10
+}
+
+// Backward pagination (explicit)
+pagination: {
+  direction: 'backward',
+  maxPages: 10
+}
+
+// Auto-detect from query variables (recommended)
+pagination: { maxPages: 10 }  // direction is auto-detected
+```
+
+**Note:** Forward pagination is recommended and most commonly used.
+
+### abortSignal Property
+
+**Type:** `AbortSignal | undefined`
+
+**Default:** `undefined`
+
+**Description:** AbortSignal for cancelling pagination mid-operation. Allows external cancellation of long-running pagination operations.
+
+**Examples:**
+
+```typescript
+// Basic cancellation
+const controller = new AbortController();
+const promise = client.graphql({
+  query,
+  pagination: {
+    maxPages: 100,
+    abortSignal: controller.signal
+  }
+});
+
+// Cancel after 10 seconds
+setTimeout(() => controller.abort(), 10000);
+
+try {
+  const result = await promise;
+} catch (error) {
+  if (error.name === 'AbortError') {
+    console.log('Pagination cancelled');
+  }
+}
+```
+
+**Use Cases:**
+- User-initiated cancellation (e.g., cancel button)
+- Timeout enforcement
+- Resource cleanup on component unmount
+
+### onWarning Callback
+
+**Type:** `((message: string) => void) | undefined`
+
+**Description:** Callback function invoked when non-fatal warnings occur during pagination. Warnings don't stop pagination but indicate potential issues.
+
+**Examples:**
+
+```typescript
+// Log warnings
+pagination: {
+  maxPages: 10,
+  onWarning: (message) => {
+    console.warn(`[Pagination Warning] ${message}`);
+  }
+}
+
+// Track warnings for reporting
+const warnings: string[] = [];
+pagination: {
+  maxPages: 10,
+  onWarning: (message) => {
+    warnings.push(message);
+  }
+}
+```
+
+**Common Warnings:**
+- Duplicate records detected (deduplication occurred)
+- Unexpected response structure
+- Performance degradation detected
+
+## Response Metadata
+
+### extensions.autoPagination
+
+**Type:**
+
+```typescript
+interface AutoPaginationMetadata {
+  totalPages: number;      // Total pages fetched
+  totalRecords: number;    // Total records fetched
+  truncated: boolean;      // True if stopped due to limit
+  timeElapsed?: number;    // Time taken (ms)
+}
+```
+
+**Location:** `result.extensions.autoPagination`
+
+**Properties:**
+
+#### totalPages
+
+**Type:** `number`
+
+**Description:** Total number of pages fetched during pagination.
+
+**Example:**
+```typescript
+const result = await client.graphql({
+  query,
+  pagination: { maxPages: 10 }
+});
+
+console.log(result.extensions.autoPagination.totalPages);
+// Output: 8 (if only 8 pages existed)
+```
+
+#### totalRecords
+
+**Type:** `number`
+
+**Description:** Total number of records fetched across all pages.
+
+**Example:**
+```typescript
+const result = await client.graphql({
+  query,
+  pagination: { maxRecords: 1000 }
+});
+
+console.log(result.extensions.autoPagination.totalRecords);
+// Output: 873 (actual records fetched)
+```
+
+#### truncated
+
+**Type:** `boolean`
+
+**Description:** `true` if pagination stopped due to a limit (maxPages, maxRecords, timeoutMs). `false` if all available data was fetched.
+
+**Note:** The SDK does NOT provide a `truncationReason` property. To determine which limit was hit, check metadata values:
+- If `totalPages === maxPages` → maxPages limit
+- If `totalRecords >= maxRecords` → maxRecords limit
+- If `timeElapsed >= timeoutMs` → timeout limit
+
+**Examples:**
+
+```typescript
+// Basic truncation check
+const result = await client.graphql({
+  query,
+  pagination: { maxPages: 10, maxRecords: 1000 }
+});
+
+if (result.extensions.autoPagination.truncated) {
+  console.log('⚠️ Hit a limit - more data may exist');
+} else {
+  console.log('✅ Fetched all available data');
+}
+```
+
+```typescript
+// Determine which limit was hit
+const result = await client.graphql({
+  query,
+  pagination: {
+    maxPages: 10,
+    maxRecords: 1000,
+    timeoutMs: 30000
+  }
+});
+
+const metadata = result.extensions.autoPagination;
+
+if (metadata.truncated) {
+  // Check which limit caused truncation
+  if (metadata.totalPages === 10) {
+    console.log('⚠️ Stopped: Reached maxPages limit');
+  } else if (metadata.totalRecords >= 1000) {
+    console.log('⚠️ Stopped: Reached maxRecords limit');
+  } else if (metadata.timeElapsed && metadata.timeElapsed >= 30000) {
+    console.log('⚠️ Stopped: Timeout elapsed');
+  }
+} else {
+  console.log('✅ Fetched all available data');
+}
+```
+
+#### timeElapsed
+
+**Type:** `number | undefined`
+
+**Description:** Time taken (in milliseconds) for the entire pagination operation.
+
+**Example:**
+```typescript
+const result = await client.graphql({
+  query,
+  pagination: { maxPages: 100 }
+});
+
+const seconds = result.extensions.autoPagination.timeElapsed! / 1000;
+console.log(`Completed in ${seconds}s`);
+```
+
+## GraphQL Query Requirements
+
+### Required Structure
+
+For auto-pagination to work, your query must:
+
+1. **Have pagination variables**
+
+```typescript
+// ✅ Required variables
+query GetProducts($first: Int!, $after: String) { ... }
+
+// OR (backward pagination)
+query GetProducts($last: Int!, $before: String) { ... }
+```
+
+2. **Use variables in connection arguments**
+
+```typescript
+// ✅ Correct
+products(first: $first, after: $after) { ... }
+
+// ❌ Wrong - hardcoded values
+products(first: 100) { ... }
+```
+
+3. **Include connection structure**
+
+```typescript
+// ✅ Required structure
+products(first: $first, after: $after) {
+  edges {
+    node { id /* other fields */ }
+    cursor
+  }
+  pageInfo {
+    hasNextPage
+  }
+}
+```
+
+### Relay Specification Compliance
+
+The SDK expects **Relay-style cursor pagination**:
+
+```graphql
+type ProductConnection {
+  edges: [ProductEdge!]!
+  pageInfo: PageInfo!
+}
+
+type ProductEdge {
+  node: Product!
+  cursor: String!
+}
+
+type PageInfo {
+  hasNextPage: Boolean!
+  endCursor: String
+}
+```
+
+**Required fields:**
+- `edges`: Array of edge objects
+- `edges[].node`: The actual data object
+- `edges[].cursor`: Pagination cursor
+- `pageInfo.hasNextPage`: Boolean indicating more pages exist
+
+**Optional but recommended:**
+- `pageInfo.endCursor`: Cursor of last edge
+- `id` field in node for deduplication
+
+## Auto-Detection Algorithm
+
+### How It Works
+
+When `connectionPath` is **not specified**, the SDK:
+
+1. Checks if query has pagination variables (`$first`, `$after`, etc.)
+2. Receives response from first query execution
+3. Recursively searches response object for connection structure
+4. Looks for objects with properties:
+   - `edges` (array)
+   - `pageInfo` (object)
+   - `pageInfo.hasNextPage` (boolean)
+5. Uses **first match found**
+
+### Search Order
+
+**Depth-first traversal:**
+
+```typescript
+const response = {
+  products: {           // ← Checked first
+    edges: [...],
+    pageInfo: {...}
+  },
+  locations: {          // ← Checked second
+    edges: [...],
+    pageInfo: {...}
+  },
+  order: {
+    id: '123',
+    items: {            // ← Checked third (nested)
+      edges: [...],
+      pageInfo: {...}
+    }
+  }
+};
+```
+
+### When Auto-Detection Fails
+
+Auto-detection fails when:
+- No pagination variables in query
+- Response doesn't match Relay structure
+- Multiple connections exist (picks first, may not be desired)
+- Non-standard field names (`items` instead of `edges`)
+
+## Parallel Query Pattern (Promise.all)
+
+### Basic Pattern
+
+```typescript
+const [result1, result2, result3] = await Promise.all([
+  client.graphql({
+    query: query1,
+    pagination: { maxPages: 10 }
+  }),
+  client.graphql({
+    query: query2,
+    pagination: { maxPages: 5 }
+  }),
+  client.graphql({
+    query: query3,
+    pagination: { maxPages: 8 }
+  })
+]);
+```
+
+### Error Handling Pattern
+
+```typescript
+const results = await Promise.allSettled([
+  client.graphql({ query: query1, pagination: { maxPages: 10 } }),
+  client.graphql({ query: query2, pagination: { maxPages: 5 } }),
+  client.graphql({ query: query3, pagination: { maxPages: 8 } })
+]);
+
+results.forEach((result, index) => {
+  if (result.status === 'fulfilled') {
+    console.log(`Query ${index + 1}: ${result.value.extensions.autoPagination.totalRecords} records`);
+  } else {
+    console.error(`Query ${index + 1} failed:`, result.reason);
+  }
+});
+```
+
+## Supported Pagination Directions
+
+### Forward Pagination (Recommended)
+
+```typescript
+query GetProducts($first: Int!, $after: String) {
+  products(first: $first, after: $after) {
+    edges { node { id } cursor }
+    pageInfo {
+      hasNextPage
+      endCursor
+    }
+  }
+}
+```
+
+**Variables:**
+- `first`: Number of records per page
+- `after`: Cursor of last record from previous page
+
+### Backward Pagination
+
+```typescript
+query GetProducts($last: Int!, $before: String) {
+  products(last: $last, before: $before) {
+    edges { node { id } cursor }
+    pageInfo {
+      hasPreviousPage
+      startCursor
+    }
+  }
+}
+```
+
+**Variables:**
+- `last`: Number of records per page
+- `before`: Cursor of first record from next page
+
+**Note:** SDK primarily focuses on forward pagination. Backward pagination is supported but less common.
+
+## Deduplication Behavior
+
+### Automatic Deduplication
+
+The SDK automatically deduplicates records across pages using the `id` field:
+
+```typescript
+// If pages have overlapping records (e.g., due to concurrent writes):
+// Page 1: [{id: '1'}, {id: '2'}, {id: '3'}]
+// Page 2: [{id: '3'}, {id: '4'}, {id: '5'}]  // id:'3' duplicated
+
+// SDK result: [{id: '1'}, {id: '2'}, {id: '3'}, {id: '4'}, {id: '5'}]
+// Duplicate removed automatically
+```
+
+### Requirements
+
+For deduplication to work:
+- ✅ Each record must have an `id` field
+- ✅ `id` must be unique across records
+
+**If `id` is missing:**
+- ⚠️ No deduplication occurs
+- Duplicate records may appear in final result
+
+## Limitations and Constraints
+
+### Current Limitations
+
+1. **Single connection per query**
+   - Can only paginate ONE connection per `client.graphql()` call
+   - Use parallel queries for multiple connections
+
+2. **No array syntax for connectionPath**
+   - `connectionPath: ['products', 'locations']` is NOT supported
+   - Must use separate queries
+
+3. **Relay spec required**
+   - Non-standard pagination structures not supported
+   - Must have `edges`, `pageInfo`, `hasNextPage`
+
+4. **Forward pagination focus**
+   - Backward pagination (`last`, `before`) supported but less tested
+   - Bidirectional pagination not supported
+
+### Performance Constraints
+
+**Recommended limits:**
+- `maxPages`: ≤ 100 for most use cases
+- `maxRecords`: ≤ 10,000 for simple entities
+- `timeoutMs`: ≤ 300,000 (5 minutes)
+- Concurrent parallel queries: ≤ 5
+
+**Resource usage:**
+- Memory: ~1MB per 1,000 simple records
+- Network: Proportional to page count × page size
+- API rate limits: Respect Fluent Commerce limits
+
+## TypeScript Types
+
+### Complete Type Definitions
+
+```typescript
+import { GraphQLClient } from '@fluentcommerce/fc-connect-sdk';
+
+interface PaginationConfig {
+  enabled?: boolean;
+  connectionPath?: string;
+  maxPages?: number;
+  maxRecords?: number;
+  timeoutMs?: number;
+  delayMs?: number;
+  direction?: 'forward' | 'backward';
+  abortSignal?: AbortSignal;
+  onProgress?: (page: number, totalRecords: number) => void;
+  onWarning?: (message: string) => void;
+}
+
+interface GraphQLOptions {
+  query: string;
+  variables?: Record<string, any>;
+  pagination?: PaginationConfig;
+}
+
+interface AutoPaginationMetadata {
+  totalPages: number;
+  totalRecords: number;
+  truncated: boolean;
+  timeElapsed?: number;
+}
+
+interface GraphQLResponse<T = any> {
+  data: T;
+  errors?: any[];
+  extensions: {
+    autoPagination: AutoPaginationMetadata;
+  };
+}
+
+// Usage
+const result: GraphQLResponse<{ products: Connection<Product> }> =
+  await client.graphql({
+    query: productsQuery,
+    variables: { first: 100 },
+    pagination: {
+      connectionPath: 'products',
+      maxPages: 10,
+      delayMs: 500,
+      onWarning: (msg) => console.warn(msg)
+    }
+  });
+```
+
+## Quick Reference Summary
+
+### Configuration Options
+
+| Configuration | Type | Default | Description |
+|---------------|------|---------|-------------|
+| `enabled` | `boolean` | Auto-detect | Enable/disable auto-pagination |
+| `connectionPath` | `string` | Auto-detect | Path to connection to paginate |
+| `maxPages` | `number` | `Infinity` | Max pages to fetch (OR logic) |
+| `maxRecords` | `number` | `Infinity` | Max total records (OR logic) |
+| `timeoutMs` | `number` | `Infinity` | Max time in ms (OR logic) |
+| `delayMs` | `number` | `0` | Delay between pages (ms) |
+| `direction` | `'forward'|'backward'` | Auto-detect | Pagination direction |
+| `abortSignal` | `AbortSignal` | `undefined` | Cancel pagination |
+| `onProgress` | `function` | `undefined` | Callback after each page |
+| `onWarning` | `function` | `undefined` | Callback for warnings |
+
+### Response Metadata
+
+| Metadata | Type | Description |
+|----------|------|-------------|
+| `totalPages` | `number` | Pages fetched |
+| `totalRecords` | `number` | Total records fetched |
+| `truncated` | `boolean` | Stopped due to limit |
+| `timeElapsed` | `number` | Time taken (ms) |
+
+**Note:** There is NO `truncationReason` property. To determine which limit was hit:
+- Check if `totalPages === maxPages` → maxPages limit
+- Check if `totalRecords >= maxRecords` → maxRecords limit
+- Check if `timeElapsed >= timeoutMs` → timeout limit
+
+## Related Documentation
+
+- [Module 1: Foundations](.././modules/multiple-connections-01-foundations.md) - Core concepts
+- [Module 2: Quick Start](.././modules/multiple-connections-02-quick-start.md) - Working examples
+- [Module 3: Targeting Connections](./multiple-connections-03-targeting-connections.md) - connectionPath usage
+- [Module 4: Parallel Queries](./multiple-connections-04-parallel-queries.md) - Promise.all patterns
+- [Module 5: Best Practices](./multiple-connections-05-best-practices.md) - Production patterns
+- [Auto-Pagination Guide](../../../02-CORE-GUIDES/auto-pagination/) - Core pagination documentation
+- [Main Guide](../multiple-connections-readme.md) - Back to multiple connections overview
+
+## Key Takeaways
+
+- 🎯 **connectionPath** - String path to target connection
+- 🎯 **OR-logic limits** - First limit hit stops pagination
+- 🎯 **Auto-detection** - Works but explicit is better
+- 🎯 **Relay structure** - Required for pagination
+- 🎯 **Metadata** - Check `extensions.autoPagination`
+- 🎯 **Deduplication** - Automatic by `id` field