refactor: restructure to standard src/ layout, fix Gateway type annotations

Move pyproject.toml to repo root and package to src/stackcoin/ following
the standard Python src layout. Fix Gateway handler type to preserve
narrowed event types via TypeVar, and import Client directly to make
the client= param visible to type checkers.

Author: jackharrhy

.gitignore

@@ -1,7 +1,29 @@
 *.sh
 
-venv/
+# Python
+__pycache__/
+*.egg-info/
 dist/
 build/
-__pycache__
-*.egg-info/
+
+# Environments
+.venv/
+venv/
+.env
+
+# Testing
+.pytest_cache/
+coverage.xml
+.coverage
+
+# Tools
+.ruff_cache/
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# IDE
+.idea/
+
+# pyenv
+.python-version

README.md

@@ -30,20 +30,38 @@ asyncio.run(main())
 
 ## Gateway (real-time events)
 
+Pass a `client` to the Gateway so it can automatically catch up on missed events
+via the REST API if the bot has been offline too long (>100 events). Without a
+client, a `TooManyMissedEventsError` is raised and you must handle catch-up
+yourself.
+
 ```python
 import stackcoin
 
-gateway = stackcoin.Gateway(token="...")
+async with stackcoin.Client(token="...") as client:
+    gateway = stackcoin.Gateway(token="...", client=client)
+
+    @gateway.on("transfer.completed")
+    async def on_transfer(event: stackcoin.TransferCompletedEvent):
+        print(f"Transfer of {event.data.amount} STK from #{event.data.from_id} to #{event.data.to_id}")
 
-@gateway.on("transfer.completed")
-async def on_transfer(event: stackcoin.TransferCompletedEvent):
-    print(f"Transfer of {event.data.amount} STK from #{event.data.from_id} to #{event.data.to_id}")
+    @gateway.on("request.accepted")
+    async def on_accepted(event: stackcoin.RequestAcceptedEvent):
+        print(f"Request #{event.data.request_id} accepted")
 
-@gateway.on("request.accepted")
-async def on_accepted(event: stackcoin.RequestAcceptedEvent):
-    print(f"Request #{event.data.request_id} accepted")
+    await gateway.connect()
+```
 
-await gateway.connect()
+The Gateway also accepts `last_event_id` to resume from a known cursor, and
+`on_event_id` as a callback to persist the cursor position after each event:
+
+```python
+gateway = stackcoin.Gateway(
+    token="...",
+    client=client,
+    last_event_id=saved_cursor,
+    on_event_id=lambda eid: save_cursor(eid),
+)
 ```
 
 ## Examples

examples/simple_cli.py

@@ -146,8 +146,10 @@ async def main():
         me = await client.get_me()
         print(f"Connected to {base_url} as {me.username} ({me.balance} STK)")
 
-        # Set up gateway for live events
-        gateway = stackcoin.Gateway(token, ws_url=ws_url)
+        # Set up gateway for live events.
+        # Passing client= enables automatic REST catch-up if >100 events
+        # were missed while offline.
+        gateway = stackcoin.Gateway(token, ws_url=ws_url, client=client)
 
         @gateway.on("transfer.completed")
         async def on_transfer(event: stackcoin.TransferCompletedEvent):

justfile

@@ -5,10 +5,7 @@ generate:
     --input {{stackcoin_root}}/openapi.json \
     --input-file-type openapi \
     --output-model-type pydantic_v2.BaseModel \
-    --output stackcoin/stackcoin/models.py \
+    --output src/stackcoin/models.py \
     --target-python-version 3.13 \
     --output-datetime-class datetime
-  uvx ruff format stackcoin/
-
-dev:
-  uv pip install -e "stackcoin @ ./stackcoin"
+  uvx ruff format src/

stackcoin/pyproject.toml pyproject.tomlstackcoin/pyproject.toml renamed to pyproject.toml

@@ -14,7 +14,7 @@ requires = ["hatchling"]
 build-backend = "hatchling.build"
 
 [tool.hatch.build.targets.wheel]
-packages = ["stackcoin"]
+packages = ["src/stackcoin"]
 
 [tool.ruff]
 line-length = 100

stackcoin/stackcoin/__init__.py src/stackcoin/__init__.pystackcoin/stackcoin/__init__.py renamed to src/stackcoin/__init__.py

@@ -5,16 +5,18 @@
 import asyncio
 import json
 from collections.abc import Awaitable, Callable
-from typing import TYPE_CHECKING, Any
+from typing import Any, TypeVar
 
-from .client import AnyEvent
+from .client import AnyEvent, Client
 from .models import Event
 
-if TYPE_CHECKING:
-    from .client import Client
-
+# Internal handler type — accepts the full union at runtime.
 EventHandler = Callable[[AnyEvent], Awaitable[None]]
 
+# TypeVar for the @gateway.on() decorator so it preserves the caller's
+# narrowed signature (e.g. async def f(event: RequestAcceptedEvent)).
+_F = TypeVar("_F", bound=Callable[..., Awaitable[None]])
+
 
 class Gateway:
     """WebSocket gateway for receiving real-time StackCoin events.
@@ -59,11 +61,11 @@ def __init__(
     def last_event_id(self) -> int:
         return self._last_event_id
 
-    def on(self, event_type: str) -> Callable[[EventHandler], EventHandler]:
+    def on(self, event_type: str) -> Callable[[_F], _F]:
         """Decorator to register an event handler."""
 
-        def decorator(func: EventHandler) -> EventHandler:
-            self.register_handler(event_type, func)
+        def decorator(func: _F) -> _F:
+            self.register_handler(event_type, func)  # type: ignore[arg-type]
             return func
 
         return decorator