@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

package/docs/02-CORE-GUIDES/auto-pagination/examples/common-patterns.ts

@@ -1,351 +1,351 @@
-/**
- * Auto-Pagination Common Patterns
- *
- * Complete examples showing various pagination scenarios with the FC Connect SDK.
- * All examples use real Fluent Commerce schema fields and cursor-based pagination.
- *
- * @package @fluentcommerce/fc-connect-sdk
- * @see https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk
- */
-
-import { createClient, FluentClient } from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * Pattern 1: Auto-Pagination with Safety Limits
- *
- * The SDK automatically handles pagination with configurable safety limits
- * to prevent runaway queries.
- */
-export async function autoPaginationWithLimits() {
-  const client = await createClient({
-    config: {
-      baseUrl: 'https://api.fluentcommerce.com',
-      clientId: process.env.FLUENT_CLIENT_ID!,
-      clientSecret: process.env.FLUENT_CLIENT_SECRET!,
-      retailerId: process.env.FLUENT_RETAILER_ID!,
-      username: process.env.FLUENT_USERNAME!,
-      password: process.env.FLUENT_PASSWORD!,
-    },
-  });
-
-  try {
-    // Auto-pagination fetches all pages and merges results
-    const result = await client.graphql({
-      query: `
-        query GetOrders($first: Int!, $after: String) {
-          orders(first: $first, after: $after) {
-            edges {
-              cursor
-              node {
-                id
-                ref
-                type
-                status
-                totalPrice
-              }
-            }
-            pageInfo {
-              hasNextPage
-              # Note: Fluent doesn't return endCursor/startCursor - cursors are in edges[].cursor
-            }
-          }
-        }
-      `,
-      variables: { first: 100 },
-      pagination: {
-        maxPages: 50, // Stop after 50 pages
-        maxRecords: 5000, // OR stop after 5000 records
-        timeoutMs: 60000, // OR stop after 60 seconds
-        onProgress: (page, totalRecords) => {
-          console.log(`Fetched page ${page}, total records: ${totalRecords}`);
-        },
-      },
-    });
-
-    // All pages are merged into a single result
-    const allOrders = result.data.orders.edges.map((e: any) => e.node);
-
-    // Check if pagination was truncated
-    const { totalPages, totalRecords, truncated } = result.extensions.autoPagination;
-    console.log(`Total: ${totalRecords} orders across ${totalPages} pages`);
-
-    if (truncated) {
-      console.warn('Pagination stopped early due to safety limits');
-    }
-
-    return allOrders;
-  } catch (error) {
-    console.error('Auto-pagination failed:', error);
-    throw error;
-  }
-}
-
-/**
- * Pattern 2: Manual Cursor-Based Pagination
- *
- * For complete control over pagination logic, manually manage cursors
- * and page fetching.
- */
-export async function manualCursorPagination(client: FluentClient) {
-  const allProducts = [];
-  let hasNextPage = true;
-  let cursor: string | undefined = undefined;
-  let pageCount = 0;
-
-  const query = `
-    query GetProducts($first: Int!, $after: String) {
-      products(first: $first, after: $after) {
-        edges {
-          cursor
-          node {
-            id
-            ref
-            name
-            type
-            status
-          }
-        }
-        pageInfo {
-          hasNextPage
-          # Note: Fluent doesn't return endCursor/startCursor - cursors are in edges[].cursor
-        }
-      }
-    }
-  `;
-
-  try {
-    while (hasNextPage) {
-      pageCount++;
-
-      // Fetch single page with manual pagination disabled
-      const result = await client.graphql({
-        query,
-        variables: { first: 200, after: cursor },
-        pagination: { enabled: false }, // Disable auto-pagination
-      });
-
-      const products = result.data.products.edges.map((e: any) => e.node);
-      allProducts.push(...products);
-
-      // Extract pagination info using edge cursors (Fluent does not return endCursor in pageInfo)
-      hasNextPage = result.data.products.pageInfo.hasNextPage;
-      const edges = result.data.products.edges || [];
-      cursor = edges.length > 0 ? edges[edges.length - 1].cursor : undefined;
-
-      console.log(`Page ${pageCount}: ${products.length} products (total: ${allProducts.length})`);
-
-      // Optional: Add delay to avoid rate limiting
-      if (hasNextPage) {
-        await new Promise(resolve => setTimeout(resolve, 100));
-      }
-    }
-
-    return allProducts;
-  } catch (error) {
-    console.error('Manual pagination failed:', error);
-    throw error;
-  }
-}
-
-/**
- * Pattern 3: Generator-Based Streaming Pagination
- *
- * Use async generators for memory-efficient processing of large datasets.
- * Process records as they arrive instead of loading everything into memory.
- */
-export async function* streamPaginatedResults(client: FluentClient) {
-  let hasNextPage = true;
-  let cursor: string | undefined = undefined;
-
-  const query = `
-    query GetVirtualPositions($first: Int!, $after: String) {
-      virtualPositions(first: $first, after: $after) {
-        edges {
-          cursor
-          node {
-            id
-            ref
-            type
-            status
-            productRef
-            groupRef
-            quantity
-          }
-        }
-        pageInfo {
-          hasNextPage
-          # Note: Fluent doesn't return endCursor/startCursor - cursors are in edges[].cursor
-        }
-      }
-    }
-  `;
-
-  while (hasNextPage) {
-    try {
-      const result = await client.graphql({
-        query,
-        variables: { first: 500, after: cursor },
-        pagination: { enabled: false },
-      });
-
-      const positions = result.data.virtualPositions.edges.map((e: any) => e.node);
-
-      // Yield batch of records for immediate processing
-      yield positions;
-
-      hasNextPage = result.data.virtualPositions.pageInfo.hasNextPage;
-      const edges = result.data.virtualPositions.edges || [];
-      cursor = edges.length > 0 ? edges[edges.length - 1].cursor : undefined;
-    } catch (error) {
-      console.error('Streaming pagination error:', error);
-      throw error;
-    }
-  }
-}
-
-/**
- * Pattern 4: Filtered Pagination with GraphQL Variables
- *
- * Combine pagination with filtering using GraphQL variables.
- */
-export async function paginateWithFilters(client: FluentClient) {
-  const result = await client.graphql({
-    query: `
-      query GetFilteredOrders(
-        $first: Int!
-        $after: String
-        $status: [String!]
-        $createdFrom: DateTime
-      ) {
-        orders(
-          first: $first
-          after: $after
-          status: $status
-          createdOn: { from: $createdFrom }
-        ) {
-          edges {
-            cursor
-            node {
-              id
-              ref
-              status
-              createdOn
-              totalPrice
-            }
-          }
-          pageInfo {
-            hasNextPage
-            endCursor
-          }
-        }
-      }
-    `,
-    variables: {
-      first: 100,
-      status: ['BOOKED', 'CONFIRMED'],
-      createdFrom: '2024-01-01T00:00:00Z',
-    },
-    pagination: {
-      maxRecords: 1000,
-      onProgress: (page, total) => {
-        console.log(`Filtered results - Page ${page}: ${total} total`);
-      },
-    },
-  });
-
-  return result.data.orders.edges.map((e: any) => e.node);
-}
-
-/**
- * Pattern 5: Backward Pagination (Last/Before)
- *
- * Paginate backwards from the end of a result set using 'last' and 'before'.
- */
-export async function backwardPagination(client: FluentClient) {
-  const allItems = [];
-  let hasPreviousPage = true;
-  let cursor: string | undefined = undefined;
-
-  const query = `
-    query GetOrdersBackward($last: Int!, $before: String) {
-      orders(last: $last, before: $before) {
-        edges {
-          cursor
-          node {
-            id
-            ref
-            status
-          }
-        }
-        pageInfo {
-          hasPreviousPage
-          # Note: Fluent doesn't return endCursor/startCursor - cursors are in edges[].cursor
-        }
-      }
-    }
-  `;
-
-  try {
-    while (hasPreviousPage) {
-      const result = await client.graphql({
-        query,
-        variables: { last: 100, before: cursor },
-        pagination: { enabled: false },
-      });
-
-      const items = result.data.orders.edges.map((e: any) => e.node);
-      // Prepend items since we're going backwards
-      allItems.unshift(...items.reverse());
-
-      hasPreviousPage = result.data.orders.pageInfo.hasPreviousPage;
-      const edges = result.data.orders.edges || [];
-      cursor = edges.length > 0 ? edges[0].cursor : undefined;
-    }
-
-    return allItems;
-  } catch (error) {
-    console.error('Backward pagination failed:', error);
-    throw error;
-  }
-}
-
-/**
- * Usage Example: Process Large Dataset in Batches
- */
-async function main() {
-  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!,
-      username: process.env.FLUENT_USERNAME!,
-      password: process.env.FLUENT_PASSWORD!,
-    },
-  });
-
-  console.log('Example 1: Auto-pagination with limits');
-  await autoPaginationWithLimits();
-
-  console.log('\nExample 2: Manual cursor pagination');
-  await manualCursorPagination(client);
-
-  console.log('\nExample 3: Generator-based streaming');
-  for await (const batch of streamPaginatedResults(client)) {
-    console.log(`Processing batch of ${batch.length} virtual positions`);
-    // Process batch immediately without accumulating in memory
-  }
-
-  console.log('\nExample 4: Filtered pagination');
-  const filtered = await paginateWithFilters(client);
-  console.log(`Found ${filtered.length} filtered orders`);
-
-  console.log('\nExample 5: Backward pagination');
-  const backward = await backwardPagination(client);
-  console.log(`Fetched ${backward.length} items backwards`);
-}
-
-// Run examples if executed directly
-if (require.main === module) {
-  main().catch(console.error);
-}
+/**
+ * Auto-Pagination Common Patterns
+ *
+ * Complete examples showing various pagination scenarios with the FC Connect SDK.
+ * All examples use real Fluent Commerce schema fields and cursor-based pagination.
+ *
+ * @package @fluentcommerce/fc-connect-sdk
+ * @see https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk
+ */
+
+import { createClient, FluentClient } from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * Pattern 1: Auto-Pagination with Safety Limits
+ *
+ * The SDK automatically handles pagination with configurable safety limits
+ * to prevent runaway queries.
+ */
+export async function autoPaginationWithLimits() {
+  const client = await createClient({
+    config: {
+      baseUrl: 'https://api.fluentcommerce.com',
+      clientId: process.env.FLUENT_CLIENT_ID!,
+      clientSecret: process.env.FLUENT_CLIENT_SECRET!,
+      retailerId: process.env.FLUENT_RETAILER_ID!,
+      username: process.env.FLUENT_USERNAME!,
+      password: process.env.FLUENT_PASSWORD!,
+    },
+  });
+
+  try {
+    // Auto-pagination fetches all pages and merges results
+    const result = await client.graphql({
+      query: `
+        query GetOrders($first: Int!, $after: String) {
+          orders(first: $first, after: $after) {
+            edges {
+              cursor
+              node {
+                id
+                ref
+                type
+                status
+                totalPrice
+              }
+            }
+            pageInfo {
+              hasNextPage
+              # Note: Fluent doesn't return endCursor/startCursor - cursors are in edges[].cursor
+            }
+          }
+        }
+      `,
+      variables: { first: 100 },
+      pagination: {
+        maxPages: 50, // Stop after 50 pages
+        maxRecords: 5000, // OR stop after 5000 records
+        timeoutMs: 60000, // OR stop after 60 seconds
+        onProgress: (page, totalRecords) => {
+          console.log(`Fetched page ${page}, total records: ${totalRecords}`);
+        },
+      },
+    });
+
+    // All pages are merged into a single result
+    const allOrders = result.data.orders.edges.map((e: any) => e.node);
+
+    // Check if pagination was truncated
+    const { totalPages, totalRecords, truncated } = result.extensions.autoPagination;
+    console.log(`Total: ${totalRecords} orders across ${totalPages} pages`);
+
+    if (truncated) {
+      console.warn('Pagination stopped early due to safety limits');
+    }
+
+    return allOrders;
+  } catch (error) {
+    console.error('Auto-pagination failed:', error);
+    throw error;
+  }
+}
+
+/**
+ * Pattern 2: Manual Cursor-Based Pagination
+ *
+ * For complete control over pagination logic, manually manage cursors
+ * and page fetching.
+ */
+export async function manualCursorPagination(client: FluentClient) {
+  const allProducts = [];
+  let hasNextPage = true;
+  let cursor: string | undefined = undefined;
+  let pageCount = 0;
+
+  const query = `
+    query GetProducts($first: Int!, $after: String) {
+      products(first: $first, after: $after) {
+        edges {
+          cursor
+          node {
+            id
+            ref
+            name
+            type
+            status
+          }
+        }
+        pageInfo {
+          hasNextPage
+          # Note: Fluent doesn't return endCursor/startCursor - cursors are in edges[].cursor
+        }
+      }
+    }
+  `;
+
+  try {
+    while (hasNextPage) {
+      pageCount++;
+
+      // Fetch single page with manual pagination disabled
+      const result = await client.graphql({
+        query,
+        variables: { first: 200, after: cursor },
+        pagination: { enabled: false }, // Disable auto-pagination
+      });
+
+      const products = result.data.products.edges.map((e: any) => e.node);
+      allProducts.push(...products);
+
+      // Extract pagination info using edge cursors (Fluent does not return endCursor in pageInfo)
+      hasNextPage = result.data.products.pageInfo.hasNextPage;
+      const edges = result.data.products.edges || [];
+      cursor = edges.length > 0 ? edges[edges.length - 1].cursor : undefined;
+
+      console.log(`Page ${pageCount}: ${products.length} products (total: ${allProducts.length})`);
+
+      // Optional: Add delay to avoid rate limiting
+      if (hasNextPage) {
+        await new Promise(resolve => setTimeout(resolve, 100));
+      }
+    }
+
+    return allProducts;
+  } catch (error) {
+    console.error('Manual pagination failed:', error);
+    throw error;
+  }
+}
+
+/**
+ * Pattern 3: Generator-Based Streaming Pagination
+ *
+ * Use async generators for memory-efficient processing of large datasets.
+ * Process records as they arrive instead of loading everything into memory.
+ */
+export async function* streamPaginatedResults(client: FluentClient) {
+  let hasNextPage = true;
+  let cursor: string | undefined = undefined;
+
+  const query = `
+    query GetVirtualPositions($first: Int!, $after: String) {
+      virtualPositions(first: $first, after: $after) {
+        edges {
+          cursor
+          node {
+            id
+            ref
+            type
+            status
+            productRef
+            groupRef
+            quantity
+          }
+        }
+        pageInfo {
+          hasNextPage
+          # Note: Fluent doesn't return endCursor/startCursor - cursors are in edges[].cursor
+        }
+      }
+    }
+  `;
+
+  while (hasNextPage) {
+    try {
+      const result = await client.graphql({
+        query,
+        variables: { first: 500, after: cursor },
+        pagination: { enabled: false },
+      });
+
+      const positions = result.data.virtualPositions.edges.map((e: any) => e.node);
+
+      // Yield batch of records for immediate processing
+      yield positions;
+
+      hasNextPage = result.data.virtualPositions.pageInfo.hasNextPage;
+      const edges = result.data.virtualPositions.edges || [];
+      cursor = edges.length > 0 ? edges[edges.length - 1].cursor : undefined;
+    } catch (error) {
+      console.error('Streaming pagination error:', error);
+      throw error;
+    }
+  }
+}
+
+/**
+ * Pattern 4: Filtered Pagination with GraphQL Variables
+ *
+ * Combine pagination with filtering using GraphQL variables.
+ */
+export async function paginateWithFilters(client: FluentClient) {
+  const result = await client.graphql({
+    query: `
+      query GetFilteredOrders(
+        $first: Int!
+        $after: String
+        $status: [String!]
+        $createdFrom: DateTime
+      ) {
+        orders(
+          first: $first
+          after: $after
+          status: $status
+          createdOn: { from: $createdFrom }
+        ) {
+          edges {
+            cursor
+            node {
+              id
+              ref
+              status
+              createdOn
+              totalPrice
+            }
+          }
+          pageInfo {
+            hasNextPage
+            endCursor
+          }
+        }
+      }
+    `,
+    variables: {
+      first: 100,
+      status: ['BOOKED', 'CONFIRMED'],
+      createdFrom: '2024-01-01T00:00:00Z',
+    },
+    pagination: {
+      maxRecords: 1000,
+      onProgress: (page, total) => {
+        console.log(`Filtered results - Page ${page}: ${total} total`);
+      },
+    },
+  });
+
+  return result.data.orders.edges.map((e: any) => e.node);
+}
+
+/**
+ * Pattern 5: Backward Pagination (Last/Before)
+ *
+ * Paginate backwards from the end of a result set using 'last' and 'before'.
+ */
+export async function backwardPagination(client: FluentClient) {
+  const allItems = [];
+  let hasPreviousPage = true;
+  let cursor: string | undefined = undefined;
+
+  const query = `
+    query GetOrdersBackward($last: Int!, $before: String) {
+      orders(last: $last, before: $before) {
+        edges {
+          cursor
+          node {
+            id
+            ref
+            status
+          }
+        }
+        pageInfo {
+          hasPreviousPage
+          # Note: Fluent doesn't return endCursor/startCursor - cursors are in edges[].cursor
+        }
+      }
+    }
+  `;
+
+  try {
+    while (hasPreviousPage) {
+      const result = await client.graphql({
+        query,
+        variables: { last: 100, before: cursor },
+        pagination: { enabled: false },
+      });
+
+      const items = result.data.orders.edges.map((e: any) => e.node);
+      // Prepend items since we're going backwards
+      allItems.unshift(...items.reverse());
+
+      hasPreviousPage = result.data.orders.pageInfo.hasPreviousPage;
+      const edges = result.data.orders.edges || [];
+      cursor = edges.length > 0 ? edges[0].cursor : undefined;
+    }
+
+    return allItems;
+  } catch (error) {
+    console.error('Backward pagination failed:', error);
+    throw error;
+  }
+}
+
+/**
+ * Usage Example: Process Large Dataset in Batches
+ */
+async function main() {
+  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!,
+      username: process.env.FLUENT_USERNAME!,
+      password: process.env.FLUENT_PASSWORD!,
+    },
+  });
+
+  console.log('Example 1: Auto-pagination with limits');
+  await autoPaginationWithLimits();
+
+  console.log('\nExample 2: Manual cursor pagination');
+  await manualCursorPagination(client);
+
+  console.log('\nExample 3: Generator-based streaming');
+  for await (const batch of streamPaginatedResults(client)) {
+    console.log(`Processing batch of ${batch.length} virtual positions`);
+    // Process batch immediately without accumulating in memory
+  }
+
+  console.log('\nExample 4: Filtered pagination');
+  const filtered = await paginateWithFilters(client);
+  console.log(`Found ${filtered.length} filtered orders`);
+
+  console.log('\nExample 5: Backward pagination');
+  const backward = await backwardPagination(client);
+  console.log(`Fetched ${backward.length} items backwards`);
+}
+
+// Run examples if executed directly
+if (require.main === module) {
+  main().catch(console.error);
+}