fix: review polish — logging, narrowed catches, cursor fix, exports, py.typed

- Gateway: add logging on handler errors (replaces silent pass), narrow
  reconnect exception catch, replace assert with runtime check, stop()
  closes WebSocket properly
- Client: fix get_events cursor check (if cursor > 0 vs if cursor)
- __init__.py: export all return types (User, Transaction, etc.)
- Add py.typed PEP 561 marker
- README: fix model path, add Testing section

Author: jackharrhy

README.md

@@ -69,6 +69,21 @@ gateway = stackcoin.Gateway(
 - `examples/basic_usage.py` -- REST client basics (balance, requests, transactions)
 - `examples/simple_cli.py` -- interactive REPL with live gateway events
 
+## Testing
+
+Tests for this library live in the main
+[StackCoin/StackCoin](https://github.com/StackCoin/StackCoin) repository as
+end-to-end tests that boot a real StackCoin server:
+
+```sh
+cd /path/to/StackCoin/test/e2e
+uv sync
+uv run pytest
+```
+
+The E2E suite covers the REST client, WebSocket gateway, event pagination, and
+the [LuckyPot](https://github.com/StackCoin/LuckyPot) bot integration.
+
 ## Development
 
 Models are generated from the StackCoin OpenAPI spec using `datamodel-codegen`:
@@ -77,4 +92,4 @@ Models are generated from the StackCoin OpenAPI spec using `datamodel-codegen`:
 STACKCOIN_ROOT=/path/to/StackCoin just generate
 ```
 
-This regenerates `stackcoin/stackcoin/models.py` from `openapi.json`.
+This regenerates `src/stackcoin/models.py` from `openapi.json`.

src/stackcoin/__init__.py

@@ -4,30 +4,44 @@
 from .errors import StackCoinError, TooManyMissedEventsError
 from .gateway import Gateway
 from .models import (
+    CreateRequestResponse,
+    DiscordGuild,
     Event,
+    Request,
     RequestAcceptedData,
     RequestAcceptedEvent,
+    RequestActionResponse,
     RequestCreatedData,
     RequestCreatedEvent,
     RequestDeniedData,
     RequestDeniedEvent,
+    SendStkResponse,
+    Transaction,
     TransferCompletedData,
     TransferCompletedEvent,
+    User,
 )
 
 __all__ = [
     "AnyEvent",
     "Client",
+    "CreateRequestResponse",
+    "DiscordGuild",
     "Event",
     "Gateway",
+    "Request",
     "RequestAcceptedData",
     "RequestAcceptedEvent",
+    "RequestActionResponse",
     "RequestCreatedData",
     "RequestCreatedEvent",
     "RequestDeniedData",
     "RequestDeniedEvent",
+    "SendStkResponse",
     "StackCoinError",
     "TooManyMissedEventsError",
+    "Transaction",
     "TransferCompletedData",
     "TransferCompletedEvent",
+    "User",
 ]

src/stackcoin/client.py

@@ -202,7 +202,7 @@ async def get_events(self, *, since_id: int = 0) -> list[AnyEvent]:
 
         while True:
             params: dict[str, Any] = {}
-            if cursor:
+            if cursor > 0:
                 params["since_id"] = cursor
             resp = await self._http.get("/api/events", params=params)
             self._raise_for_error(resp)

src/stackcoin/gateway.py

@@ -4,12 +4,15 @@
 
 import asyncio
 import json
+import logging
 from collections.abc import Awaitable, Callable
 from typing import Any, TypeVar
 
 from .client import AnyEvent, Client
 from .models import Event
 
+logger = logging.getLogger(__name__)
+
 # Internal handler type — accepts the full union at runtime.
 EventHandler = Callable[[AnyEvent], Awaitable[None]]
 
@@ -85,6 +88,7 @@ async def connect(self) -> None:
         :class:`TooManyMissedEventsError`.
         """
         import websockets
+        import websockets.exceptions
 
         from .errors import TooManyMissedEventsError
 
@@ -111,8 +115,14 @@ async def connect(self) -> None:
                     raise  # No client — caller must handle catch-up
                 await self._catch_up_via_rest()
                 # Loop back to reconnect with updated cursor
-            except Exception:
+            except (
+                OSError,
+                ConnectionError,
+                asyncio.TimeoutError,
+                websockets.exceptions.WebSocketException,
+            ) as exc:
                 if self._running:
+                    logger.warning("Gateway connection lost: %s. Reconnecting in 5s...", exc)
                     await asyncio.sleep(5)
 
     async def _catch_up_via_rest(self) -> None:
@@ -121,7 +131,8 @@ async def _catch_up_via_rest(self) -> None:
         Dispatches each event through the registered handlers, exactly
         as if it arrived over the WebSocket.
         """
-        assert self._client is not None
+        if self._client is None:
+            raise RuntimeError("Cannot catch up via REST without a client")
         events = await self._client.get_events(since_id=self._last_event_id)
         for event in events:
             await self._dispatch_event(event)
@@ -135,13 +146,13 @@ async def _dispatch_event(self, typed_event: AnyEvent) -> None:
             try:
                 await handler(typed_event)
             except Exception:
-                pass
+                logger.exception("Error in %s handler for event %s", typed_event.type, typed_event.id)
 
         if typed_event.id > 0 and self._on_event_id:
             try:
                 self._on_event_id(typed_event.id)
             except Exception:
-                pass
+                logger.exception("Error in on_event_id callback for event %s", typed_event.id)
 
     async def _join_channel(self, ws: Any) -> None:
         """Join the user:self channel with event replay."""
@@ -196,5 +207,7 @@ async def _handle_message(self, msg: list[Any]) -> None:
             await self._dispatch_event(typed_event)
 
     def stop(self) -> None:
-        """Signal the gateway to stop."""
+        """Signal the gateway to stop and close the WebSocket connection."""
         self._running = False
+        if self._ws is not None:
+            asyncio.ensure_future(self._ws.close())

src/stackcoin/models.py

@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  openapi.json
-#   timestamp: 2026-03-06T18:41:27+00:00
+#   timestamp: 2026-03-06T23:08:44+00:00
 
 from __future__ import annotations