Update readme

Author: andrii-balitskyi

README.md

@@ -66,6 +66,92 @@ $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 +173,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.