@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

package/docs/02-CORE-GUIDES/auto-pagination/modules/auto-pagination-07-api-reference.md

@@ -1,462 +1,462 @@
-# Module 7: Complete API Reference
-
-> **Learning Objective:** Complete technical reference for all auto-pagination interfaces, types, and behaviors.
->
-> **Level:** Reference
-
-## PaginationConfig Interface
-
-Complete configuration interface for auto-pagination control.
-
-```typescript
-interface PaginationConfig {
-  /**
-   * Enable or disable auto-pagination
-   * @default auto-detected based on query variables
-   */
-  enabled?: boolean;
-
-  /**
-   * Maximum number of pages to fetch before stopping
-   * @default 100
-   */
-  maxPages?: number;
-
-  /**
-   * Maximum total records to fetch before stopping
-   * @default 10,000
-   */
-  maxRecords?: number;
-
-  /**
-   * Overall timeout in milliseconds before stopping
-   * @default 300,000 (5 minutes)
-   */
-  timeoutMs?: number;
-
-  /**
-   * Delay between page fetches in milliseconds
-   * @default 0 (no delay)
-   */
-  delayMs?: number;
-
-  /**
-   * Pagination direction
-   * @default auto-detected from query variables
-   */
-  direction?: 'forward' | 'backward';
-
-  /**
-   * Path to connection in response (e.g., "order.items")
-   * Use dot notation for nested connections
-   * @default auto-detected (first connection found)
-   */
-  connectionPath?: string;
-
-  /**
-   * AbortSignal to cancel pagination programmatically
-   * @default undefined
-   */
-  abortSignal?: AbortSignal;
-
-  /**
-   * Callback invoked after each page fetch
-   * @param page - Current page number (1-indexed)
-   * @param totalRecords - Total records fetched so far
-   */
-  onProgress?: (page: number, totalRecords: number) => void;
-
-  /**
-   * Callback invoked when approaching limits
-   * @param message - Warning message describing the issue
-   */
-  onWarning?: (message: string) => void;
-}
-```
-
-## AutoPaginationMetadata Interface
-
-Metadata returned in `response.extensions.autoPagination`.
-
-```typescript
-interface AutoPaginationMetadata {
-  /**
-   * Total number of pages fetched
-   */
-  totalPages: number;
-
-  /**
-   * Total number of records across all pages
-   */
-  totalRecords: number;
-
-  /**
-   * Whether pagination was stopped before completion
-   */
-  truncated: boolean;
-
-  /**
-   * Reason for truncation (if truncated === true)
-   * Possible values: "maxPages" | "maxRecords" | "timeout"
-   */
-  truncationReason?: 'maxPages' | 'maxRecords' | 'timeout';
-
-  /**
-   * Pagination direction used
-   * Determined from query variables or config
-   */
-  direction?: 'forward' | 'backward';
-}
-```
-
-**Note:** The SDK tracks pagination duration internally (via `Date.now()` timestamps) but does NOT expose `timeElapsed` or `duration` in the `autoPagination` metadata. Calculate duration yourself using `Date.now()` before and after the call if needed.
-
-## GraphQL Query Requirements
-
-For auto-pagination to activate, your query must meet these requirements:
-
-### Required: Pagination Variables
-
-Query must declare pagination-related variables:
-
-```typescript
-// ✅ VALID: Forward pagination
-query MyQuery($first: Int!, $after: String) { ... }
-
-// ✅ VALID: Backward pagination
-query MyQuery($last: Int!, $before: String) { ... }
-
-// ✅ VALID: Custom names (detected automatically)
-query MyQuery($itemsFirst: Int!, $itemsAfter: String) { ... }
-
-// ❌ INVALID: No pagination variables
-query MyQuery { ... }
-```
-
-### Required: Connection Structure
-
-Response must follow Relay Connection specification:
-
-```typescript
-{
-  edges: [
-    {
-      node: { /* data */ },
-      cursor: string
-    }
-  ],
-  pageInfo: {
-    hasNextPage: boolean  // or hasPreviousPage for backward
-  }
-}
-```
-
-### Required: pageInfo Field
-
-Must include `hasNextPage` (forward) or `hasPreviousPage` (backward).
-
-**IMPORTANT:** Fluent Commerce uses **edge-based cursors only**. Unlike the full Relay spec:
-- ❌ `pageInfo.startCursor` - Not used (Fluent doesn't return this)
-- ❌ `pageInfo.endCursor` - Not used (Fluent doesn't return this)
-- ✅ `edges[].cursor` - **Required** - SDK extracts cursors from edges
-
-```graphql
-# ✅ CORRECT for Fluent
-edges {
-  node { /* data */ }
-  cursor  # ← Cursor is in edge, not pageInfo!
-}
-pageInfo {
-  hasNextPage
-}
-```
-
-### Cursor Selection Logic
-
-The SDK automatically selects the correct cursor from edges based on pagination direction:
-
-**Forward Pagination (after):**
-- Uses the **last edge's cursor** from the current page
-- Rationale: Next page starts after the last item
-
-```typescript
-// Forward pagination example
-edges = [
-  { cursor: 'abc', node: { id: 1 } },
-  { cursor: 'def', node: { id: 2 } },
-  { cursor: 'ghi', node: { id: 3 } }
-];
-// Selected cursor for next page: 'ghi' (last edge)
-```
-
-**Backward Pagination (before):**
-- Uses the **first edge's cursor** from the current page
-- Rationale: Previous page ends before the first item
-
-```typescript
-// Backward pagination example
-edges = [
-  { cursor: 'abc', node: { id: 1 } },
-  { cursor: 'def', node: { id: 2 } },
-  { cursor: 'ghi', node: { id: 3 } }
-];
-// Selected cursor for next page: 'abc' (first edge)
-```
-
-**Implementation:**
-```typescript
-// Forward direction
-const cursor = edges[edges.length - 1].cursor;  // Last edge
-
-// Backward direction
-const cursor = edges[0].cursor;  // First edge
-```
-
-## Variable Name Detection Patterns
-
-SDK automatically detects these variable name patterns:
-
-| Pattern    | Example                | Direction | Detected As |
-| ---------- | ---------------------- | --------- | ----------- |
-| `$first`   | `$first: Int!`         | Forward   | Page size   |
-| `$after`   | `$after: String`       | Forward   | Cursor      |
-| `$*First`  | `$itemsFirst: Int!`    | Forward   | Page size   |
-| `$*After`  | `$itemsAfter: String`  | Forward   | Cursor      |
-| `$last`    | `$last: Int!`          | Backward  | Page size   |
-| `$before`  | `$before: String`      | Backward  | Cursor      |
-| `$*Last`   | `$itemsLast: Int!`     | Backward  | Page size   |
-| `$*Before` | `$itemsBefore: String` | Backward  | Cursor      |
-
-**Case Sensitivity:** Detection is case-insensitive for patterns (e.g., `$First`, `$FIRST` all match).
-
-## Safety Limit Behavior (OR-Logic)
-
-Pagination stops when **ANY** limit is reached first:
-
-```typescript
-pagination: {
-  maxPages: 50,        // Limit A
-  maxRecords: 5000,    // Limit B
-  timeoutMs: 60000     // Limit C
-}
-
-// Stops when: A OR B OR C is reached
-```
-
-### Limit Evaluation Order
-
-1. **Timeout** - Checked before each page fetch
-2. **Max Pages** - Checked after each page fetch
-3. **Max Records** - Checked after each page fetch
-
-### Truncation Reason Priority
-
-If multiple limits are reached simultaneously, priority is:
-
-1. `timeout` (highest priority)
-2. `maxPages`
-3. `maxRecords` (lowest priority)
-
-## Deduplication Behavior
-
-SDK automatically deduplicates edges using a two-tier strategy:
-
-```typescript
-// Page 1: Returns edges with node.id [1, 2, 3] and cursors ['a', 'b', 'c']
-// Page 2: Returns edges with node.id [3, 4, 5] and cursors ['c', 'd', 'e']
-// ID 3 is duplicate (same node.id and cursor 'c')
-
-// Final result: [1, 2, 3, 4, 5]  // ID 3 appears only once
-```
-
-**Deduplication Strategy:**
-1. **Primary:** Deduplicates by `edge.node.id` (if present)
-2. **Fallback:** Deduplicates by `edge.cursor` (if node.id not present)
-3. **None:** If neither exists, edge is included (not deduplicated)
-
-This ensures robust deduplication across paginated responses.
-
-## Infinite Loop Protection
-
-SDK includes safeguards against infinite pagination loops:
-
-### 1. Stuck Cursor Detection
-
-```typescript
-// If same cursor returned twice consecutively, pagination stops
-// Example:
-// Page 1: lastCursor = "abc123"
-// Page 2: lastCursor = "abc123"  ← Same cursor!
-// → Pagination stops automatically
-```
-
-### 2. Empty Page Detection
-
-```typescript
-// If 3 consecutive empty pages (edges.length === 0), pagination stops
-```
-
-### 3. hasNextPage Respect
-
-```typescript
-// If pageInfo.hasNextPage === false, pagination stops
-// Even if other limits not reached
-```
-
-## Error Handling
-
-### Fail-Fast Behavior
-
-Auto-pagination **fails fast** on GraphQL errors - no partial data returned:
-
-```typescript
-try {
-  const result = await client.graphql({
-    query: invalidQuery,
-    variables: { first: 100 },
-  });
-} catch (error) {
-  // GraphQL error throws immediately
-  // No partial pages returned
-  console.error('Pagination failed:', error.message);
-}
-```
-
-### Network Retry Behavior
-
-SDK retries 5xx errors automatically (exponential backoff):
-
-- 500 Internal Server Error: Retries up to 3 times
-- 502 Bad Gateway: Retries up to 3 times
-- 503 Service Unavailable: Retries up to 3 times
-- 504 Gateway Timeout: Retries up to 3 times
-
-4xx errors **do NOT** retry:
-
-- 400 Bad Request: Immediate failure
-- 401 Unauthorized: Immediate failure
-- 403 Forbidden: Immediate failure
-- 404 Not Found: Immediate failure
-- 429 Too Many Requests: Immediate failure
-
-## Mutation Detection
-
-Auto-pagination is **always disabled** for mutations:
-
-```typescript
-// ❌ Auto-pagination DISABLED (mutation detected)
-mutation CreateOrder($first: Int!, $after: String) {
-  createOrder(input: $input) {
-    order {
-      items(first: $first, after: $after) {
-        edges { ... }
-      }
-    }
-  }
-}
-
-// Even with pagination variables, mutations never auto-paginate
-```
-
-## Default Values
-
-| Config Option    | Default Value                  | Notes                      |
-| ---------------- | ------------------------------ | -------------------------- |
-| `enabled`        | `true` (if variables detected) | Auto-detected              |
-| `maxPages`       | `100`                          | Conservative default       |
-| `maxRecords`     | `10,000`                       | Conservative default       |
-| `timeoutMs`      | `300,000` (5 minutes)          | Overall timeout            |
-| `delayMs`        | `0` (no delay)                 | For rate limiting          |
-| `direction`      | Auto-detected                  | From query variables       |
-| `connectionPath` | Auto-detected                  | First connection found     |
-| `abortSignal`    | `undefined`                    | No cancellation by default |
-| `onProgress`     | `undefined`                    | No callback                |
-| `onWarning`      | `undefined`                    | No callback                |
-
-## Type Exports
-
-All types are exported from the main SDK package:
-
-```typescript
-import type {
-  PaginationConfig,
-  AutoPaginationMetadata,
-  GraphQLResponse,
-  GraphQLPayload,
-} from '@fluentcommerce/fc-connect-sdk';
-```
-
-## Versori Platform Differences
-
-When running on Versori platform:
-
-| Aspect             | Node.js/Deno                     | Versori Platform                                 |
-| ------------------ | -------------------------------- | ------------------------------------------------ |
-| Client Creation    | `await createClient({ config })` | `await createClient(ctx)` |
-| Authentication     | OAuth2 client credentials        | Connection-based (automatic)                     |
-| Timeout Defaults   | 5 minutes                        | Same (5 minutes)                                 |
-| Progress Callbacks | Console output                   | Versori logs                                     |
-| Context Detection  | Manual                           | Automatic                                        |
-
-**Note:** Auto-pagination behavior is identical across all platforms.
-
-## Response Structure
-
-Complete structure of paginated response:
-
-```typescript
-interface GraphQLResponse<T = any> {
-  data: T; // Merged data from all pages
-  errors?: Array<{
-    message: string;
-    locations?: Array<{ line: number; column: number }>;
-    path?: string[];
-    extensions?: Record<string, unknown>;
-  }>;
-  extensions?: {
-    autoPagination?: AutoPaginationMetadata;
-    [key: string]: unknown;
-  };
-}
-```
-
-## Limitations
-
-Current limitations of auto-pagination:
-
-1. **One Connection Per Query**: Can only paginate one connection at a time
-   - Solution: Use `connectionPath` to specify which connection
-   - Or: Run separate queries for each connection
-
-2. **No Streaming**: All pages fetched into memory before returning
-   - Solution: Use manual pagination for streaming use cases
-
-3. **No Resume from Failure**: If pagination fails mid-way, must restart
-   - Solution: Use manual pagination with checkpoint persistence
-
-4. **Mutations Not Supported**: Auto-pagination disabled for all mutations
-   - Solution: Not applicable (mutations shouldn't paginate)
-
-## Source Code Reference
-
-Implementation files in SDK repository:
-
-- **Core Logic**: `src/clients/fluent-client.ts` (lines 400-600)
-- **Detection Helpers**: `src/utils/pagination-helpers.ts`
-- **Type Definitions**: `src/types/index.ts` (lines 360-420)
-- **Integration Tests**: `tests/integration/auto-pagination.integration.test.ts`
-- **Unit Tests**: `tests/unit/fluent-client-pagination.test.ts`
-
----
-
-## Summary
-
-This module provides the complete technical reference for auto-pagination. For practical usage:
-
-- **Getting Started**: [Module 2: Quick Start](./auto-pagination-02-quick-start.md)
-- **Configuration**: [Module 3: Configuration](./auto-pagination-03-configuration.md)
-- **Troubleshooting**: [Module 6: Troubleshooting](./auto-pagination-06-troubleshooting.md)
-
----
-
-[← Back to Index](../auto-pagination-readme.md) | [← Previous: Troubleshooting](./auto-pagination-06-troubleshooting.md)
+# Module 7: Complete API Reference
+
+> **Learning Objective:** Complete technical reference for all auto-pagination interfaces, types, and behaviors.
+>
+> **Level:** Reference
+
+## PaginationConfig Interface
+
+Complete configuration interface for auto-pagination control.
+
+```typescript
+interface PaginationConfig {
+  /**
+   * Enable or disable auto-pagination
+   * @default auto-detected based on query variables
+   */
+  enabled?: boolean;
+
+  /**
+   * Maximum number of pages to fetch before stopping
+   * @default 100
+   */
+  maxPages?: number;
+
+  /**
+   * Maximum total records to fetch before stopping
+   * @default 10,000
+   */
+  maxRecords?: number;
+
+  /**
+   * Overall timeout in milliseconds before stopping
+   * @default 300,000 (5 minutes)
+   */
+  timeoutMs?: number;
+
+  /**
+   * Delay between page fetches in milliseconds
+   * @default 0 (no delay)
+   */
+  delayMs?: number;
+
+  /**
+   * Pagination direction
+   * @default auto-detected from query variables
+   */
+  direction?: 'forward' | 'backward';
+
+  /**
+   * Path to connection in response (e.g., "order.items")
+   * Use dot notation for nested connections
+   * @default auto-detected (first connection found)
+   */
+  connectionPath?: string;
+
+  /**
+   * AbortSignal to cancel pagination programmatically
+   * @default undefined
+   */
+  abortSignal?: AbortSignal;
+
+  /**
+   * Callback invoked after each page fetch
+   * @param page - Current page number (1-indexed)
+   * @param totalRecords - Total records fetched so far
+   */
+  onProgress?: (page: number, totalRecords: number) => void;
+
+  /**
+   * Callback invoked when approaching limits
+   * @param message - Warning message describing the issue
+   */
+  onWarning?: (message: string) => void;
+}
+```
+
+## AutoPaginationMetadata Interface
+
+Metadata returned in `response.extensions.autoPagination`.
+
+```typescript
+interface AutoPaginationMetadata {
+  /**
+   * Total number of pages fetched
+   */
+  totalPages: number;
+
+  /**
+   * Total number of records across all pages
+   */
+  totalRecords: number;
+
+  /**
+   * Whether pagination was stopped before completion
+   */
+  truncated: boolean;
+
+  /**
+   * Reason for truncation (if truncated === true)
+   * Possible values: "maxPages" | "maxRecords" | "timeout"
+   */
+  truncationReason?: 'maxPages' | 'maxRecords' | 'timeout';
+
+  /**
+   * Pagination direction used
+   * Determined from query variables or config
+   */
+  direction?: 'forward' | 'backward';
+}
+```
+
+**Note:** The SDK tracks pagination duration internally (via `Date.now()` timestamps) but does NOT expose `timeElapsed` or `duration` in the `autoPagination` metadata. Calculate duration yourself using `Date.now()` before and after the call if needed.
+
+## GraphQL Query Requirements
+
+For auto-pagination to activate, your query must meet these requirements:
+
+### Required: Pagination Variables
+
+Query must declare pagination-related variables:
+
+```typescript
+// ✅ VALID: Forward pagination
+query MyQuery($first: Int!, $after: String) { ... }
+
+// ✅ VALID: Backward pagination
+query MyQuery($last: Int!, $before: String) { ... }
+
+// ✅ VALID: Custom names (detected automatically)
+query MyQuery($itemsFirst: Int!, $itemsAfter: String) { ... }
+
+// ❌ INVALID: No pagination variables
+query MyQuery { ... }
+```
+
+### Required: Connection Structure
+
+Response must follow Relay Connection specification:
+
+```typescript
+{
+  edges: [
+    {
+      node: { /* data */ },
+      cursor: string
+    }
+  ],
+  pageInfo: {
+    hasNextPage: boolean  // or hasPreviousPage for backward
+  }
+}
+```
+
+### Required: pageInfo Field
+
+Must include `hasNextPage` (forward) or `hasPreviousPage` (backward).
+
+**IMPORTANT:** Fluent Commerce uses **edge-based cursors only**. Unlike the full Relay spec:
+- ❌ `pageInfo.startCursor` - Not used (Fluent doesn't return this)
+- ❌ `pageInfo.endCursor` - Not used (Fluent doesn't return this)
+- ✅ `edges[].cursor` - **Required** - SDK extracts cursors from edges
+
+```graphql
+# ✅ CORRECT for Fluent
+edges {
+  node { /* data */ }
+  cursor  # ← Cursor is in edge, not pageInfo!
+}
+pageInfo {
+  hasNextPage
+}
+```
+
+### Cursor Selection Logic
+
+The SDK automatically selects the correct cursor from edges based on pagination direction:
+
+**Forward Pagination (after):**
+- Uses the **last edge's cursor** from the current page
+- Rationale: Next page starts after the last item
+
+```typescript
+// Forward pagination example
+edges = [
+  { cursor: 'abc', node: { id: 1 } },
+  { cursor: 'def', node: { id: 2 } },
+  { cursor: 'ghi', node: { id: 3 } }
+];
+// Selected cursor for next page: 'ghi' (last edge)
+```
+
+**Backward Pagination (before):**
+- Uses the **first edge's cursor** from the current page
+- Rationale: Previous page ends before the first item
+
+```typescript
+// Backward pagination example
+edges = [
+  { cursor: 'abc', node: { id: 1 } },
+  { cursor: 'def', node: { id: 2 } },
+  { cursor: 'ghi', node: { id: 3 } }
+];
+// Selected cursor for next page: 'abc' (first edge)
+```
+
+**Implementation:**
+```typescript
+// Forward direction
+const cursor = edges[edges.length - 1].cursor;  // Last edge
+
+// Backward direction
+const cursor = edges[0].cursor;  // First edge
+```
+
+## Variable Name Detection Patterns
+
+SDK automatically detects these variable name patterns:
+
+| Pattern    | Example                | Direction | Detected As |
+| ---------- | ---------------------- | --------- | ----------- |
+| `$first`   | `$first: Int!`         | Forward   | Page size   |
+| `$after`   | `$after: String`       | Forward   | Cursor      |
+| `$*First`  | `$itemsFirst: Int!`    | Forward   | Page size   |
+| `$*After`  | `$itemsAfter: String`  | Forward   | Cursor      |
+| `$last`    | `$last: Int!`          | Backward  | Page size   |
+| `$before`  | `$before: String`      | Backward  | Cursor      |
+| `$*Last`   | `$itemsLast: Int!`     | Backward  | Page size   |
+| `$*Before` | `$itemsBefore: String` | Backward  | Cursor      |
+
+**Case Sensitivity:** Detection is case-insensitive for patterns (e.g., `$First`, `$FIRST` all match).
+
+## Safety Limit Behavior (OR-Logic)
+
+Pagination stops when **ANY** limit is reached first:
+
+```typescript
+pagination: {
+  maxPages: 50,        // Limit A
+  maxRecords: 5000,    // Limit B
+  timeoutMs: 60000     // Limit C
+}
+
+// Stops when: A OR B OR C is reached
+```
+
+### Limit Evaluation Order
+
+1. **Timeout** - Checked before each page fetch
+2. **Max Pages** - Checked after each page fetch
+3. **Max Records** - Checked after each page fetch
+
+### Truncation Reason Priority
+
+If multiple limits are reached simultaneously, priority is:
+
+1. `timeout` (highest priority)
+2. `maxPages`
+3. `maxRecords` (lowest priority)
+
+## Deduplication Behavior
+
+SDK automatically deduplicates edges using a two-tier strategy:
+
+```typescript
+// Page 1: Returns edges with node.id [1, 2, 3] and cursors ['a', 'b', 'c']
+// Page 2: Returns edges with node.id [3, 4, 5] and cursors ['c', 'd', 'e']
+// ID 3 is duplicate (same node.id and cursor 'c')
+
+// Final result: [1, 2, 3, 4, 5]  // ID 3 appears only once
+```
+
+**Deduplication Strategy:**
+1. **Primary:** Deduplicates by `edge.node.id` (if present)
+2. **Fallback:** Deduplicates by `edge.cursor` (if node.id not present)
+3. **None:** If neither exists, edge is included (not deduplicated)
+
+This ensures robust deduplication across paginated responses.
+
+## Infinite Loop Protection
+
+SDK includes safeguards against infinite pagination loops:
+
+### 1. Stuck Cursor Detection
+
+```typescript
+// If same cursor returned twice consecutively, pagination stops
+// Example:
+// Page 1: lastCursor = "abc123"
+// Page 2: lastCursor = "abc123"  ← Same cursor!
+// → Pagination stops automatically
+```
+
+### 2. Empty Page Detection
+
+```typescript
+// If 3 consecutive empty pages (edges.length === 0), pagination stops
+```
+
+### 3. hasNextPage Respect
+
+```typescript
+// If pageInfo.hasNextPage === false, pagination stops
+// Even if other limits not reached
+```
+
+## Error Handling
+
+### Fail-Fast Behavior
+
+Auto-pagination **fails fast** on GraphQL errors - no partial data returned:
+
+```typescript
+try {
+  const result = await client.graphql({
+    query: invalidQuery,
+    variables: { first: 100 },
+  });
+} catch (error) {
+  // GraphQL error throws immediately
+  // No partial pages returned
+  console.error('Pagination failed:', error.message);
+}
+```
+
+### Network Retry Behavior
+
+SDK retries 5xx errors automatically (exponential backoff):
+
+- 500 Internal Server Error: Retries up to 3 times
+- 502 Bad Gateway: Retries up to 3 times
+- 503 Service Unavailable: Retries up to 3 times
+- 504 Gateway Timeout: Retries up to 3 times
+
+4xx errors **do NOT** retry:
+
+- 400 Bad Request: Immediate failure
+- 401 Unauthorized: Immediate failure
+- 403 Forbidden: Immediate failure
+- 404 Not Found: Immediate failure
+- 429 Too Many Requests: Immediate failure
+
+## Mutation Detection
+
+Auto-pagination is **always disabled** for mutations:
+
+```typescript
+// ❌ Auto-pagination DISABLED (mutation detected)
+mutation CreateOrder($first: Int!, $after: String) {
+  createOrder(input: $input) {
+    order {
+      items(first: $first, after: $after) {
+        edges { ... }
+      }
+    }
+  }
+}
+
+// Even with pagination variables, mutations never auto-paginate
+```
+
+## Default Values
+
+| Config Option    | Default Value                  | Notes                      |
+| ---------------- | ------------------------------ | -------------------------- |
+| `enabled`        | `true` (if variables detected) | Auto-detected              |
+| `maxPages`       | `100`                          | Conservative default       |
+| `maxRecords`     | `10,000`                       | Conservative default       |
+| `timeoutMs`      | `300,000` (5 minutes)          | Overall timeout            |
+| `delayMs`        | `0` (no delay)                 | For rate limiting          |
+| `direction`      | Auto-detected                  | From query variables       |
+| `connectionPath` | Auto-detected                  | First connection found     |
+| `abortSignal`    | `undefined`                    | No cancellation by default |
+| `onProgress`     | `undefined`                    | No callback                |
+| `onWarning`      | `undefined`                    | No callback                |
+
+## Type Exports
+
+All types are exported from the main SDK package:
+
+```typescript
+import type {
+  PaginationConfig,
+  AutoPaginationMetadata,
+  GraphQLResponse,
+  GraphQLPayload,
+} from '@fluentcommerce/fc-connect-sdk';
+```
+
+## Versori Platform Differences
+
+When running on Versori platform:
+
+| Aspect             | Node.js/Deno                     | Versori Platform                                 |
+| ------------------ | -------------------------------- | ------------------------------------------------ |
+| Client Creation    | `await createClient({ config })` | `await createClient(ctx)` |
+| Authentication     | OAuth2 client credentials        | Connection-based (automatic)                     |
+| Timeout Defaults   | 5 minutes                        | Same (5 minutes)                                 |
+| Progress Callbacks | Console output                   | Versori logs                                     |
+| Context Detection  | Manual                           | Automatic                                        |
+
+**Note:** Auto-pagination behavior is identical across all platforms.
+
+## Response Structure
+
+Complete structure of paginated response:
+
+```typescript
+interface GraphQLResponse<T = any> {
+  data: T; // Merged data from all pages
+  errors?: Array<{
+    message: string;
+    locations?: Array<{ line: number; column: number }>;
+    path?: string[];
+    extensions?: Record<string, unknown>;
+  }>;
+  extensions?: {
+    autoPagination?: AutoPaginationMetadata;
+    [key: string]: unknown;
+  };
+}
+```
+
+## Limitations
+
+Current limitations of auto-pagination:
+
+1. **One Connection Per Query**: Can only paginate one connection at a time
+   - Solution: Use `connectionPath` to specify which connection
+   - Or: Run separate queries for each connection
+
+2. **No Streaming**: All pages fetched into memory before returning
+   - Solution: Use manual pagination for streaming use cases
+
+3. **No Resume from Failure**: If pagination fails mid-way, must restart
+   - Solution: Use manual pagination with checkpoint persistence
+
+4. **Mutations Not Supported**: Auto-pagination disabled for all mutations
+   - Solution: Not applicable (mutations shouldn't paginate)
+
+## Source Code Reference
+
+Implementation files in SDK repository:
+
+- **Core Logic**: `src/clients/fluent-client.ts` (lines 400-600)
+- **Detection Helpers**: `src/utils/pagination-helpers.ts`
+- **Type Definitions**: `src/types/index.ts` (lines 360-420)
+- **Integration Tests**: `tests/integration/auto-pagination.integration.test.ts`
+- **Unit Tests**: `tests/unit/fluent-client-pagination.test.ts`
+
+---
+
+## Summary
+
+This module provides the complete technical reference for auto-pagination. For practical usage:
+
+- **Getting Started**: [Module 2: Quick Start](./auto-pagination-02-quick-start.md)
+- **Configuration**: [Module 3: Configuration](./auto-pagination-03-configuration.md)
+- **Troubleshooting**: [Module 6: Troubleshooting](./auto-pagination-06-troubleshooting.md)
+
+---
+
+[← Back to Index](../auto-pagination-readme.md) | [← Previous: Troubleshooting](./auto-pagination-06-troubleshooting.md)