Add readme section, rename Paginator to SeamPaginator

Author: andrii-balitskyi

README.rst

@@ -257,6 +257,110 @@ For example:
   except SeamActionAttemptTimeoutError as e:
       print("Door took too long to unlock")
 
+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
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: python
+
+  from seam import Seam
+
+  seam = Seam()
+
+  paginator = seam.create_paginator(seam.connected_accounts.list, {"limit": 20})
+
+  connected_accounts, pagination = paginator.first_page()
+
+  if pagination.has_next_page:
+      more_connected_accounts, _ = paginator.next_page(pagination.next_page_cursor)
+
+Resume pagination
+^^^^^^^^^^^^^^^^^
+
+Get the first page on initial load and store the state (e.g., in memory or a file):
+
+.. code-block:: python
+
+  import json
+  from seam import Seam
+
+  seam = Seam()
+
+  params = {"limit": 20}
+  paginator = seam.create_paginator(seam.connected_accounts.list, params)
+
+  connected_accounts, pagination = paginator.first_page()
+
+  # Example: Store state for later use (e.g., in a file or database)
+  pagination_state = {
+      "params": params,
+      "next_page_cursor": pagination.next_page_cursor,
+      "has_next_page": pagination.has_next_page,
+  }
+  # with open("pagination_state.json", "w") as f:
+  # with open("/tmp/seam_connected_accounts_list.json", "w") as f:
+  #     json.dump(pagination_state, f)
+
+Get the next page at a later time using the stored state:
+
+.. code-block:: python
+
+  import json
+  from seam import Seam
+
+  seam = Seam()
+
+  # Example: Load state from where it was stored
+  # with open("/tmp/seam_connected_accounts_list.json", "r") as f:
+  #     pagination_state = json.load(f)
+  # Placeholder for loaded state:
+  pagination_state = {
+      "params": {"limit": 20},
+      "next_page_cursor": "some_cursor_value",
+      "has_next_page": True,
+  }
+
+
+  if pagination_state.get("has_next_page"):
+      paginator = seam.create_paginator(
+          seam.connected_accounts.list, pagination_state["params"]
+      )
+      more_connected_accounts, _ = paginator.next_page(
+          pagination_state["next_page_cursor"]
+      )
+
+Iterate over all resources
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: python
+
+  from seam import Seam
+
+  seam = Seam()
+
+  paginator = seam.create_paginator(seam.connected_accounts.list, {"limit": 20})
+
+  for account in paginator.flatten():
+      print(account.account_type_display_name)
+
+Return all resources across all pages as a list
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: python
+
+  from seam import Seam
+
+  seam = Seam()
+
+  paginator = seam.create_paginator(seam.connected_accounts.list, {"limit": 20})
+
+  all_connected_accounts = paginator.flatten_to_list()
+
 Interacting with Multiple Workspaces
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

seam/paginator.py

@@ -4,7 +4,7 @@
 from .pagination import Pagination
 
 
-class Paginator:
+class SeamPaginator:
     """
     Handles pagination for API list endpoints.
 

seam/seam.py

@@ -7,7 +7,7 @@
 from .routes import Routes
 from .models import AbstractSeam
 from .client import SeamHttpClient
-from .paginator import Paginator
+from .paginator import SeamPaginator
 
 
 class Seam(AbstractSeam):
@@ -92,7 +92,7 @@ def __init__(
 
     def create_paginator(
         self, request: Callable, params: Optional[Dict[str, Any]] = None, /
-    ) -> Paginator:
+    ) -> SeamPaginator:
         """
         Creates a Paginator instance for iterating through list endpoints.
 
@@ -113,7 +113,7 @@ def create_paginator(
             >>> for connected_account in connected_accounts_paginator.flatten():
             >>>     print(connected_account.account_type_display_name)
         """
-        return Paginator(self.client, request, params)
+        return SeamPaginator(self.client, request, params)
 
     @classmethod
     def from_api_key(