Skip to content

armgit / E2B

Public Imported from GitHub
0

Open-source, secure environment with real-world tools for enterprise-grade agents.

Introduce generic paginator base class for JS and Python SDKs (#1491)

Lukáš Huvarbb45f185f113
diff --git a/.changeset/generic-paginator.md b/.changeset/generic-paginator.md
new file mode 100644
index 000000000..d84e3ddd2
--- /dev/null
+++ b/.changeset/generic-paginator.md
@@ -0,0 +1,6 @@
+---
+"@e2b/python-sdk": patch
+"e2b": patch
+---
+
+Introduce a generic, reusable paginator base class and migrate the sandbox and snapshot list paginators onto it. The base owns the shared cursor-based pagination state (`hasNext`/`has_next`, `nextToken`/`next_token`, and reading the `x-next-token` header) while each concrete paginator implements `nextItems`/`next_items` to fetch its own page, so future list endpoints can add pagination by subclassing it without reimplementing the bookkeeping. No public API changes.
diff --git a/packages/js-sdk/src/paginator.ts b/packages/js-sdk/src/paginator.ts
new file mode 100644
index 000000000..051655a76
--- /dev/null
+++ b/packages/js-sdk/src/paginator.ts
@@ -0,0 +1,77 @@
+import type { ConnectionOpts } from './connectionConfig'
+
+/**
+ * Generic, reusable paginator for cursor-based list endpoints.
+ *
+ * The base owns the shared pagination state — `hasNext`, `nextToken`, and the
+ * reading of the `x-next-token` response header (via {@link Paginator.updatePagination}).
+ * Each concrete paginator implements {@link Paginator.nextItems} to do the
+ * actual fetching for its endpoint, so any model can expose pagination by
+ * subclassing this without reimplementing the bookkeeping.
+ *
+ * The optional `O` type parameter is the per-call options type accepted by
+ * `nextItems` (e.g. connection options for a given API).
+ *
+ * @example
+ * ```ts
+ * const paginator = Sandbox.list()
+ * while (paginator.hasNext) {
+ * const items = await paginator.nextItems()
+ * console.log(items)
+ * }
+ * ```
+ */
+export abstract class Paginator<T, O extends ConnectionOpts = ConnectionOpts> {
+ protected readonly opts?: O
+ protected readonly limit?: number
+
+ private _hasNext: boolean
+ private _nextToken?: string
+
+ constructor(opts?: O, limit?: number, nextToken?: string) {
+ this.opts = opts
+ this.limit = limit
+
+ this._hasNext = true
+ this._nextToken = nextToken
+ }
+
+ /**
+ * Returns true if there are more items to fetch.
+ */
+ get hasNext(): boolean {
+ return this._hasNext
+ }
+
+ /**
+ * Returns the next token to use for pagination.
+ */
+ get nextToken(): string | undefined {
+ return this._nextToken
+ }
+
+ /**
+ * Update the pagination state from a response, reading the `x-next-token`
+ * header. Concrete paginators call this from {@link Paginator.nextItems}
+ * after fetching a page.
+ */
+ protected updatePagination(response: Response) {
+ this._nextToken = response.headers.get('x-next-token') || undefined
+ this._hasNext = !!this._nextToken
+ }
+
+ /**
+ * Get the next page of items.
+ *
+ * @param opts per-call connection options. When provided, this call uses
+ * these options (e.g. `apiKey`, `domain`, `headers`, `requestTimeoutMs`,
+ * `signal`) instead of the ones the paginator was constructed with.
+ * Aborting a page via `signal` does not affect subsequent {@link Paginator.nextItems}
+ * calls — pass a fresh signal each call you want to be cancellable.
+ *
+ * @throws Error if there are no more items to fetch. Call this method only if `hasNext` is `true`.
+ *
+ * @returns List of items
+ */
+ abstract nextItems(opts?: O): Promise<T[]>
+}
diff --git a/packages/js-sdk/src/sandbox/sandboxApi.ts b/packages/js-sdk/src/sandbox/sandboxApi.ts
index 6211e10ea..4cedebcfa 100644
--- a/packages/js-sdk/src/sandbox/sandboxApi.ts
+++ b/packages/js-sdk/src/sandbox/sandboxApi.ts
@@ -11,6 +11,7 @@ import {
SandboxNotFoundError,
TemplateError,
} from '../errors'
+import { Paginator } from '../paginator'
import { timeoutToSeconds } from '../utils'
import type { Volume } from '../volume'
import type { McpServer as BaseMcpServer } from './mcp'
@@ -1242,56 +1243,6 @@ export class SandboxApi {
}
}
-abstract class BasePaginator<T> {
- protected readonly opts?: SandboxApiOpts
- protected readonly limit?: number
-
- private _hasNext: boolean
- private _nextToken?: string
-
- constructor(opts?: SandboxApiOpts, limit?: number, nextToken?: string) {
- this.opts = opts
- this.limit = limit
-
- this._hasNext = true
- this._nextToken = nextToken
- }
-
- /**
- * Returns true if there are more items to fetch.
- */
- get hasNext(): boolean {
- return this._hasNext
- }
-
- /**
- * Returns the next token to use for pagination.
- */
- get nextToken(): string | undefined {
- return this._nextToken
- }
-
- protected updatePagination(response: Response) {
- this._nextToken = response.headers.get('x-next-token') || undefined
- this._hasNext = !!this._nextToken
- }
-
- /**
- * Get the next page of items.
- *
- * @param opts per-call connection options. When provided, this call uses
- * these options (e.g. `apiKey`, `domain`, `headers`, `requestTimeoutMs`,
- * `signal`) instead of the ones the paginator was constructed with.
- * Aborting a page via `signal` does not affect subsequent {@link BasePaginator.nextItems}
- * calls — pass a fresh signal each call you want to be cancellable.
- *
- * @throws Error if there are no more items to fetch. Call this method only if `hasNext` is `true`.
- *
- * @returns List of items
- */
- abstract nextItems(opts?: SandboxApiOpts): Promise<T[]>
-}
-
/**
* Paginator for listing sandboxes.
*
@@ -1304,7 +1255,7 @@ abstract class BasePaginator<T> {
* }
* ```
*/
-export class SandboxPaginator extends BasePaginator<SandboxInfo> {
+export class SandboxPaginator extends Paginator<SandboxInfo, SandboxApiOpts> {
private query: SandboxListOpts['query']
constructor(opts?: SandboxListOpts) {
@@ -1382,7 +1333,7 @@ export class SandboxPaginator extends BasePaginator<SandboxInfo> {
* }
* ```
*/
-export class SnapshotPaginator extends BasePaginator<SnapshotInfo> {
+export class SnapshotPaginator extends Paginator<SnapshotInfo, SandboxApiOpts> {
private readonly sandboxId?: string
constructor(opts?: SnapshotListOpts) {
diff --git a/packages/js-sdk/tests/paginator.test.ts b/packages/js-sdk/tests/paginator.test.ts
new file mode 100644
index 000000000..67169b6ab
--- /dev/null
+++ b/packages/js-sdk/tests/paginator.test.ts
@@ -0,0 +1,62 @@
+import { assert, expect, test } from 'vitest'
+
+import { Paginator } from '../src/paginator'
+
+// Build a fake HTTP Response carrying only the `x-next-token` header.
+function fakeResponse(nextToken?: string): Response {
+ const headers = new Headers()
+ if (nextToken !== undefined) {
+ headers.set('x-next-token', nextToken)
+ }
+ return new Response(null, { headers })
+}
+
+// Minimal concrete paginator that returns canned pages and drives the shared
+// base state machine via `updatePagination`.
+class FakePaginator extends Paginator<string> {
+ private call = 0
+
+ constructor(
+ private readonly pages: Array<{ items: string[]; nextToken?: string }>
+ ) {
+ super()
+ }
+
+ async nextItems(): Promise<string[]> {
+ if (!this.hasNext) {
+ throw new Error('No more items to fetch')
+ }
+
+ const page = this.pages[this.call++]
+ this.updatePagination(fakeResponse(page.nextToken))
+ return page.items
+ }
+}
+
+test('paginator exposes pagination state and advances across pages', async () => {
+ const paginator = new FakePaginator([
+ { items: ['a', 'b'], nextToken: 'tok-2' },
+ { items: ['c'], nextToken: undefined },
+ ])
+
+ assert.isTrue(paginator.hasNext)
+ assert.isUndefined(paginator.nextToken)
+
+ const first = await paginator.nextItems()
+ assert.deepEqual(first, ['a', 'b'])
+ assert.isTrue(paginator.hasNext)
+ assert.equal(paginator.nextToken, 'tok-2')
+
+ const second = await paginator.nextItems()
+ assert.deepEqual(second, ['c'])
+ assert.isFalse(paginator.hasNext)
+ assert.isUndefined(paginator.nextToken)
+})
+
+test('paginator throws once exhausted', async () => {
+ const paginator = new FakePaginator([{ items: [], nextToken: undefined }])
+ await paginator.nextItems()
+
+ assert.isFalse(paginator.hasNext)
+ await expect(paginator.nextItems()).rejects.toThrow('No more items to fetch')
+})
diff --git a/packages/python-sdk/e2b/paginator.py b/packages/python-sdk/e2b/paginator.py
new file mode 100644
index 000000000..a1a2e1130
--- /dev/null
+++ b/packages/python-sdk/e2b/paginator.py
@@ -0,0 +1,52 @@
+from typing import Generic, Mapping, Optional, TypeVar
+
+from typing_extensions import Unpack
+
+from e2b.connection_config import ApiParams
+
+T = TypeVar("T")
+OptsT = TypeVar("OptsT", bound=ApiParams)
+
+
+class PaginatorBase(Generic[T, OptsT]):
+ """
+ Shared pagination state for cursor-based list endpoints.
+
+ Owns the `has_next` / `next_token` state and the reading of the
+ `x-next-token` response header (via `_update_pagination`). Each concrete
+ paginator implements `next_items` to do the actual fetching for its
+ endpoint, so any model can expose pagination by subclassing this without
+ reimplementing the bookkeeping.
+
+ `T` is the item type returned by `next_items`; `OptsT` is the connection
+ options type accepted by the paginator (an `ApiParams`-compatible TypedDict).
+ """
+
+ def __init__(
+ self,
+ limit: Optional[int] = None,
+ next_token: Optional[str] = None,
+ **opts: Unpack[OptsT],
+ ):
+ self._opts: OptsT = opts
+ self.limit = limit
+ self._has_next = True
+ self._next_token = next_token
+
+ @property
+ def has_next(self) -> bool:
+ """
+ Returns True if there are more items to fetch.
+ """
+ return self._has_next
+
+ @property
+ def next_token(self) -> Optional[str]:
+ """
+ Returns the next token to use for pagination.
+ """
+ return self._next_token
+
+ def _update_pagination(self, headers: Mapping[str, str]) -> None:
+ self._next_token = headers.get("x-next-token")
+ self._has_next = bool(self._next_token)
diff --git a/packages/python-sdk/e2b/sandbox/sandbox_api.py b/packages/python-sdk/e2b/sandbox/sandbox_api.py
index 4799e0df1..d0982864f 100644
--- a/packages/python-sdk/e2b/sandbox/sandbox_api.py
+++ b/packages/python-sdk/e2b/sandbox/sandbox_api.py
@@ -48,6 +48,7 @@ from e2b.api.client.types import Unset
from e2b.connection_config import ApiParams
from e2b.sandbox.mcp import McpServer as BaseMcpServer
from e2b.sandbox.network import ALL_TRAFFIC
+from e2b.paginator import PaginatorBase
class GitHubMcpServerConfig(TypedDict):
@@ -599,34 +600,7 @@ class SnapshotInfo:
"""Full names of the snapshot template including team namespace and tag (e.g. team-slug/my-snapshot:v2)."""
-class PaginatorBase:
- def __init__(
- self,
- limit: Optional[int] = None,
- next_token: Optional[str] = None,
- **opts: Unpack[ApiParams],
- ):
- self._opts: ApiParams = opts
- self.limit = limit
- self._has_next = True
- self._next_token = next_token
-
- @property
- def has_next(self) -> bool:
- """
- Returns True if there are more items to fetch.
- """
- return self._has_next
-
- @property
- def next_token(self) -> Optional[str]:
- """
- Returns the next token to use for pagination.
- """
- return self._next_token
-
-
-class SnapshotPaginatorBase(PaginatorBase):
+class SnapshotPaginatorBase(PaginatorBase[SnapshotInfo, ApiParams]):
def __init__(
self,
sandbox_id: Optional[str] = None,
@@ -638,7 +612,7 @@ class SnapshotPaginatorBase(PaginatorBase):
self.sandbox_id = sandbox_id
-class SandboxPaginatorBase(PaginatorBase):
+class SandboxPaginatorBase(PaginatorBase[SandboxInfo, ApiParams]):
def __init__(
self,
query: Optional[SandboxQuery] = None,
diff --git a/packages/python-sdk/e2b/sandbox_async/paginator.py b/packages/python-sdk/e2b/sandbox_async/paginator.py
index 451ff7e55..269248c5e 100644
--- a/packages/python-sdk/e2b/sandbox_async/paginator.py
+++ b/packages/python-sdk/e2b/sandbox_async/paginator.py
@@ -70,8 +70,7 @@ class AsyncSandboxPaginator(SandboxPaginatorBase):
if res.status_code >= 300:
raise handle_api_exception(res)
- self._next_token = res.headers.get("x-next-token")
- self._has_next = bool(self._next_token)
+ self._update_pagination(res.headers)
if res.parsed is None:
return []
@@ -124,8 +123,7 @@ class AsyncSnapshotPaginator(SnapshotPaginatorBase):
if res.status_code >= 300:
raise handle_api_exception(res)
- self._next_token = res.headers.get("x-next-token")
- self._has_next = bool(self._next_token)
+ self._update_pagination(res.headers)
if res.parsed is None:
return []
diff --git a/packages/python-sdk/e2b/sandbox_sync/paginator.py b/packages/python-sdk/e2b/sandbox_sync/paginator.py
index 464de6644..9f0d4bf22 100644
--- a/packages/python-sdk/e2b/sandbox_sync/paginator.py
+++ b/packages/python-sdk/e2b/sandbox_sync/paginator.py
@@ -70,8 +70,7 @@ class SandboxPaginator(SandboxPaginatorBase):
if res.status_code >= 300:
raise handle_api_exception(res)
- self._next_token = res.headers.get("x-next-token")
- self._has_next = bool(self._next_token)
+ self._update_pagination(res.headers)
if res.parsed is None:
return []
@@ -124,8 +123,7 @@ class SnapshotPaginator(SnapshotPaginatorBase):
if res.status_code >= 300:
raise handle_api_exception(res)
- self._next_token = res.headers.get("x-next-token")
- self._has_next = bool(self._next_token)
+ self._update_pagination(res.headers)
if res.parsed is None:
return []
diff --git a/packages/python-sdk/tests/test_paginator.py b/packages/python-sdk/tests/test_paginator.py
new file mode 100644
index 000000000..e667f8eb0
--- /dev/null
+++ b/packages/python-sdk/tests/test_paginator.py
@@ -0,0 +1,53 @@
+import pytest
+
+from e2b.connection_config import ApiParams
+from e2b.paginator import PaginatorBase
+
+
+class FakePaginator(PaginatorBase[str, ApiParams]):
+ """Minimal paginator that returns canned pages and drives the shared state."""
+
+ def __init__(self, pages):
+ super().__init__()
+ self._pages = pages
+ self._call = 0
+
+ def next_items(self):
+ if not self.has_next:
+ raise Exception("No more items to fetch")
+
+ items, headers = self._pages[self._call]
+ self._call += 1
+ self._update_pagination(headers)
+ return items
+
+
+def test_paginator_exposes_state_and_advances():
+ paginator = FakePaginator(
+ [
+ (["a", "b"], {"x-next-token": "tok-2"}),
+ (["c"], {}),
+ ]
+ )
+
+ assert paginator.has_next is True
+ assert paginator.next_token is None
+
+ first = paginator.next_items()
+ assert first == ["a", "b"]
+ assert paginator.has_next is True
+ assert paginator.next_token == "tok-2"
+
+ second = paginator.next_items()
+ assert second == ["c"]
+ assert paginator.has_next is False
+ assert paginator.next_token is None
+
+
+def test_paginator_raises_once_exhausted():
+ paginator = FakePaginator([([], {})])
+ paginator.next_items()
+
+ assert paginator.has_next is False
+ with pytest.raises(Exception, match="No more items to fetch"):
+ paginator.next_items()