@seamapi/http 1.24.0 → 1.25.1

package/README.md

@@ -308,6 +308,93 @@ 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)
+}
+```
+
+#### Resume pagination
+
+Get the first page on initial load:
+
+```ts
+const params = { limit: 20 }
+
+const pages = seam.createPaginator(seam.devices.list(params))
+
+const [devices, pagination] = await pages.firstPage()
+
+localStorage.setItem('/seam/devices/list', JSON.stringify([params, pagination]))
+```
+
+Get the next page at a later time:
+
+```ts
+const [params = {}, { hasNextPage = false, nextPageCursor = null } = {}] =
+  JSON.parse(localStorage.getItem('/seam/devices/list') ?? '[]')
+
+if (hasNextPage) {
+  const pages = seam.createPaginator(seam.devices.list(params))
+  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.flattenToArray()
+```
+
 ### Interacting with Multiple Workspaces
 
 Some Seam API endpoints interact with multiple workspaces.