From f7bf2d92d25c85be6b0b33d6ce738f75917dceff Mon Sep 17 00:00:00 2001 From: Ilyaas Kapadia <86218345+IlyaasK@users.noreply.github.com> Date: Fri, 12 Jun 2026 15:30:38 -0400 Subject: [PATCH 1/2] fix(pagination): stop skipping a page per auto-pagination iteration OffsetPagination.nextPageRequestOptions() requested the next page at next_offset + items.length. The X-Next-Offset header already holds the offset where the next page starts (the API computes offset + limit), so adding the current page length skipped a full page per iteration: with 250 items at limit 100, iteration returned items 0-99 and 200-249 and silently dropped 100-199. X-Has-More still terminated the loop, hiding the data loss. Use the header value directly, and stop paginating when it is absent. Hand-maintained fix: with Stainless's hosted generator winding down, the template-level fix is not coming; this commit and its test are the canonical behavior. Co-Authored-By: Claude Fable 5 --- src/core/pagination.ts | 11 +++++++---- tests/pagination.test.ts | 39 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 46 insertions(+), 4 deletions(-) create mode 100644 tests/pagination.test.ts diff --git a/src/core/pagination.ts b/src/core/pagination.ts index 9a507f0e..33578f03 100644 --- a/src/core/pagination.ts +++ b/src/core/pagination.ts @@ -148,15 +148,18 @@ export class OffsetPagination extends AbstractPage { } nextPageRequestOptions(): PageRequestOptions | null { - const offset = this.next_offset ?? 0; - const length = this.getPaginatedItems().length; - const currentCount = offset + length; + // X-Next-Offset already holds the offset where the next page starts; + // adding the current page length on top skips a full page per iteration. + const offset = this.next_offset; + if (offset == null) { + return null; + } return { ...this.options, query: { ...maybeObj(this.options.query), - offset: currentCount, + offset, }, }; } diff --git a/tests/pagination.test.ts b/tests/pagination.test.ts new file mode 100644 index 00000000..50bb8247 --- /dev/null +++ b/tests/pagination.test.ts @@ -0,0 +1,39 @@ +import Kernel from '@onkernel/sdk'; +import { OffsetPagination } from '@onkernel/sdk/core/pagination'; +import type { FinalRequestOptions } from '@onkernel/sdk/internal/request-options'; + +const client = new Kernel({ apiKey: 'test-api-key', fetch: () => Promise.reject(new Error('unexpected request')) }); + +function pageWith(headers: Record, items: unknown[], offset?: number): OffsetPagination { + const options: FinalRequestOptions = { + method: 'get', + path: '/proxies', + query: offset === undefined ? {} : { offset }, + }; + return new OffsetPagination(client, new Response('[]', { headers }), items, options); +} + +describe('OffsetPagination', () => { + test('requests the next page at exactly X-Next-Offset', () => { + // X-Next-Offset already holds the next page's start. Adding the current + // page length on top (the old behavior) skipped a full page per iteration. + const page = pageWith({ 'x-next-offset': '100', 'x-has-more': 'true' }, new Array(100).fill({}), 0); + expect(page.nextPageRequestOptions()?.query).toEqual({ offset: 100 }); + }); + + test('stops when X-Next-Offset is absent', () => { + const page = pageWith({ 'x-has-more': 'true' }, new Array(100).fill({})); + expect(page.nextPageRequestOptions()).toBeNull(); + expect(page.hasNextPage()).toBe(false); + }); + + test('stops when X-Has-More is false', () => { + const page = pageWith({ 'x-next-offset': '200', 'x-has-more': 'false' }, new Array(50).fill({}), 100); + expect(page.hasNextPage()).toBe(false); + }); + + test('stops on an empty page', () => { + const page = pageWith({ 'x-next-offset': '300', 'x-has-more': 'true' }, [], 200); + expect(page.hasNextPage()).toBe(false); + }); +}); From 994749dd56176dfae27a60d9b8df6bf10c335eb8 Mon Sep 17 00:00:00 2001 From: Ilyaas Kapadia <86218345+IlyaasK@users.noreply.github.com> Date: Fri, 12 Jun 2026 16:07:36 -0400 Subject: [PATCH 2/2] fix(pagination): fail loudly when X-Has-More contradicts a missing X-Next-Offset Review follow-up: stopping silently on an absent header is correct for real last pages, but if a server ever reports more results without saying where they start, truncating silently reproduces the data-loss failure mode this branch exists to fix. Throw instead. Also pins the 0 next-offset sentinel the API emits on last pages. Co-Authored-By: Claude Fable 5 --- src/core/pagination.ts | 5 +++++ tests/pagination.test.ts | 18 ++++++++++++++---- 2 files changed, 19 insertions(+), 4 deletions(-) diff --git a/src/core/pagination.ts b/src/core/pagination.ts index 33578f03..eb447205 100644 --- a/src/core/pagination.ts +++ b/src/core/pagination.ts @@ -152,6 +152,11 @@ export class OffsetPagination extends AbstractPage { // adding the current page length on top skips a full page per iteration. const offset = this.next_offset; if (offset == null) { + if (this.has_more) { + throw new KernelError( + 'Server reported X-Has-More: true without an X-Next-Offset header; refusing to silently truncate pagination', + ); + } return null; } diff --git a/tests/pagination.test.ts b/tests/pagination.test.ts index 50bb8247..e9ffb49e 100644 --- a/tests/pagination.test.ts +++ b/tests/pagination.test.ts @@ -1,4 +1,4 @@ -import Kernel from '@onkernel/sdk'; +import Kernel, { KernelError } from '@onkernel/sdk'; import { OffsetPagination } from '@onkernel/sdk/core/pagination'; import type { FinalRequestOptions } from '@onkernel/sdk/internal/request-options'; @@ -21,13 +21,18 @@ describe('OffsetPagination', () => { expect(page.nextPageRequestOptions()?.query).toEqual({ offset: 100 }); }); - test('stops when X-Next-Offset is absent', () => { - const page = pageWith({ 'x-has-more': 'true' }, new Array(100).fill({})); + test('stops cleanly when the last page omits X-Next-Offset', () => { + const page = pageWith({ 'x-has-more': 'false' }, new Array(50).fill({}), 100); expect(page.nextPageRequestOptions()).toBeNull(); expect(page.hasNextPage()).toBe(false); }); - test('stops when X-Has-More is false', () => { + test('stops when X-Next-Offset is 0, the last-page sentinel', () => { + const page = pageWith({ 'x-next-offset': '0', 'x-has-more': 'false' }, new Array(50).fill({}), 100); + expect(page.hasNextPage()).toBe(false); + }); + + test('stops when X-Has-More is false even with a positive X-Next-Offset', () => { const page = pageWith({ 'x-next-offset': '200', 'x-has-more': 'false' }, new Array(50).fill({}), 100); expect(page.hasNextPage()).toBe(false); }); @@ -36,4 +41,9 @@ describe('OffsetPagination', () => { const page = pageWith({ 'x-next-offset': '300', 'x-has-more': 'true' }, [], 200); expect(page.hasNextPage()).toBe(false); }); + + test('refuses to silently truncate when X-Has-More is true but X-Next-Offset is missing', () => { + const page = pageWith({ 'x-has-more': 'true' }, new Array(100).fill({})); + expect(() => page.hasNextPage()).toThrow(KernelError); + }); });