feat: auto-paginate get_events, handle WebSocket join rejection

- get_events() now loops while has_more=true, auto-paginating
- Gateway raises TooManyMissedEventsError on join rejection (no auto-retry)
- Regenerated models with has_more field in EventsResponse

Author: jackharrhy

stackcoin/stackcoin/__init__.py

@@ -1,7 +1,7 @@
 """StackCoin Python library."""
 
 from .client import AnyEvent, Client
-from .errors import StackCoinError
+from .errors import StackCoinError, TooManyMissedEventsError
 from .gateway import Gateway
 from .models import (
     Event,
@@ -27,6 +27,7 @@
     "RequestDeniedData",
     "RequestDeniedEvent",
     "StackCoinError",
+    "TooManyMissedEventsError",
     "TransferCompletedData",
     "TransferCompletedEvent",
 ]

stackcoin/stackcoin/client.py

@@ -193,14 +193,28 @@ async def get_transaction(self, transaction_id: int) -> Transaction:
         return Transaction.model_validate(resp.json())
 
     async def get_events(self, *, since_id: int = 0) -> list[AnyEvent]:
-        """Return typed events since the given ID."""
-        params: dict[str, Any] = {}
-        if since_id:
-            params["since_id"] = since_id
-        resp = await self._http.get("/api/events", params=params)
-        self._raise_for_error(resp)
-        wrapper = EventsResponse.model_validate(resp.json())
-        return [e.root for e in wrapper.events]
+        """Return typed events since the given ID.
+
+        Automatically paginates through all available events.
+        """
+        all_events: list[AnyEvent] = []
+        cursor = since_id
+
+        while True:
+            params: dict[str, Any] = {}
+            if cursor:
+                params["since_id"] = cursor
+            resp = await self._http.get("/api/events", params=params)
+            self._raise_for_error(resp)
+            wrapper = EventsResponse.model_validate(resp.json())
+            page = [e.root for e in wrapper.events]
+            all_events.extend(page)
+
+            if not wrapper.has_more or not page:
+                break
+            cursor = page[-1].id
+
+        return all_events
 
     async def get_discord_guilds(self) -> list[DiscordGuild]:
         """Return all Discord guilds."""

stackcoin/stackcoin/errors.py

@@ -6,3 +6,12 @@ def __init__(self, status_code: int, error: str, message: str | None = None):
         self.error = error
         self.message = message
         super().__init__(f"{status_code} {error}: {message}")
+
+
+class TooManyMissedEventsError(StackCoinError):
+    """Raised when the WebSocket gateway rejects a join due to too many missed events."""
+
+    def __init__(self, missed_count: int, replay_limit: int, message: str):
+        super().__init__(status_code=0, error="too_many_missed_events", message=message)
+        self.missed_count = missed_count
+        self.replay_limit = replay_limit

stackcoin/stackcoin/gateway.py

@@ -65,6 +65,8 @@ async def connect(self) -> None:
         """Connect and listen for events. Reconnects automatically on failure."""
         import websockets
 
+        from .errors import TooManyMissedEventsError
+
         self._running = True
 
         while self._running:
@@ -83,12 +85,16 @@ async def connect(self) -> None:
                     finally:
                         heartbeat_task.cancel()
 
+            except TooManyMissedEventsError:
+                raise  # Don't retry — caller must catch up via REST
             except Exception:
                 if self._running:
                     await asyncio.sleep(5)
 
     async def _join_channel(self, ws: Any) -> None:
         """Join the user:self channel with event replay."""
+        from .errors import TooManyMissedEventsError
+
         self._ref_counter += 1
         join_msg = json.dumps(
             [
@@ -102,8 +108,19 @@ async def _join_channel(self, ws: Any) -> None:
         await ws.send(join_msg)
 
         reply = json.loads(await asyncio.wait_for(ws.recv(), timeout=10))
-        if not (reply[3] == "phx_reply" and reply[4].get("status") == "ok"):
-            raise ConnectionError(f"Failed to join channel: {reply}")
+        if reply[3] == "phx_reply" and reply[4].get("status") == "ok":
+            return
+
+        # Check for too_many_missed_events rejection
+        response = reply[4].get("response", {})
+        if response.get("reason") == "too_many_missed_events":
+            raise TooManyMissedEventsError(
+                missed_count=response.get("missed_count", 0),
+                replay_limit=response.get("replay_limit", 0),
+                message=response.get("message", "Too many missed events"),
+            )
+
+        raise ConnectionError(f"Failed to join channel: {reply}")
 
     async def _heartbeat(self, ws: Any) -> None:
         """Send periodic heartbeats."""

stackcoin/stackcoin/models.py

@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  openapi.json
-#   timestamp: 2026-03-05T04:32:37+00:00
+#   timestamp: 2026-03-06T18:41:27+00:00
 
 from __future__ import annotations
 
@@ -269,3 +269,4 @@ class Event(
 
 class EventsResponse(BaseModel):
     events: list[Event] = Field(..., description="The events list")
+    has_more: bool = Field(..., description="Whether more events exist beyond this page")