feat: Add $seam->createPaginator (#290)

Co-authored-by: Seam Bot <seambot@getseam.com>

Author: andrii-balitskyi

README.md

@@ -11,32 +11,32 @@ $seam = new Seam\SeamClient("YOUR_API_KEY");
 
 # Create a Connect Webview to login to a provider
 $connect_webview = $seam->connect_webviews->create(
-  accepted_providers: ["august"]
+    accepted_providers: ["august"]
 );
 
 print "Please Login at this url: " . $connect_webview->url;
 
 # Poll until connect webview is completed
 while (true) {
-  $connect_webview = $seam->connect_webviews->get(
-    $connect_webview->connect_webview_id
-  );
-  if ($connect_webview->status == "authorized") {
-    break;
-  } else {
-    sleep(1);
-  }
+    $connect_webview = $seam->connect_webviews->get(
+        $connect_webview->connect_webview_id
+    );
+    if ($connect_webview->status == "authorized") {
+        break;
+    } else {
+        sleep(1);
+    }
 }
 
 $connected_account = $seam->connected_accounts->get(
-  $connect_webview->connected_account_id
+    $connect_webview->connected_account_id
 );
 
 print "Looks like you connected with " .
-  json_encode($connected_account->user_identifier);
+    json_encode($connected_account->user_identifier);
 
 $devices = $seam->devices->list(
-  connected_account_id: $connected_account->connected_account_id
+    connected_account_id: $connected_account->connected_account_id
 );
 
 print "You have " . count($devices) . " devices";
@@ -55,9 +55,9 @@ $updated_device->properties->locked; // false
 
 # Create an access code on a device
 $access_code = $seam->access_codes->create(
-  device_id: $device_id,
-  code: "1234",
-  name: "Test Code"
+    device_id: $device_id,
+    code: "1234",
+    name: "Test Code"
 );
 
 # Check the status of an access code
@@ -66,6 +66,93 @@ $access_code->status; // 'setting' (it will go to 'set' when active on the devic
 $seam->access_codes->delete($access_code->access_code_id);
 ```
 
+### Pagination
+
+Some Seam API endpoints that return lists of resources support pagination.
+Use the `Paginator` class to fetch and process resources across multiple pages.
+
+#### Manually fetch pages with the next_page_cursor
+
+```php
+$pages = $seam->createPaginator(
+    fn($params) => $seam->connected_accounts->list(...$params),
+    ["limit" => 2]
+);
+
+[$connectedAccounts, $pagination] = $pages->firstPage();
+
+if ($pagination->has_next_page) {
+    [$moreConnectedAccounts] = $pages->nextPage($pagination->next_page_cursor);
+}
+```
+
+#### Resume pagination
+
+Get the first page on initial load:
+
+```php
+$params = ["limit" => 20];
+
+$pages = $seam->createPaginator(
+    fn($p) => $seam->connected_accounts->list(...$p),
+    $params
+);
+
+[$connectedAccounts, $pagination] = $pages->firstPage();
+
+// Store pagination state for later use
+file_put_contents(
+    "/tmp/seam_connected_accounts_list.json",
+    json_encode([$params, $pagination])
+);
+```
+
+Get the next page at a later time:
+
+```php
+$stored_data = json_decode(
+    file_get_contents("/tmp/seam_connected_accounts_list.json") ?: "[]",
+    false
+);
+
+$params = $stored_data[0] ?? [];
+$pagination =
+    $stored_data[1] ??
+    (object) ["has_next_page" => false, "next_page_cursor" => null];
+
+if ($pagination->has_next_page) {
+    $pages = $seam->createPaginator(
+        fn($p) => $seam->connected_accounts->list(...$p),
+        $params
+    );
+    [$moreConnectedAccounts] = $pages->nextPage($pagination->next_page_cursor);
+}
+```
+
+#### Iterate over all resources
+
+```php
+$pages = $seam->createPaginator(
+    fn($p) => $seam->connected_accounts->list(...$p),
+    ["limit" => 20]
+);
+
+foreach ($pages->flatten() as $connectedAccount) {
+    print $connectedAccount->account_type_display_name . "\n";
+}
+```
+
+#### Return all resources across all pages as an array
+
+```php
+$pages = $seam->createPaginator(
+    fn($p) => $seam->connected_accounts->list(...$p),
+    ["limit" => 20]
+);
+
+$connectedAccounts = $pages->flattenToArray();
+```
+
 ## Installation
 
 To install the latest version of the automatically generated SDK, run:
@@ -87,4 +174,4 @@ If you want to install our previous handwritten version, run:
 
 ### Running Tests
 
-You'll need to export `SEAM_API_KEY` to a sandbox workspace API key.
+You'll need to export `SEAM_API_KEY` to a sandbox workspace API key.

package-lock.json

@@ -12,8 +12,8 @@
   },
   "devDependencies": {
     "@prettier/plugin-php": "^0.22.1",
-    "@seamapi/nextlove-sdk-generator": "1.15.8",
-    "@seamapi/types": "1.351.1",
+    "@seamapi/nextlove-sdk-generator": "1.18.0",
+    "@seamapi/types": "1.377.0",
     "del": "^7.1.0",
     "prettier": "^3.0.0"
   }