@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/02-CORE-GUIDES/auto-pagination/auto-pagination-quick-reference.md

@@ -1,351 +1,351 @@
-# Auto-Pagination Quick Reference
-
-> One-page cheat sheet for auto-pagination configuration and usage
-
-## Basic Usage
-
-```typescript
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-const client = await createClient({
-  config: {
-    baseUrl: process.env.FLUENT_BASE_URL!,
-    retailerId: process.env.FLUENT_RETAILER_ID!,
-    clientId: process.env.FLUENT_CLIENT_ID!,
-    clientSecret: process.env.FLUENT_CLIENT_SECRET!,
-  },
-});
-
-const result = await client.graphql({
-  query: `
-    query GetItems($first: Int!, $after: String) {
-      items(first: $first, after: $after) {
-        edges {
-          node { id field1 field2 }
-          cursor
-        }
-        pageInfo { hasNextPage }
-      }
-    }
-  `,
-  variables: { first: 100 },
-  pagination: { maxPages: 50, maxRecords: 5000 },
-});
-
-console.log(result.extensions.autoPagination);
-```
-
-## Configuration Options
-
-| Option           | Type        | Default   | Description                              |
-| ---------------- | ----------- | --------- | ---------------------------------------- |
-| `enabled`        | boolean     | auto      | Enable/disable auto-pagination           |
-| `maxPages`       | number      | 100       | Max pages to fetch (OR-logic)            |
-| `maxRecords`     | number      | 10,000    | Max records to fetch (OR-logic)          |
-| `timeoutMs`      | number      | 300,000   | Timeout in ms (OR-logic)                 |
-| `delayMs`        | number      | 0         | Delay between pages (ms)                 |
-| `direction`      | string      | auto      | 'forward' or 'backward'                  |
-| `connectionPath` | string      | auto      | Path to connection (e.g., "order.items") |
-| `abortSignal`    | AbortSignal | undefined | Cancellation signal                      |
-| `onProgress`     | function    | undefined | `(page, records) => void`                |
-| `onWarning`      | function    | undefined | `(message) => void`                      |
-
-**Note:** Page size (e.g., `first: 100`) is specified in query `variables`, not in `pagination` config.
-
-## Entity-Specific Recommendations
-
-| Entity              | first | maxPages | maxRecords | delayMs | Complexity |
-| ------------------- | ----- | -------- | ---------- | ------- | ---------- |
-| virtualPositions    | 150   | 100      | 15000      | 0       | Simple     |
-| locations           | 100   | 100      | 10000      | 0       | Simple     |
-| products            | 75    | 50       | 5000       | 0       | Medium     |
-| orders (with items) | 20    | 30       | 1000       | 100     | Complex    |
-
-## Query Requirements Checklist
-
-✅ Include pagination variables (`$first`, `$after`)
-✅ Use variables in query arguments
-✅ Include `cursor` field in edges
-✅ Include `pageInfo { hasNextPage }`
-✅ Follow Relay Connection structure
-
-## Common Patterns
-
-### Simple Pagination
-
-```typescript
-const result = await client.graphql({
-  query,
-  variables: { first: 100 },
-  pagination: { maxRecords: 5000 },
-});
-```
-
-### With Progress Tracking
-
-```typescript
-const result = await client.graphql({
-  query,
-  variables: { first: 100 },
-  pagination: {
-    maxRecords: 10000,
-    onProgress: (page, records) => {
-      console.log(`Page ${page}: ${records} records`);
-    },
-  },
-});
-```
-
-### Nested Connection
-
-```typescript
-const result = await client.graphql({
-  query,
-  variables: { orderId: 'ORDER-123', first: 50 },
-  pagination: {
-    connectionPath: 'order.items',
-    maxPages: 20,
-  },
-});
-```
-
-### With Rate Limiting
-
-```typescript
-const result = await client.graphql({
-  query,
-  variables: { first: 75 },
-  pagination: {
-    maxRecords: 5000,
-    delayMs: 100, // 100ms between pages
-  },
-});
-```
-
-### With Abort Signal
-
-```typescript
-const controller = new AbortController();
-setTimeout(() => controller.abort(), 60000);
-
-const result = await client.graphql({
-  query,
-  variables: { first: 100 },
-  pagination: { abortSignal: controller.signal },
-});
-```
-
-## Response Structure
-
-```typescript
-{
-  data: {
-    items: {
-      edges: [/* all pages merged */],
-      pageInfo: { hasNextPage: false }
-    }
-  },
-  extensions: {
-    autoPagination: {
-      totalPages: 15,
-      totalRecords: 1487,
-      truncated: false,
-      truncationReason: undefined,  // "maxPages" | "maxRecords" | "timeout" if truncated
-      direction: "forward"  // Direction used for pagination
-    }
-  }
-}
-```
-
-**Note:** `timeElapsed` and `duration` are NOT included in the response. Calculate duration using `Date.now()` before and after the call if needed.
-
-## Common Errors & Fixes
-
-| Error                            | Cause                | Fix                                 |
-| -------------------------------- | -------------------- | ----------------------------------- |
-| "Cannot read property 'edges'"   | Wrong connectionPath | Match response structure            |
-| "Auto-pagination not activating" | Missing variables    | Add `$first`, `$after` to query     |
-| Memory exhaustion (OOM)          | Too many records     | Reduce `maxRecords` or use chunking |
-| Timeout errors                   | Query too complex    | Reduce `first` (page size)          |
-| "Field doesn't exist"            | Wrong field name     | Use schema introspection            |
-
-## Introspect Schema
-
-Always discover real fields before writing queries:
-
-```bash
-npx fc-connect introspect-schema \
-  --endpoint https://your-account.api.fluentretail.com/graphql \
-  --output schema.json
-```
-
-## Real Field Names (Verified)
-
-### VirtualPosition
-
-```graphql
-{
-  id
-  ref
-  productRef
-  quantity
-  groupRef
-  status
-  type
-  createdOn
-  updatedOn
-}
-```
-
-### Location
-
-```graphql
-{
-  id
-  ref
-  name
-  type
-  status
-  defaultCarrier
-}
-```
-
-### Product
-
-```graphql
-{
-  id
-  ref
-  type
-  status
-  gtin
-}
-```
-
-### Order
-
-```graphql
-{
-  id
-  ref
-  status
-  type
-  totalPrice
-  totalTax
-  createdOn
-}
-```
-
-## When NOT to Use Auto-Pagination
-
-❌ **Very large datasets** (50K+ records) → Use manual pagination with chunking
-❌ **Streaming ETL** → Process each page immediately, don't load all
-❌ **Fine-grained error recovery** → Handle errors per page
-❌ **Mutations** → Auto-pagination always disabled for mutations
-
-## Performance Tips
-
-✅ Match page size to entity complexity
-✅ Use progress callbacks for monitoring
-✅ Start with conservative limits
-✅ Add delays for rate limiting
-✅ Test with small limits first
-✅ Use parallel fetching for multiple entities
-
-## Safety Limits (OR-Logic)
-
-Pagination stops when **first** limit reached:
-
-```typescript
-pagination: {
-  maxPages: 50,        // Stop after 50 pages
-  maxRecords: 5000,    // OR stop after 5000 records
-  timeoutMs: 60000,    // OR stop after 60 seconds
-}
-```
-
-## Check Truncation
-
-```typescript
-if (result.extensions.autoPagination.truncated) {
-  console.warn(`Truncated: ${result.extensions.autoPagination.truncationReason}`);
-  // Reasons: "maxPages" | "maxRecords" | "timeout"
-}
-```
-
-## Default Values
-
-```typescript
-{
-  enabled: true (if variables detected),
-  maxPages: 100,
-  maxRecords: 10000,
-  timeoutMs: 300000,  // 5 minutes
-  delayMs: 0,
-  direction: 'forward' (auto-detected),
-  connectionPath: undefined (auto-detected),
-  abortSignal: undefined,
-  onProgress: undefined,
-  onWarning: undefined
-}
-```
-
-## Variable Name Patterns (Auto-Detected)
-
-| Pattern    | Example                | Direction |
-| ---------- | ---------------------- | --------- |
-| `$first`   | `$first: Int!`         | Forward   |
-| `$after`   | `$after: String`       | Forward   |
-| `$*First`  | `$itemsFirst: Int!`    | Forward   |
-| `$*After`  | `$itemsAfter: String`  | Forward   |
-| `$last`    | `$last: Int!`          | Backward  |
-| `$before`  | `$before: String`      | Backward  |
-| `$*Last`   | `$itemsLast: Int!`     | Backward  |
-| `$*Before` | `$itemsBefore: String` | Backward  |
-
-## Integration with SDK Services
-
-### With UniversalMapper
-
-```typescript
-const result = await client.graphql({ query, variables, pagination });
-const mapper = new UniversalMapper(mappingConfig);
-const transformed = await mapper.mapArray(result.data.items.edges);
-```
-
-### With S3 Export
-
-```typescript
-const result = await client.graphql({ query, variables, pagination });
-const s3 = new S3DataSource(config);
-await s3.writeFile('output.json', JSON.stringify(result.data));
-```
-
-### In Versori Workflow
-
-```typescript
-import { webhook, fn } from '@versori/run';
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-export const sync = webhook('sync').then(
-  fn('paginate', async (ctx) => {
-    const client = await createClient(ctx); // Auto-detects Versori context
-    const result = await client.graphql({ query, variables, pagination });
-    return result.data;
-  })
-);
-```
-
-## Further Reading
-
-- [Module 1: Foundations](./modules/auto-pagination-01-foundations.md) - Theory and concepts
-- [Module 2: Quick Start](./modules/auto-pagination-02-quick-start.md) - First working example
-- [Module 3: Configuration](./modules/auto-pagination-03-configuration.md) - All options explained
-- [Module 4: Advanced Patterns](./modules/auto-pagination-04-advanced-patterns.md) - Complex scenarios
-- [Module 5: SDK Integration](./modules/auto-pagination-05-sdk-integration.md) - Integration patterns
-- [Module 6: Troubleshooting](./modules/auto-pagination-06-troubleshooting.md) - Common issues
-- [Module 7: API Reference](./modules/auto-pagination-07-api-reference.md) - Complete API docs
-
----
-
-**Need Help?** Check the [main documentation](../advanced-services/advanced-services-readme.md) or [troubleshooting guide](./modules/auto-pagination-06-troubleshooting.md).
+# Auto-Pagination Quick Reference
+
+> One-page cheat sheet for auto-pagination configuration and usage
+
+## Basic Usage
+
+```typescript
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+const client = await createClient({
+  config: {
+    baseUrl: process.env.FLUENT_BASE_URL!,
+    retailerId: process.env.FLUENT_RETAILER_ID!,
+    clientId: process.env.FLUENT_CLIENT_ID!,
+    clientSecret: process.env.FLUENT_CLIENT_SECRET!,
+  },
+});
+
+const result = await client.graphql({
+  query: `
+    query GetItems($first: Int!, $after: String) {
+      items(first: $first, after: $after) {
+        edges {
+          node { id field1 field2 }
+          cursor
+        }
+        pageInfo { hasNextPage }
+      }
+    }
+  `,
+  variables: { first: 100 },
+  pagination: { maxPages: 50, maxRecords: 5000 },
+});
+
+console.log(result.extensions.autoPagination);
+```
+
+## Configuration Options
+
+| Option           | Type        | Default   | Description                              |
+| ---------------- | ----------- | --------- | ---------------------------------------- |
+| `enabled`        | boolean     | auto      | Enable/disable auto-pagination           |
+| `maxPages`       | number      | 100       | Max pages to fetch (OR-logic)            |
+| `maxRecords`     | number      | 10,000    | Max records to fetch (OR-logic)          |
+| `timeoutMs`      | number      | 300,000   | Timeout in ms (OR-logic)                 |
+| `delayMs`        | number      | 0         | Delay between pages (ms)                 |
+| `direction`      | string      | auto      | 'forward' or 'backward'                  |
+| `connectionPath` | string      | auto      | Path to connection (e.g., "order.items") |
+| `abortSignal`    | AbortSignal | undefined | Cancellation signal                      |
+| `onProgress`     | function    | undefined | `(page, records) => void`                |
+| `onWarning`      | function    | undefined | `(message) => void`                      |
+
+**Note:** Page size (e.g., `first: 100`) is specified in query `variables`, not in `pagination` config.
+
+## Entity-Specific Recommendations
+
+| Entity              | first | maxPages | maxRecords | delayMs | Complexity |
+| ------------------- | ----- | -------- | ---------- | ------- | ---------- |
+| virtualPositions    | 150   | 100      | 15000      | 0       | Simple     |
+| locations           | 100   | 100      | 10000      | 0       | Simple     |
+| products            | 75    | 50       | 5000       | 0       | Medium     |
+| orders (with items) | 20    | 30       | 1000       | 100     | Complex    |
+
+## Query Requirements Checklist
+
+✅ Include pagination variables (`$first`, `$after`)
+✅ Use variables in query arguments
+✅ Include `cursor` field in edges
+✅ Include `pageInfo { hasNextPage }`
+✅ Follow Relay Connection structure
+
+## Common Patterns
+
+### Simple Pagination
+
+```typescript
+const result = await client.graphql({
+  query,
+  variables: { first: 100 },
+  pagination: { maxRecords: 5000 },
+});
+```
+
+### With Progress Tracking
+
+```typescript
+const result = await client.graphql({
+  query,
+  variables: { first: 100 },
+  pagination: {
+    maxRecords: 10000,
+    onProgress: (page, records) => {
+      console.log(`Page ${page}: ${records} records`);
+    },
+  },
+});
+```
+
+### Nested Connection
+
+```typescript
+const result = await client.graphql({
+  query,
+  variables: { orderId: 'ORDER-123', first: 50 },
+  pagination: {
+    connectionPath: 'order.items',
+    maxPages: 20,
+  },
+});
+```
+
+### With Rate Limiting
+
+```typescript
+const result = await client.graphql({
+  query,
+  variables: { first: 75 },
+  pagination: {
+    maxRecords: 5000,
+    delayMs: 100, // 100ms between pages
+  },
+});
+```
+
+### With Abort Signal
+
+```typescript
+const controller = new AbortController();
+setTimeout(() => controller.abort(), 60000);
+
+const result = await client.graphql({
+  query,
+  variables: { first: 100 },
+  pagination: { abortSignal: controller.signal },
+});
+```
+
+## Response Structure
+
+```typescript
+{
+  data: {
+    items: {
+      edges: [/* all pages merged */],
+      pageInfo: { hasNextPage: false }
+    }
+  },
+  extensions: {
+    autoPagination: {
+      totalPages: 15,
+      totalRecords: 1487,
+      truncated: false,
+      truncationReason: undefined,  // "maxPages" | "maxRecords" | "timeout" if truncated
+      direction: "forward"  // Direction used for pagination
+    }
+  }
+}
+```
+
+**Note:** `timeElapsed` and `duration` are NOT included in the response. Calculate duration using `Date.now()` before and after the call if needed.
+
+## Common Errors & Fixes
+
+| Error                            | Cause                | Fix                                 |
+| -------------------------------- | -------------------- | ----------------------------------- |
+| "Cannot read property 'edges'"   | Wrong connectionPath | Match response structure            |
+| "Auto-pagination not activating" | Missing variables    | Add `$first`, `$after` to query     |
+| Memory exhaustion (OOM)          | Too many records     | Reduce `maxRecords` or use chunking |
+| Timeout errors                   | Query too complex    | Reduce `first` (page size)          |
+| "Field doesn't exist"            | Wrong field name     | Use schema introspection            |
+
+## Introspect Schema
+
+Always discover real fields before writing queries:
+
+```bash
+npx fc-connect introspect-schema \
+  --endpoint https://your-account.api.fluentretail.com/graphql \
+  --output schema.json
+```
+
+## Real Field Names (Verified)
+
+### VirtualPosition
+
+```graphql
+{
+  id
+  ref
+  productRef
+  quantity
+  groupRef
+  status
+  type
+  createdOn
+  updatedOn
+}
+```
+
+### Location
+
+```graphql
+{
+  id
+  ref
+  name
+  type
+  status
+  defaultCarrier
+}
+```
+
+### Product
+
+```graphql
+{
+  id
+  ref
+  type
+  status
+  gtin
+}
+```
+
+### Order
+
+```graphql
+{
+  id
+  ref
+  status
+  type
+  totalPrice
+  totalTax
+  createdOn
+}
+```
+
+## When NOT to Use Auto-Pagination
+
+❌ **Very large datasets** (50K+ records) → Use manual pagination with chunking
+❌ **Streaming ETL** → Process each page immediately, don't load all
+❌ **Fine-grained error recovery** → Handle errors per page
+❌ **Mutations** → Auto-pagination always disabled for mutations
+
+## Performance Tips
+
+✅ Match page size to entity complexity
+✅ Use progress callbacks for monitoring
+✅ Start with conservative limits
+✅ Add delays for rate limiting
+✅ Test with small limits first
+✅ Use parallel fetching for multiple entities
+
+## Safety Limits (OR-Logic)
+
+Pagination stops when **first** limit reached:
+
+```typescript
+pagination: {
+  maxPages: 50,        // Stop after 50 pages
+  maxRecords: 5000,    // OR stop after 5000 records
+  timeoutMs: 60000,    // OR stop after 60 seconds
+}
+```
+
+## Check Truncation
+
+```typescript
+if (result.extensions.autoPagination.truncated) {
+  console.warn(`Truncated: ${result.extensions.autoPagination.truncationReason}`);
+  // Reasons: "maxPages" | "maxRecords" | "timeout"
+}
+```
+
+## Default Values
+
+```typescript
+{
+  enabled: true (if variables detected),
+  maxPages: 100,
+  maxRecords: 10000,
+  timeoutMs: 300000,  // 5 minutes
+  delayMs: 0,
+  direction: 'forward' (auto-detected),
+  connectionPath: undefined (auto-detected),
+  abortSignal: undefined,
+  onProgress: undefined,
+  onWarning: undefined
+}
+```
+
+## Variable Name Patterns (Auto-Detected)
+
+| Pattern    | Example                | Direction |
+| ---------- | ---------------------- | --------- |
+| `$first`   | `$first: Int!`         | Forward   |
+| `$after`   | `$after: String`       | Forward   |
+| `$*First`  | `$itemsFirst: Int!`    | Forward   |
+| `$*After`  | `$itemsAfter: String`  | Forward   |
+| `$last`    | `$last: Int!`          | Backward  |
+| `$before`  | `$before: String`      | Backward  |
+| `$*Last`   | `$itemsLast: Int!`     | Backward  |
+| `$*Before` | `$itemsBefore: String` | Backward  |
+
+## Integration with SDK Services
+
+### With UniversalMapper
+
+```typescript
+const result = await client.graphql({ query, variables, pagination });
+const mapper = new UniversalMapper(mappingConfig);
+const transformed = await mapper.mapArray(result.data.items.edges);
+```
+
+### With S3 Export
+
+```typescript
+const result = await client.graphql({ query, variables, pagination });
+const s3 = new S3DataSource(config);
+await s3.writeFile('output.json', JSON.stringify(result.data));
+```
+
+### In Versori Workflow
+
+```typescript
+import { webhook, fn } from '@versori/run';
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+export const sync = webhook('sync').then(
+  fn('paginate', async (ctx) => {
+    const client = await createClient(ctx); // Auto-detects Versori context
+    const result = await client.graphql({ query, variables, pagination });
+    return result.data;
+  })
+);
+```
+
+## Further Reading
+
+- [Module 1: Foundations](./modules/auto-pagination-01-foundations.md) - Theory and concepts
+- [Module 2: Quick Start](./modules/auto-pagination-02-quick-start.md) - First working example
+- [Module 3: Configuration](./modules/auto-pagination-03-configuration.md) - All options explained
+- [Module 4: Advanced Patterns](./modules/auto-pagination-04-advanced-patterns.md) - Complex scenarios
+- [Module 5: SDK Integration](./modules/auto-pagination-05-sdk-integration.md) - Integration patterns
+- [Module 6: Troubleshooting](./modules/auto-pagination-06-troubleshooting.md) - Common issues
+- [Module 7: API Reference](./modules/auto-pagination-07-api-reference.md) - Complete API docs
+
+---
+
+**Need Help?** Check the [main documentation](../advanced-services/advanced-services-readme.md) or [troubleshooting guide](./modules/auto-pagination-06-troubleshooting.md).