@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to the Fluent Commerce Connect SDK will be documented in thi
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.55] - 2026-04-02
+
+### Fixed - Pagination Cursor Detection & Record Counting
+- **Root cause fix:** `detectPaginationVariables()` now uses body-based fallback detection for non-standard variable names (e.g., `$cursor` used as `after:`, `$pageSize` used as `first:`). Previously, only convention-named variables like `$after`/`$first` were detected, causing pagination to silently re-fetch page 1 repeatedly.
+- **`totalRecords` accuracy:** Both `FluentClient` and `FluentVersoriClient` now derive `totalRecords` from actual merged/deduped edges instead of raw page-count accumulation. Fixes inflated counts (e.g., reporting 1000 when actual was 529).
+- **`maxRecords` limit accuracy:** The pagination loop now checks unique record count (post-dedup) against `maxRecords`, not the raw accumulator. Prevents premature or delayed truncation.
+- Added 5 new unit tests for body-based variable detection patterns.
+- Fixed `fluent-versori-client-parity` maxRecords test to use unique edges per page.
+
+### Changed
+- Upgraded `@versori/run` from `^0.4.18` to `^0.5.10` (adds OpenTelemetry observability, connection services; no breaking changes to SDK imports).
+
 ## [0.1.54] - 2026-02-20
 
 ### Added - Fluent CLI Profile Integration

package/README.md

@@ -7,6 +7,17 @@
 [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.0.0-green)](https://nodejs.org/)
 [![Deno Compatible](https://img.shields.io/badge/Deno-Compatible-black)](https://deno.land/)
 
+> [!CAUTION]
+> **🧪 EXPERIMENTAL — LABS PROJECT**
+>
+> This package is **NOT production-ready**. It is an internal labs experiment under active development.
+>
+> - **No stability guarantees** — APIs, services, CLI options, and config may change or break between any release
+> - **No support** — this is not an officially supported Fluent Commerce product
+> - **No warranty** — provided as-is for experimentation and internal evaluation only
+> - **Do NOT use in production** without thorough review and explicit sign-off from your team
+> - **Pin to an exact version** (`@0.1.55`) if you depend on current behavior
+
 TypeScript SDK for building **Fluent Commerce** integrations across Node.js, Deno, and the Versori platform.
 
 - **Package:** [`@fluentcommerce/fc-connect-sdk`](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)

package/dist/cjs/clients/fluent-client.js

@@ -250,9 +250,12 @@ class FluentClient {
             else {
                 emptyPageCount = 0;
             }
+            const mergedConnection = (0, pagination_helpers_1.extractConnection)(allData, config.connectionPath);
+            const uniqueRecords = mergedConnection ? mergedConnection.edges.length : totalRecords;
             this.log('debug', `[FluentClient:pagination] Page ${pageNumber} fetched`, {
                 edgesInPage: connection.edges.length,
-                totalRecords,
+                uniqueRecords,
+                rawRecordsFetched: totalRecords,
                 hasMore: (0, pagination_helpers_1.hasMorePages)(connection.pageInfo, config.direction),
                 emptyPageCount,
             });
@@ -262,13 +265,13 @@ class FluentClient {
                 config.onWarning(`Pagination stopped: maxPages (${config.maxPages}) reached`);
                 break;
             }
-            if (totalRecords >= config.maxRecords) {
+            if (uniqueRecords >= config.maxRecords) {
                 truncated = true;
                 truncationReason = 'maxRecords';
                 config.onWarning(`Pagination stopped: maxRecords (${config.maxRecords}) reached`);
                 break;
             }
-            config.onProgress(pageNumber, totalRecords);
+            config.onProgress(pageNumber, uniqueRecords);
             if (!(0, pagination_helpers_1.hasMorePages)(connection.pageInfo, config.direction)) {
                 this.log('debug', '[FluentClient:pagination] No more pages, stopping');
                 break;
@@ -289,9 +292,13 @@ class FluentClient {
             }
         }
         const hasPartialErrors = accumulatedErrors.length > 0;
-        this.log('info', `[FluentClient:pagination] Pagination complete (${pageNumber} pages, ${totalRecords} records${truncated ? `, truncated: ${truncationReason}` : ''}${hasPartialErrors ? `, ${accumulatedErrors.length} errors` : ''})`, {
+        const finalConnection = (0, pagination_helpers_1.extractConnection)(allData, config.connectionPath);
+        const actualTotalRecords = finalConnection ? finalConnection.edges.length : totalRecords;
+        this.log('info', `[FluentClient:pagination] Pagination complete (${pageNumber} pages, ${actualTotalRecords} records${totalRecords !== actualTotalRecords ? ` (${totalRecords} raw, ${totalRecords - actualTotalRecords} duplicates removed)` : ''}${truncated ? `, truncated: ${truncationReason}` : ''}${hasPartialErrors ? `, ${accumulatedErrors.length} errors` : ''})`, {
             totalPages: pageNumber,
-            totalRecords,
+            totalRecords: actualTotalRecords,
+            rawRecordsFetched: totalRecords,
+            duplicatesRemoved: totalRecords - actualTotalRecords,
             truncated,
             truncationReason,
             duration: Date.now() - startTime,
@@ -304,7 +311,7 @@ class FluentClient {
                 ...(lastExtensions || {}),
                 autoPagination: {
                     totalPages: pageNumber,
-                    totalRecords,
+                    totalRecords: actualTotalRecords,
                     truncated,
                     truncationReason,
                     direction: config.direction,

package/dist/cjs/utils/pagination-helpers.js

@@ -32,8 +32,44 @@ function detectPaginationVariables(query) {
         variableNames.last = lastMatch[1];
     if (beforeMatch)
         variableNames.before = beforeMatch[1];
-    const hasForward = !!firstMatch || !!afterMatch;
-    const hasBackward = !!lastMatch || !!beforeMatch;
+    if (!variableNames.after) {
+        const afterUsage = normalized.match(/after\s*:\s*\$(\w+)/);
+        if (afterUsage) {
+            const varName = afterUsage[1];
+            if (varDeclarations.includes(`$${varName}`)) {
+                variableNames.after = varName;
+            }
+        }
+    }
+    if (!variableNames.before) {
+        const beforeUsage = normalized.match(/before\s*:\s*\$(\w+)/);
+        if (beforeUsage) {
+            const varName = beforeUsage[1];
+            if (varDeclarations.includes(`$${varName}`)) {
+                variableNames.before = varName;
+            }
+        }
+    }
+    if (!variableNames.first) {
+        const firstUsage = normalized.match(/first\s*:\s*\$(\w+)/);
+        if (firstUsage) {
+            const varName = firstUsage[1];
+            if (varDeclarations.includes(`$${varName}`)) {
+                variableNames.first = varName;
+            }
+        }
+    }
+    if (!variableNames.last) {
+        const lastUsage = normalized.match(/last\s*:\s*\$(\w+)/);
+        if (lastUsage) {
+            const varName = lastUsage[1];
+            if (varDeclarations.includes(`$${varName}`)) {
+                variableNames.last = varName;
+            }
+        }
+    }
+    const hasForward = !!variableNames.first || !!variableNames.after;
+    const hasBackward = !!variableNames.last || !!variableNames.before;
     let direction = 'none';
     if (hasForward && !hasBackward) {
         direction = 'forward';

package/dist/cjs/versori/fluent-versori-client.js

@@ -308,19 +308,21 @@ class FluentVersoriClient {
             else {
                 emptyPageCount = 0;
             }
+            const mergedConnection = (0, pagination_helpers_1.extractConnection)(allData, config.connectionPath);
+            const uniqueRecords = mergedConnection ? mergedConnection.edges.length : totalRecords;
             if (pageNumber >= config.maxPages) {
                 truncated = true;
                 truncationReason = 'maxPages';
                 config.onWarning(`Pagination stopped: maxPages (${config.maxPages}) reached`);
                 break;
             }
-            if (totalRecords >= config.maxRecords) {
+            if (uniqueRecords >= config.maxRecords) {
                 truncated = true;
                 truncationReason = 'maxRecords';
                 config.onWarning(`Pagination stopped: maxRecords (${config.maxRecords}) reached`);
                 break;
             }
-            config.onProgress(pageNumber, totalRecords);
+            config.onProgress(pageNumber, uniqueRecords);
             if (!(0, pagination_helpers_1.hasMorePages)(connection.pageInfo, config.direction)) {
                 this.ctx.log?.debug?.('[fc-connect-sdk:pagination] No more pages, stopping');
                 break;
@@ -341,9 +343,13 @@ class FluentVersoriClient {
             }
         }
         const hasPartialErrors = accumulatedErrors.length > 0;
-        this.ctx.log?.info?.(`[fc-connect-sdk:pagination] Pagination complete (${pageNumber} pages, ${totalRecords} records${truncated ? `, truncated: ${truncationReason}` : ''}${hasPartialErrors ? `, ${accumulatedErrors.length} errors` : ''})`, {
+        const finalConnection = (0, pagination_helpers_1.extractConnection)(allData, config.connectionPath);
+        const actualTotalRecords = finalConnection ? finalConnection.edges.length : totalRecords;
+        this.ctx.log?.info?.(`[fc-connect-sdk:pagination] Pagination complete (${pageNumber} pages, ${actualTotalRecords} records${totalRecords !== actualTotalRecords ? ` (${totalRecords} raw, ${totalRecords - actualTotalRecords} duplicates removed)` : ''}${truncated ? `, truncated: ${truncationReason}` : ''}${hasPartialErrors ? `, ${accumulatedErrors.length} errors` : ''})`, {
             totalPages: pageNumber,
-            totalRecords,
+            totalRecords: actualTotalRecords,
+            rawRecordsFetched: totalRecords,
+            duplicatesRemoved: totalRecords - actualTotalRecords,
             truncated,
             truncationReason,
             duration: Date.now() - startTime,
@@ -356,7 +362,7 @@ class FluentVersoriClient {
                 ...(lastExtensions || {}),
                 autoPagination: {
                     totalPages: pageNumber,
-                    totalRecords,
+                    totalRecords: actualTotalRecords,
                     truncated,
                     truncationReason,
                     direction: config.direction,

package/dist/esm/clients/fluent-client.js

@@ -247,9 +247,12 @@ export class FluentClient {
             else {
                 emptyPageCount = 0;
             }
+            const mergedConnection = extractConnection(allData, config.connectionPath);
+            const uniqueRecords = mergedConnection ? mergedConnection.edges.length : totalRecords;
             this.log('debug', `[FluentClient:pagination] Page ${pageNumber} fetched`, {
                 edgesInPage: connection.edges.length,
-                totalRecords,
+                uniqueRecords,
+                rawRecordsFetched: totalRecords,
                 hasMore: hasMorePages(connection.pageInfo, config.direction),
                 emptyPageCount,
             });
@@ -259,13 +262,13 @@ export class FluentClient {
                 config.onWarning(`Pagination stopped: maxPages (${config.maxPages}) reached`);
                 break;
             }
-            if (totalRecords >= config.maxRecords) {
+            if (uniqueRecords >= config.maxRecords) {
                 truncated = true;
                 truncationReason = 'maxRecords';
                 config.onWarning(`Pagination stopped: maxRecords (${config.maxRecords}) reached`);
                 break;
             }
-            config.onProgress(pageNumber, totalRecords);
+            config.onProgress(pageNumber, uniqueRecords);
             if (!hasMorePages(connection.pageInfo, config.direction)) {
                 this.log('debug', '[FluentClient:pagination] No more pages, stopping');
                 break;
@@ -286,9 +289,13 @@ export class FluentClient {
             }
         }
         const hasPartialErrors = accumulatedErrors.length > 0;
-        this.log('info', `[FluentClient:pagination] Pagination complete (${pageNumber} pages, ${totalRecords} records${truncated ? `, truncated: ${truncationReason}` : ''}${hasPartialErrors ? `, ${accumulatedErrors.length} errors` : ''})`, {
+        const finalConnection = extractConnection(allData, config.connectionPath);
+        const actualTotalRecords = finalConnection ? finalConnection.edges.length : totalRecords;
+        this.log('info', `[FluentClient:pagination] Pagination complete (${pageNumber} pages, ${actualTotalRecords} records${totalRecords !== actualTotalRecords ? ` (${totalRecords} raw, ${totalRecords - actualTotalRecords} duplicates removed)` : ''}${truncated ? `, truncated: ${truncationReason}` : ''}${hasPartialErrors ? `, ${accumulatedErrors.length} errors` : ''})`, {
             totalPages: pageNumber,
-            totalRecords,
+            totalRecords: actualTotalRecords,
+            rawRecordsFetched: totalRecords,
+            duplicatesRemoved: totalRecords - actualTotalRecords,
             truncated,
             truncationReason,
             duration: Date.now() - startTime,
@@ -301,7 +308,7 @@ export class FluentClient {
                 ...(lastExtensions || {}),
                 autoPagination: {
                     totalPages: pageNumber,
-                    totalRecords,
+                    totalRecords: actualTotalRecords,
                     truncated,
                     truncationReason,
                     direction: config.direction,

package/dist/esm/utils/pagination-helpers.js

@@ -25,8 +25,44 @@ export function detectPaginationVariables(query) {
         variableNames.last = lastMatch[1];
     if (beforeMatch)
         variableNames.before = beforeMatch[1];
-    const hasForward = !!firstMatch || !!afterMatch;
-    const hasBackward = !!lastMatch || !!beforeMatch;
+    if (!variableNames.after) {
+        const afterUsage = normalized.match(/after\s*:\s*\$(\w+)/);
+        if (afterUsage) {
+            const varName = afterUsage[1];
+            if (varDeclarations.includes(`$${varName}`)) {
+                variableNames.after = varName;
+            }
+        }
+    }
+    if (!variableNames.before) {
+        const beforeUsage = normalized.match(/before\s*:\s*\$(\w+)/);
+        if (beforeUsage) {
+            const varName = beforeUsage[1];
+            if (varDeclarations.includes(`$${varName}`)) {
+                variableNames.before = varName;
+            }
+        }
+    }
+    if (!variableNames.first) {
+        const firstUsage = normalized.match(/first\s*:\s*\$(\w+)/);
+        if (firstUsage) {
+            const varName = firstUsage[1];
+            if (varDeclarations.includes(`$${varName}`)) {
+                variableNames.first = varName;
+            }
+        }
+    }
+    if (!variableNames.last) {
+        const lastUsage = normalized.match(/last\s*:\s*\$(\w+)/);
+        if (lastUsage) {
+            const varName = lastUsage[1];
+            if (varDeclarations.includes(`$${varName}`)) {
+                variableNames.last = varName;
+            }
+        }
+    }
+    const hasForward = !!variableNames.first || !!variableNames.after;
+    const hasBackward = !!variableNames.last || !!variableNames.before;
     let direction = 'none';
     if (hasForward && !hasBackward) {
         direction = 'forward';

package/dist/esm/versori/fluent-versori-client.js

@@ -305,19 +305,21 @@ export class FluentVersoriClient {
             else {
                 emptyPageCount = 0;
             }
+            const mergedConnection = extractConnection(allData, config.connectionPath);
+            const uniqueRecords = mergedConnection ? mergedConnection.edges.length : totalRecords;
             if (pageNumber >= config.maxPages) {
                 truncated = true;
                 truncationReason = 'maxPages';
                 config.onWarning(`Pagination stopped: maxPages (${config.maxPages}) reached`);
                 break;
             }
-            if (totalRecords >= config.maxRecords) {
+            if (uniqueRecords >= config.maxRecords) {
                 truncated = true;
                 truncationReason = 'maxRecords';
                 config.onWarning(`Pagination stopped: maxRecords (${config.maxRecords}) reached`);
                 break;
             }
-            config.onProgress(pageNumber, totalRecords);
+            config.onProgress(pageNumber, uniqueRecords);
             if (!hasMorePages(connection.pageInfo, config.direction)) {
                 this.ctx.log?.debug?.('[fc-connect-sdk:pagination] No more pages, stopping');
                 break;
@@ -338,9 +340,13 @@ export class FluentVersoriClient {
             }
         }
         const hasPartialErrors = accumulatedErrors.length > 0;
-        this.ctx.log?.info?.(`[fc-connect-sdk:pagination] Pagination complete (${pageNumber} pages, ${totalRecords} records${truncated ? `, truncated: ${truncationReason}` : ''}${hasPartialErrors ? `, ${accumulatedErrors.length} errors` : ''})`, {
+        const finalConnection = extractConnection(allData, config.connectionPath);
+        const actualTotalRecords = finalConnection ? finalConnection.edges.length : totalRecords;
+        this.ctx.log?.info?.(`[fc-connect-sdk:pagination] Pagination complete (${pageNumber} pages, ${actualTotalRecords} records${totalRecords !== actualTotalRecords ? ` (${totalRecords} raw, ${totalRecords - actualTotalRecords} duplicates removed)` : ''}${truncated ? `, truncated: ${truncationReason}` : ''}${hasPartialErrors ? `, ${accumulatedErrors.length} errors` : ''})`, {
             totalPages: pageNumber,
-            totalRecords,
+            totalRecords: actualTotalRecords,
+            rawRecordsFetched: totalRecords,
+            duplicatesRemoved: totalRecords - actualTotalRecords,
             truncated,
             truncationReason,
             duration: Date.now() - startTime,
@@ -353,7 +359,7 @@ export class FluentVersoriClient {
                 ...(lastExtensions || {}),
                 autoPagination: {
                     totalPages: pageNumber,
-                    totalRecords,
+                    totalRecords: actualTotalRecords,
                     truncated,
                     truncationReason,
                     direction: config.direction,