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/4] 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/4] 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); + }); }); From 16ee899f00f755d72db94fe7cd37c1af1770d51f Mon Sep 17 00:00:00 2001 From: Ilyaas Kapadia <86218345+IlyaasK@users.noreply.github.com> Date: Mon, 15 Jun 2026 12:04:52 -0400 Subject: [PATCH 3/4] style: prettier-format pagination test Co-Authored-By: Claude Fable 5 --- tests/pagination.test.ts | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/tests/pagination.test.ts b/tests/pagination.test.ts index e9ffb49e..59024be3 100644 --- a/tests/pagination.test.ts +++ b/tests/pagination.test.ts @@ -2,9 +2,16 @@ import Kernel, { KernelError } 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')) }); +const client = new Kernel({ + apiKey: 'test-api-key', + fetch: () => Promise.reject(new Error('unexpected request')), +}); -function pageWith(headers: Record, items: unknown[], offset?: number): OffsetPagination { +function pageWith( + headers: Record, + items: unknown[], + offset?: number, +): OffsetPagination { const options: FinalRequestOptions = { method: 'get', path: '/proxies', From d3184109680279c5c6565f730c874ae04c52a58d Mon Sep 17 00:00:00 2001 From: Ilyaas Kapadia <86218345+IlyaasK@users.noreply.github.com> Date: Mon, 15 Jun 2026 13:46:02 -0400 Subject: [PATCH 4/4] fix(pagination): stop on the X-Next-Offset 0 sentinel, not just has_more Review follow-up: the code treated 0 as a valid advancing offset and relied solely on has_more to stop, so the '0 sentinel' test passed only because it also set has_more=false. A real next-page offset is always offset+limit >= 1, so 0 unambiguously means 'no more' -- now treated as a stop (matching the Go SDK pager), with the test calling nextPageRequestOptions directly under has_more=true to prove 0 alone stops. Co-Authored-By: Claude Fable 5 --- src/core/pagination.ts | 10 ++++++++-- tests/pagination.test.ts | 8 +++++--- 2 files changed, 13 insertions(+), 5 deletions(-) diff --git a/src/core/pagination.ts b/src/core/pagination.ts index eb447205..91bb2032 100644 --- a/src/core/pagination.ts +++ b/src/core/pagination.ts @@ -148,8 +148,11 @@ export class OffsetPagination extends AbstractPage { } nextPageRequestOptions(): PageRequestOptions | null { - // 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. + // X-Next-Offset is the absolute start of the next page, or 0 on the last + // page (the API's stop sentinel). The old code added the current page + // length on top, skipping a full page per iteration. Only a positive + // offset advances; 0 is a value the server affirmatively sent to mean + // "no more", so we stop on it (matching the Go SDK pager). const offset = this.next_offset; if (offset == null) { if (this.has_more) { @@ -159,6 +162,9 @@ export class OffsetPagination extends AbstractPage { } return null; } + if (offset === 0) { + return null; + } return { ...this.options, diff --git a/tests/pagination.test.ts b/tests/pagination.test.ts index 59024be3..3e5fadee 100644 --- a/tests/pagination.test.ts +++ b/tests/pagination.test.ts @@ -34,9 +34,11 @@ describe('OffsetPagination', () => { expect(page.hasNextPage()).toBe(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 on the X-Next-Offset 0 sentinel even when X-Has-More is true', () => { + // Call nextPageRequestOptions directly with has_more=true so the has_more + // gate in hasNextPage() cannot mask it: the 0 offset alone must stop. + const page = pageWith({ 'x-next-offset': '0', 'x-has-more': 'true' }, new Array(50).fill({}), 100); + expect(page.nextPageRequestOptions()).toBeNull(); }); test('stops when X-Has-More is false even with a positive X-Next-Offset', () => {