feat: Add seam.createPaginator (#283)

* Add SeamPaginator

* ci: Generate code

* Update interface

* Add nextPageCursor

* Fix SeamPaginator types

* Immutable SeamPaginator (#288)

* Immutable SeamPaginator

* Fix unused type

* Fix type error

* Update fake-seam-connect

* Run npm update

* Mark failing test

* Rename to fetchResponse

* Improve types

* Rename page to request

* Add more SeamPaginator tests

* Handle pagination via get or post

* ci: Format code

* ci: Generate code

* Export and document SeamPaginator

* ci: Format code

* Brand PageCursor

* Fix request

* Rename toArray to flattenToArray

* ci: Format code

* Use method version for #fetch

* ci: Format code

---------

Co-authored-by: Seam Bot <seambot@getseam.com>
Co-authored-by: Charles Pick <charles@codemix.com>

Author: 3 people

README.md

@@ -308,6 +308,67 @@ try {
 
 [action attempt]: https://docs.seam.co/latest/core-concepts/action-attempts
 
+### Pagination
+
+Some Seam API endpoints that return lists of resources support pagination.
+Use the `SeamPaginator` class to fetch and process resources across multiple pages.
+
+#### Manually fetch pages with the nextPageCursor
+
+```ts
+const pages = seam.createPaginator(
+  seam.devices.list({
+    limit: 20,
+  }),
+)
+
+const [devices, { hasNextPage, nextPageCursor }] = await pages.firstPage()
+
+if (hasNextPage) {
+  const [moreDevices] = await pages.nextPage(nextPageCursor)
+}
+```
+
+#### Iterate over all pages
+
+```ts
+const pages = seam.createPaginator(
+  seam.devices.list({
+    limit: 20,
+  }),
+)
+
+for await (const devices of pages) {
+  console.log(`There are ${devices.length} devices on this page.`)
+}
+```
+
+#### Iterate over all resources
+
+```ts
+const pages = seam.createPaginator(
+  seam.devices.list({
+    limit: 20,
+  }),
+)
+
+for await (const device of pages.flatten()) {
+  console.log(devices.name)
+}
+```
+
+#### Return all resources across all pages as an array
+
+```ts
+const pages = seam.createPaginator(
+  seam.devices.list({
+    limit: 20,
+  }),
+)
+
+const devices = await pages.toArray()
+```
+
 ### Interacting with Multiple Workspaces
 
 Some Seam API endpoints interact with multiple workspaces.

generate-routes.ts

@@ -299,6 +299,7 @@ import {
   resolveActionAttempt,
 } from 'lib/seam/connect/resolve-action-attempt.js'
 import { SeamHttpRequest } from 'lib/seam/connect/seam-http-request.js'
+import { SeamPaginator } from 'lib/seam/connect/seam-paginator.js'
 
 ${
   namespace === 'client_sessions'