@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/02-CORE-GUIDES/auto-pagination/auto-pagination-readme.md

@@ -1,277 +1,277 @@
-# Auto-Pagination Learning Path
-
-> **Complete guide to automatic pagination in the Fluent Connect SDK**
-> Progressive learning modules with real schema examples and verified code patterns
-
-## 📚 What You'll Learn
-
-This guide teaches you how to efficiently fetch large datasets from Fluent Commerce APIs using the SDK's automatic pagination feature. By the end, you'll understand:
-
-- ✅ How Relay-style pagination works in Fluent Commerce
-- ✅ How to write queries with real schema fields (not guessed!)
-- ✅ How to configure safety limits and performance tuning
-- ✅ How to integrate pagination with other SDK services
-- ✅ How to troubleshoot common issues and optimize performance
-
-## 🎯 Learning Path Overview
-
-This guide is organized into **7 progressive modules**. Follow them in order for the best learning experience:
-
-| Module                                                   | Topic                                                             | Level        |
-| -------------------------------------------------------- | ----------------------------------------------------------------- | ------------ |
-| [Module 1](./modules/auto-pagination-01-foundations.md)                  | **Foundations** - Why pagination matters, Relay spec basics       | Beginner     |
-| [Module 2](./modules/auto-pagination-02-quick-start.md)                  | **Quick Start** - Your first paginated query with real fields     | Beginner     |
-| [Module 3](./modules/auto-pagination-03-configuration.md)                | **Configuration Mastery** - All options, safety limits, tuning    | Intermediate |
-| [Module 4](./modules/auto-pagination-04-advanced-patterns.md)            | **Advanced Patterns** - Nested connections, fragments, aliases    | Advanced     |
-| [Module 5](./modules/auto-pagination-05-sdk-integration.md)              | **SDK Integration** - Combining with mapping, extraction, Versori | Advanced     |
-| [Module 6](./modules/auto-pagination-06-troubleshooting.md) | **Troubleshooting** - Common errors, optimization, edge cases     | Intermediate |
-| [Module 7](./modules/auto-pagination-07-api-reference.md)                | **API Reference** - Complete interface documentation              | Reference    |
-
-## 🚀 Quick Navigation
-
-### By Use Case
-
-- **First time using pagination?** → Start with [Module 1: Foundations](./modules/auto-pagination-01-foundations.md)
-- **Need a working example now?** → Jump to [Module 2: Quick Start](./modules/auto-pagination-02-quick-start.md)
-- **Experiencing performance issues?** → See [Module 6: Troubleshooting](./modules/auto-pagination-06-troubleshooting.md)
-- **Need specific config option?** → Check [Module 7: API Reference](./modules/auto-pagination-07-api-reference.md)
-- **Want code examples?** → Browse [Examples Directory](./examples/)
-
-### By Entity Type
-
-Different Fluent entities require different pagination strategies:
-
-| Entity Type           | Complexity | Recommended Page Size | Example                                              |
-| --------------------- | ---------- | --------------------- | ---------------------------------------------------- |
-| `virtualPositions`    | Simple     | 100-200               | [Example](./examples/paginate-virtual-positions.ts)  |
-| `locations`           | Simple     | 100-200               | [Example](./examples/common-patterns.ts) (see locations pattern)          |
-| `products`            | Medium     | 50-100                | [Example](./examples/paginate-products.ts)           |
-| `orders` (with items) | Complex    | 20-50                 | [Example](./examples/common-patterns.ts) (see nested patterns)      |
-| Nested connections    | Complex    | 20-50                 | [Example](./examples/common-patterns.ts) (see nested patterns) |
-
-## 📖 Quick Reference
-
-For quick lookups, see:
-
-- [Quick Reference Cheat Sheet](../advanced-services/advanced-services-quick-reference.md) - All config options on one page
-- [Common Patterns](./examples/common-patterns.ts) - Copy-paste ready snippets
-- [Troubleshooting Guide](./modules/auto-pagination-06-troubleshooting.md#common-errors) - Error messages and fixes
-
-## 🎓 Prerequisites
-
-Before starting this guide, you should:
-
-1. ✅ Have the SDK installed: `npm install @fluentcommerce/fc-connect-sdk`
-2. ✅ Have Fluent API credentials (clientId, clientSecret, retailerId)
-3. ✅ Understand basic GraphQL concepts (queries, variables, types)
-4. ✅ Be familiar with the SDK's `FluentClient` basic usage
-
-**New to the SDK?** Start with the [Getting Started Guide](../../00-START-HERE/getting-started.md) first.
-
-## 🔍 Key Concepts at a Glance
-
-### What is Auto-Pagination?
-
-```typescript
-// ❌ WITHOUT auto-pagination: Manual loop, cursor management, error-prone
-let allRecords = [];
-let cursor = null;
-let hasMore = true;
-
-while (hasMore) {
-  const result = await client.graphql({
-    query,
-    variables: { first: 100, after: cursor },
-  });
-  allRecords.push(...result.data.items.edges);
-  cursor = result.data.items.edges[result.data.items.edges.length - 1]?.cursor;
-  hasMore = result.data.items.pageInfo.hasNextPage;
-  // What if cursor is undefined? What about rate limits? Memory issues?
-}
-
-// ✅ WITH auto-pagination: Zero boilerplate, built-in safety, just works
-const result = await client.graphql({
-  query,
-  variables: { first: 100 },
-  pagination: { maxRecords: 10000 }, // Optional safety limit
-});
-
-// All pages automatically fetched, merged, and deduplicated!
-const allRecords = result.data.items.edges;
-console.log(result.extensions.autoPagination);
-// { totalPages: 15, totalRecords: 1487, truncated: false, truncationReason: undefined }
-```
-
-### How Detection Works
-
-### Cursor Selection Logic
-
-The SDK selects the next cursor based on pagination direction:
-
-- Forward pagination (default): uses the last edge cursor on each page and continues while `pageInfo.hasNextPage` is true.
-- Backward pagination (optional): uses the first edge cursor on each page and continues while `pageInfo.hasPreviousPage` is true.
-
-Requirements for queries:
-
-- Forward: include `$first`, `$after`, `edges { cursor }`, and `pageInfo { hasNextPage }`.
-- Backward: include `$last`, `$before`, `edges { cursor }`, and `pageInfo { hasPreviousPage }`.
-
-Do not pass manual pagination variables when using the `ExtractionOrchestrator`; it injects them for you.
-
-Auto-pagination activates when your query includes pagination variables:
-
-```typescript
-// ✅ Auto-pagination ENABLED (has $first and/or $after)
-query GetItems($first: Int!, $after: String) { ... }
-
-// ❌ Auto-pagination DISABLED (no pagination variables)
-query GetItems { items(first: 100) { ... } }
-
-// ❌ Auto-pagination DISABLED (mutations never auto-paginate)
-mutation CreateItem($input: CreateItemInput!) { ... }
-```
-
-### Benefits Summary
-
-| Feature                      | Manual Pagination | Auto-Pagination          |
-| ---------------------------- | ----------------- | ------------------------ |
-| **Boilerplate Code**         | 15-20 lines       | 3 lines                  |
-| **Cursor Management**        | Manual tracking   | Automatic                |
-| **Error Handling**           | Manual try-catch  | Built-in fail-fast       |
-| **Safety Limits**            | Manual checks     | Built-in OR-logic limits |
-| **Deduplication**            | Manual Set logic  | Automatic by ID          |
-| **Progress Tracking**        | Manual logging    | Built-in callbacks       |
-| **Memory Safety**            | Manual chunking   | Built-in limits          |
-| **Infinite Loop Protection** | Manual detection  | Automatic                |
-
-## 🛠️ Complete Example
-
-Here's a real-world example using verified Fluent schema fields:
-
-```typescript
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-// Create client (works in Node.js, Deno, and Versori)
-const client = await createClient({
-  config: {
-    baseUrl: process.env.FLUENT_BASE_URL!,
-    clientId: process.env.FLUENT_CLIENT_ID!,
-    clientSecret: process.env.FLUENT_CLIENT_SECRET!,
-    retailerId: process.env.FLUENT_RETAILER_ID!,
-  },
-});
-
-// Fetch all virtual positions with auto-pagination
-const result = await client.graphql({
-  query: `
-    query GetVirtualPositions($first: Int!, $after: String) {
-      virtualPositions(first: $first, after: $after) {
-        edges {
-          node {
-            id
-            productRef
-            quantity
-            groupRef
-          }
-          cursor
-        }
-        pageInfo {
-          hasNextPage
-        }
-      }
-    }
-  `,
-  variables: { first: 100 },
-  pagination: {
-    maxPages: 100, // Stop after 100 pages
-    maxRecords: 10000, // OR stop after 10K records
-    timeoutMs: 60000, // OR stop after 60 seconds
-    onProgress: (page, totalRecords) => {
-      console.log(`Page ${page}: ${totalRecords} records fetched`);
-    },
-  },
-});
-
-// All pages merged into single response
-console.log(`Total: ${result.extensions.autoPagination.totalRecords} records`);
-console.log(`Pages: ${result.extensions.autoPagination.totalPages}`);
-
-// Process all records
-for (const edge of result.data.virtualPositions.edges) {
-  console.log(`Product ${edge.node.productRef}: ${edge.node.quantity} units`);
-}
-```
-
-## 📂 Repository Structure
-
-```
-docs/guides/auto-pagination/
-├── readme.md                          # This file - main index
-├── quick-reference.md                 # Cheat sheet for quick lookups
-│
-├── modules/                           # Learning modules
-│   ├── 01-foundations.md              # Theory and concepts
-│   ├── 02-quick-start.md              # First working example
-│   ├── 03-configuration.md            # All config options
-│   ├── 04-advanced-patterns.md        # Complex queries
-│   ├── 05-sdk-integration.md          # Integration with other services
-│   ├── 06-troubleshooting.md          # Error handling and optimization
-│   └── 07-api-reference.md            # Complete API docs
-│
-└── examples/                          # Verified code examples
-    ├── readme.md                      # Examples index
-    ├── common-patterns.ts             # Copy-paste ready patterns
-    ├── paginate-virtual-positions.ts  # Simple entity
-    ├── common-patterns.ts             # All patterns (locations, orders, nested)
-    ├── paginate-products.ts           # Medium complexity
-    ├── paginate-with-transformation.ts # With UniversalMapper
-    ├── paginate-with-export.ts        # With S3 export
-    ├── paginate-versori-webhook.ts    # Versori platform
-    └── real-schema-examples.ts        # Real Fluent schema queries
-```
-
-## 🔗 Related Documentation
-
-- [Universal Mapping Guide](../mapping/modules/) - Transform paginated data
-- [Extraction Orchestrator Guide](../extraction/modules/02-core-guides-extraction-08-extraction-orchestrator.md) - High-level extraction service
-- [GraphQL Mutation Mapping](../mapping/graphql-mutation-mapping/) - Create mutations
-- [SDK Architecture](../../04-REFERENCE/architecture/) - Understanding SDK design
-- [Fluent API Documentation](https://docs.fluentcommerce.com/) - Official API docs
-
-## 🎯 FluentClient.graphql() vs ExtractionOrchestrator
-
-**Which should you use for paginated queries?**
-
-| Use Case | Recommended Approach |
-|----------|---------------------|
-| **Fetch data + custom processing** | `FluentClient.graphql()` with `pagination` option |
-| **Fetch data + export to S3/SFTP** | `ExtractionOrchestrator.extract()` |
-| **Fetch data + transform + your logic** | `FluentClient.graphql()` + `UniversalMapper` |
-| **Standard ETL pipelines** | `ExtractionOrchestrator` (pre-built patterns) |
-
-**Key Difference:**
-- `FluentClient.graphql({ pagination })` - **Direct access**, full control, manual file handling
-- `ExtractionOrchestrator.extract()` - **All-in-one**, automatic export, built-in retry logic
-
-**See:** [Module 5: When to Use Each Approach](./modules/auto-pagination-05-sdk-integration.md#when-to-use-fluentclientgraphql-vs-extractionorchestrator) for detailed comparison
-
-## 💡 Tips for Best Results
-
-1. **Always introspect schema first** - Use `npx fc-connect introspect-schema` to discover real field names
-2. **Start conservative** - Begin with small `maxPages` and `maxRecords` limits
-3. **Monitor progress** - Use `onProgress` callbacks for long operations
-4. **Match entity complexity** - Simple entities = large pages, complex entities = small pages
-5. **Test before production** - Validate queries with `maxPages: 2` first
-
-## 🚦 Getting Started
-
-Ready to begin? Start with [Module 1: Foundations →](./modules/auto-pagination-01-foundations.md)
-
----
-
-**Need Help?**
-
-- 📖 Browse [Examples](./examples/)
-- 🔍 Check [Troubleshooting](./modules/auto-pagination-06-troubleshooting.md)
-- 📧 Contact support@fluentcommerce.com
-- 🐛 Report issues at [GitHub](https://github.com/fluentcommerce/fc-connect-sdk/issues)
+# Auto-Pagination Learning Path
+
+> **Complete guide to automatic pagination in the Fluent Connect SDK**
+> Progressive learning modules with real schema examples and verified code patterns
+
+## 📚 What You'll Learn
+
+This guide teaches you how to efficiently fetch large datasets from Fluent Commerce APIs using the SDK's automatic pagination feature. By the end, you'll understand:
+
+- ✅ How Relay-style pagination works in Fluent Commerce
+- ✅ How to write queries with real schema fields (not guessed!)
+- ✅ How to configure safety limits and performance tuning
+- ✅ How to integrate pagination with other SDK services
+- ✅ How to troubleshoot common issues and optimize performance
+
+## 🎯 Learning Path Overview
+
+This guide is organized into **7 progressive modules**. Follow them in order for the best learning experience:
+
+| Module                                                   | Topic                                                             | Level        |
+| -------------------------------------------------------- | ----------------------------------------------------------------- | ------------ |
+| [Module 1](./modules/auto-pagination-01-foundations.md)                  | **Foundations** - Why pagination matters, Relay spec basics       | Beginner     |
+| [Module 2](./modules/auto-pagination-02-quick-start.md)                  | **Quick Start** - Your first paginated query with real fields     | Beginner     |
+| [Module 3](./modules/auto-pagination-03-configuration.md)                | **Configuration Mastery** - All options, safety limits, tuning    | Intermediate |
+| [Module 4](./modules/auto-pagination-04-advanced-patterns.md)            | **Advanced Patterns** - Nested connections, fragments, aliases    | Advanced     |
+| [Module 5](./modules/auto-pagination-05-sdk-integration.md)              | **SDK Integration** - Combining with mapping, extraction, Versori | Advanced     |
+| [Module 6](./modules/auto-pagination-06-troubleshooting.md) | **Troubleshooting** - Common errors, optimization, edge cases     | Intermediate |
+| [Module 7](./modules/auto-pagination-07-api-reference.md)                | **API Reference** - Complete interface documentation              | Reference    |
+
+## 🚀 Quick Navigation
+
+### By Use Case
+
+- **First time using pagination?** → Start with [Module 1: Foundations](./modules/auto-pagination-01-foundations.md)
+- **Need a working example now?** → Jump to [Module 2: Quick Start](./modules/auto-pagination-02-quick-start.md)
+- **Experiencing performance issues?** → See [Module 6: Troubleshooting](./modules/auto-pagination-06-troubleshooting.md)
+- **Need specific config option?** → Check [Module 7: API Reference](./modules/auto-pagination-07-api-reference.md)
+- **Want code examples?** → Browse [Examples Directory](./examples/)
+
+### By Entity Type
+
+Different Fluent entities require different pagination strategies:
+
+| Entity Type           | Complexity | Recommended Page Size | Example                                              |
+| --------------------- | ---------- | --------------------- | ---------------------------------------------------- |
+| `virtualPositions`    | Simple     | 100-200               | [Example](./examples/paginate-virtual-positions.ts)  |
+| `locations`           | Simple     | 100-200               | [Example](./examples/common-patterns.ts) (see locations pattern)          |
+| `products`            | Medium     | 50-100                | [Example](./examples/paginate-products.ts)           |
+| `orders` (with items) | Complex    | 20-50                 | [Example](./examples/common-patterns.ts) (see nested patterns)      |
+| Nested connections    | Complex    | 20-50                 | [Example](./examples/common-patterns.ts) (see nested patterns) |
+
+## 📖 Quick Reference
+
+For quick lookups, see:
+
+- [Quick Reference Cheat Sheet](../advanced-services/advanced-services-quick-reference.md) - All config options on one page
+- [Common Patterns](./examples/common-patterns.ts) - Copy-paste ready snippets
+- [Troubleshooting Guide](./modules/auto-pagination-06-troubleshooting.md#common-errors) - Error messages and fixes
+
+## 🎓 Prerequisites
+
+Before starting this guide, you should:
+
+1. ✅ Have the SDK installed: `npm install @fluentcommerce/fc-connect-sdk`
+2. ✅ Have Fluent API credentials (clientId, clientSecret, retailerId)
+3. ✅ Understand basic GraphQL concepts (queries, variables, types)
+4. ✅ Be familiar with the SDK's `FluentClient` basic usage
+
+**New to the SDK?** Start with the [Getting Started Guide](../../00-START-HERE/getting-started.md) first.
+
+## 🔍 Key Concepts at a Glance
+
+### What is Auto-Pagination?
+
+```typescript
+// ❌ WITHOUT auto-pagination: Manual loop, cursor management, error-prone
+let allRecords = [];
+let cursor = null;
+let hasMore = true;
+
+while (hasMore) {
+  const result = await client.graphql({
+    query,
+    variables: { first: 100, after: cursor },
+  });
+  allRecords.push(...result.data.items.edges);
+  cursor = result.data.items.edges[result.data.items.edges.length - 1]?.cursor;
+  hasMore = result.data.items.pageInfo.hasNextPage;
+  // What if cursor is undefined? What about rate limits? Memory issues?
+}
+
+// ✅ WITH auto-pagination: Zero boilerplate, built-in safety, just works
+const result = await client.graphql({
+  query,
+  variables: { first: 100 },
+  pagination: { maxRecords: 10000 }, // Optional safety limit
+});
+
+// All pages automatically fetched, merged, and deduplicated!
+const allRecords = result.data.items.edges;
+console.log(result.extensions.autoPagination);
+// { totalPages: 15, totalRecords: 1487, truncated: false, truncationReason: undefined }
+```
+
+### How Detection Works
+
+### Cursor Selection Logic
+
+The SDK selects the next cursor based on pagination direction:
+
+- Forward pagination (default): uses the last edge cursor on each page and continues while `pageInfo.hasNextPage` is true.
+- Backward pagination (optional): uses the first edge cursor on each page and continues while `pageInfo.hasPreviousPage` is true.
+
+Requirements for queries:
+
+- Forward: include `$first`, `$after`, `edges { cursor }`, and `pageInfo { hasNextPage }`.
+- Backward: include `$last`, `$before`, `edges { cursor }`, and `pageInfo { hasPreviousPage }`.
+
+Do not pass manual pagination variables when using the `ExtractionOrchestrator`; it injects them for you.
+
+Auto-pagination activates when your query includes pagination variables:
+
+```typescript
+// ✅ Auto-pagination ENABLED (has $first and/or $after)
+query GetItems($first: Int!, $after: String) { ... }
+
+// ❌ Auto-pagination DISABLED (no pagination variables)
+query GetItems { items(first: 100) { ... } }
+
+// ❌ Auto-pagination DISABLED (mutations never auto-paginate)
+mutation CreateItem($input: CreateItemInput!) { ... }
+```
+
+### Benefits Summary
+
+| Feature                      | Manual Pagination | Auto-Pagination          |
+| ---------------------------- | ----------------- | ------------------------ |
+| **Boilerplate Code**         | 15-20 lines       | 3 lines                  |
+| **Cursor Management**        | Manual tracking   | Automatic                |
+| **Error Handling**           | Manual try-catch  | Built-in fail-fast       |
+| **Safety Limits**            | Manual checks     | Built-in OR-logic limits |
+| **Deduplication**            | Manual Set logic  | Automatic by ID          |
+| **Progress Tracking**        | Manual logging    | Built-in callbacks       |
+| **Memory Safety**            | Manual chunking   | Built-in limits          |
+| **Infinite Loop Protection** | Manual detection  | Automatic                |
+
+## 🛠️ Complete Example
+
+Here's a real-world example using verified Fluent schema fields:
+
+```typescript
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+// Create client (works in Node.js, Deno, and Versori)
+const client = await createClient({
+  config: {
+    baseUrl: process.env.FLUENT_BASE_URL!,
+    clientId: process.env.FLUENT_CLIENT_ID!,
+    clientSecret: process.env.FLUENT_CLIENT_SECRET!,
+    retailerId: process.env.FLUENT_RETAILER_ID!,
+  },
+});
+
+// Fetch all virtual positions with auto-pagination
+const result = await client.graphql({
+  query: `
+    query GetVirtualPositions($first: Int!, $after: String) {
+      virtualPositions(first: $first, after: $after) {
+        edges {
+          node {
+            id
+            productRef
+            quantity
+            groupRef
+          }
+          cursor
+        }
+        pageInfo {
+          hasNextPage
+        }
+      }
+    }
+  `,
+  variables: { first: 100 },
+  pagination: {
+    maxPages: 100, // Stop after 100 pages
+    maxRecords: 10000, // OR stop after 10K records
+    timeoutMs: 60000, // OR stop after 60 seconds
+    onProgress: (page, totalRecords) => {
+      console.log(`Page ${page}: ${totalRecords} records fetched`);
+    },
+  },
+});
+
+// All pages merged into single response
+console.log(`Total: ${result.extensions.autoPagination.totalRecords} records`);
+console.log(`Pages: ${result.extensions.autoPagination.totalPages}`);
+
+// Process all records
+for (const edge of result.data.virtualPositions.edges) {
+  console.log(`Product ${edge.node.productRef}: ${edge.node.quantity} units`);
+}
+```
+
+## 📂 Repository Structure
+
+```
+docs/guides/auto-pagination/
+├── readme.md                          # This file - main index
+├── quick-reference.md                 # Cheat sheet for quick lookups
+│
+├── modules/                           # Learning modules
+│   ├── 01-foundations.md              # Theory and concepts
+│   ├── 02-quick-start.md              # First working example
+│   ├── 03-configuration.md            # All config options
+│   ├── 04-advanced-patterns.md        # Complex queries
+│   ├── 05-sdk-integration.md          # Integration with other services
+│   ├── 06-troubleshooting.md          # Error handling and optimization
+│   └── 07-api-reference.md            # Complete API docs
+│
+└── examples/                          # Verified code examples
+    ├── readme.md                      # Examples index
+    ├── common-patterns.ts             # Copy-paste ready patterns
+    ├── paginate-virtual-positions.ts  # Simple entity
+    ├── common-patterns.ts             # All patterns (locations, orders, nested)
+    ├── paginate-products.ts           # Medium complexity
+    ├── paginate-with-transformation.ts # With UniversalMapper
+    ├── paginate-with-export.ts        # With S3 export
+    ├── paginate-versori-webhook.ts    # Versori platform
+    └── real-schema-examples.ts        # Real Fluent schema queries
+```
+
+## 🔗 Related Documentation
+
+- [Universal Mapping Guide](../mapping/modules/) - Transform paginated data
+- [Extraction Orchestrator Guide](../extraction/modules/02-core-guides-extraction-08-extraction-orchestrator.md) - High-level extraction service
+- [GraphQL Mutation Mapping](../mapping/graphql-mutation-mapping/) - Create mutations
+- [SDK Architecture](../../04-REFERENCE/architecture/) - Understanding SDK design
+- [Fluent API Documentation](https://docs.fluentcommerce.com/) - Official API docs
+
+## 🎯 FluentClient.graphql() vs ExtractionOrchestrator
+
+**Which should you use for paginated queries?**
+
+| Use Case | Recommended Approach |
+|----------|---------------------|
+| **Fetch data + custom processing** | `FluentClient.graphql()` with `pagination` option |
+| **Fetch data + export to S3/SFTP** | `ExtractionOrchestrator.extract()` |
+| **Fetch data + transform + your logic** | `FluentClient.graphql()` + `UniversalMapper` |
+| **Standard ETL pipelines** | `ExtractionOrchestrator` (pre-built patterns) |
+
+**Key Difference:**
+- `FluentClient.graphql({ pagination })` - **Direct access**, full control, manual file handling
+- `ExtractionOrchestrator.extract()` - **All-in-one**, automatic export, built-in retry logic
+
+**See:** [Module 5: When to Use Each Approach](./modules/auto-pagination-05-sdk-integration.md#when-to-use-fluentclientgraphql-vs-extractionorchestrator) for detailed comparison
+
+## 💡 Tips for Best Results
+
+1. **Always introspect schema first** - Use `npx fc-connect introspect-schema` to discover real field names
+2. **Start conservative** - Begin with small `maxPages` and `maxRecords` limits
+3. **Monitor progress** - Use `onProgress` callbacks for long operations
+4. **Match entity complexity** - Simple entities = large pages, complex entities = small pages
+5. **Test before production** - Validate queries with `maxPages: 2` first
+
+## 🚦 Getting Started
+
+Ready to begin? Start with [Module 1: Foundations →](./modules/auto-pagination-01-foundations.md)
+
+---
+
+**Need Help?**
+
+- 📖 Browse [Examples](./examples/)
+- 🔍 Check [Troubleshooting](./modules/auto-pagination-06-troubleshooting.md)
+- 📧 Contact support@fluentcommerce.com
+- 🐛 Report issues at [GitHub](https://github.com/fluentcommerce/fc-connect-sdk/issues)