feat: add REST client and WebSocket gateway

Author: jackharrhy

stackcoin/stackcoin/__init__.py

@@ -1,5 +1,7 @@
 """StackCoin Python SDK."""
 
+from .client import Client
 from .errors import StackCoinError
+from .gateway import Event, Gateway
 
-__all__ = ["StackCoinError"]
+__all__ = ["Client", "Event", "Gateway", "StackCoinError"]

stackcoin/stackcoin/client.py

@@ -0,0 +1,227 @@
+"""Async REST client for the StackCoin API."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from .errors import StackCoinError
+from .models import (
+    CreateRequestResponse,
+    DiscordGuild,
+    DiscordGuildsResponse,
+    Request,
+    RequestActionResponse,
+    RequestsResponse,
+    SendStkResponse,
+    Transaction,
+    TransactionsResponse,
+    User,
+    UsersResponse,
+)
+
+
+class Client:
+    """Async client for the StackCoin REST API.
+
+    Usage::
+
+        async with Client("https://stackcoin.example.com", token="sk-...") as client:
+            me = await client.get_me()
+            print(me.username, me.balance)
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        token: str,
+        *,
+        timeout: float = 10.0,
+    ) -> None:
+        self._http = httpx.AsyncClient(
+            base_url=base_url,
+            headers={
+                "Authorization": f"Bearer {token}",
+                "Accept": "application/json",
+            },
+            timeout=timeout,
+        )
+
+    # -- context manager -------------------------------------------------- #
+
+    async def __aenter__(self) -> Client:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: Any,
+    ) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        await self._http.aclose()
+
+    # -- shared helpers --------------------------------------------------- #
+
+    @staticmethod
+    def _raise_for_error(resp: httpx.Response) -> None:
+        """Raise :class:`StackCoinError` on any 4xx/5xx response."""
+        if resp.status_code >= 400:
+            try:
+                body = resp.json()
+            except Exception:
+                body = {}
+            error = body.get("error", f"http_{resp.status_code}")
+            message = body.get("message")
+            raise StackCoinError(resp.status_code, error, message)
+
+    # -- users ------------------------------------------------------------ #
+
+    async def get_me(self) -> User:
+        """Return the authenticated user's profile."""
+        resp = await self._http.get("/api/user/me")
+        self._raise_for_error(resp)
+        return User.model_validate(resp.json())
+
+    async def get_user(self, user_id: int) -> User:
+        """Return a user by their ID."""
+        resp = await self._http.get(f"/api/user/{user_id}")
+        self._raise_for_error(resp)
+        return User.model_validate(resp.json())
+
+    async def get_users(self, *, discord_id: str | None = None) -> list[User]:
+        """Return a list of users, optionally filtered by Discord ID."""
+        params: dict[str, Any] = {}
+        if discord_id is not None:
+            params["discord_id"] = discord_id
+        resp = await self._http.get("/api/users", params=params)
+        self._raise_for_error(resp)
+        wrapper = UsersResponse.model_validate(resp.json())
+        return wrapper.users or []
+
+    # -- send ------------------------------------------------------------- #
+
+    async def send(
+        self,
+        to_user_id: int,
+        amount: int,
+        *,
+        label: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> SendStkResponse:
+        """Send STK to another user."""
+        body: dict[str, Any] = {"amount": amount}
+        if label is not None:
+            body["label"] = label
+        headers: dict[str, str] = {}
+        if idempotency_key is not None:
+            headers["Idempotency-Key"] = idempotency_key
+        resp = await self._http.post(
+            f"/api/user/{to_user_id}/send",
+            json=body,
+            headers=headers,
+        )
+        self._raise_for_error(resp)
+        return SendStkResponse.model_validate(resp.json())
+
+    # -- requests --------------------------------------------------------- #
+
+    async def create_request(
+        self,
+        to_user_id: int,
+        amount: int,
+        *,
+        label: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> CreateRequestResponse:
+        """Create a STK request to another user."""
+        body: dict[str, Any] = {"amount": amount}
+        if label is not None:
+            body["label"] = label
+        headers: dict[str, str] = {}
+        if idempotency_key is not None:
+            headers["Idempotency-Key"] = idempotency_key
+        resp = await self._http.post(
+            f"/api/user/{to_user_id}/request",
+            json=body,
+            headers=headers,
+        )
+        self._raise_for_error(resp)
+        return CreateRequestResponse.model_validate(resp.json())
+
+    async def get_request(self, request_id: int) -> Request:
+        """Return a single request by its ID."""
+        resp = await self._http.get(f"/api/request/{request_id}")
+        self._raise_for_error(resp)
+        return Request.model_validate(resp.json())
+
+    async def get_requests(self, *, status: str | None = None) -> list[Request]:
+        """Return requests for the authenticated user, optionally filtered by status."""
+        params: dict[str, Any] = {}
+        if status is not None:
+            params["status"] = status
+        resp = await self._http.get("/api/requests", params=params)
+        self._raise_for_error(resp)
+        wrapper = RequestsResponse.model_validate(resp.json())
+        return wrapper.requests or []
+
+    async def accept_request(self, request_id: int) -> RequestActionResponse:
+        """Accept a pending STK request."""
+        resp = await self._http.post(f"/api/requests/{request_id}/accept")
+        self._raise_for_error(resp)
+        return RequestActionResponse.model_validate(resp.json())
+
+    async def deny_request(self, request_id: int) -> RequestActionResponse:
+        """Deny a pending STK request."""
+        resp = await self._http.post(f"/api/requests/{request_id}/deny")
+        self._raise_for_error(resp)
+        return RequestActionResponse.model_validate(resp.json())
+
+    # -- transactions ----------------------------------------------------- #
+
+    async def get_transactions(self) -> list[Transaction]:
+        """Return transactions for the authenticated user."""
+        resp = await self._http.get("/api/transactions")
+        self._raise_for_error(resp)
+        wrapper = TransactionsResponse.model_validate(resp.json())
+        return wrapper.transactions or []
+
+    async def get_transaction(self, transaction_id: int) -> Transaction:
+        """Return a single transaction by its ID."""
+        resp = await self._http.get(f"/api/transaction/{transaction_id}")
+        self._raise_for_error(resp)
+        return Transaction.model_validate(resp.json())
+
+    # -- events ----------------------------------------------------------- #
+
+    async def get_events(self, *, since_id: int = 0) -> list[dict[str, Any]]:
+        """Return events since the given ID.
+
+        Events are not yet in the OpenAPI spec, so this returns raw dicts.
+        """
+        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)
+        data = resp.json()
+        return data.get("events", data) if isinstance(data, dict) else data
+
+    # -- discord guilds --------------------------------------------------- #
+
+    async def get_discord_guilds(self) -> list[DiscordGuild]:
+        """Return all Discord guilds."""
+        resp = await self._http.get("/api/discord/guilds")
+        self._raise_for_error(resp)
+        wrapper = DiscordGuildsResponse.model_validate(resp.json())
+        return wrapper.guilds or []
+
+    async def get_discord_guild(self, snowflake: str) -> DiscordGuild:
+        """Return a single Discord guild by its snowflake ID."""
+        resp = await self._http.get(f"/api/discord/guild/{snowflake}")
+        self._raise_for_error(resp)
+        return DiscordGuild.model_validate(resp.json())

stackcoin/stackcoin/gateway.py

@@ -0,0 +1,150 @@
+"""StackCoin WebSocket Gateway client."""
+
+import asyncio
+import json
+from typing import Any, Callable, Awaitable
+
+from pydantic import BaseModel
+
+
+EventHandler = Callable[["Event"], Awaitable[None]]
+
+
+class Event(BaseModel):
+    """A StackCoin event received via the gateway."""
+    id: int
+    type: str
+    data: dict[str, Any]
+    inserted_at: str
+
+
+class Gateway:
+    """WebSocket gateway for receiving real-time StackCoin events.
+    
+    Usage::
+    
+        gateway = stackcoin.Gateway(
+            ws_url="ws://localhost:4000/bot/websocket",
+            token="...",
+        )
+        
+        @gateway.on("request.accepted")
+        async def handle_accepted(event: stackcoin.Event):
+            print(event.data["request_id"])
+        
+        await gateway.connect()
+    """
+    
+    def __init__(
+        self,
+        ws_url: str,
+        token: str,
+        last_event_id: int = 0,
+        on_event_id: Callable[[int], None] | None = None,
+    ):
+        # ws_url should be the full websocket URL like "ws://localhost:4000/bot/websocket"
+        self._ws_url = ws_url.rstrip("/")
+        self._token = token
+        self._handlers: dict[str, list[EventHandler]] = {}
+        self._last_event_id = last_event_id
+        self._on_event_id = on_event_id  # callback to persist cursor position
+        self._ws = None
+        self._running = False
+        self._ref_counter = 0
+
+    @property
+    def last_event_id(self) -> int:
+        return self._last_event_id
+
+    def on(self, event_type: str) -> Callable[[EventHandler], EventHandler]:
+        """Decorator to register an event handler."""
+        def decorator(func: EventHandler) -> EventHandler:
+            self.register_handler(event_type, func)
+            return func
+        return decorator
+
+    def register_handler(self, event_type: str, handler: EventHandler) -> None:
+        """Register an event handler programmatically."""
+        if event_type not in self._handlers:
+            self._handlers[event_type] = []
+        self._handlers[event_type].append(handler)
+
+    async def connect(self) -> None:
+        """Connect and listen for events. Reconnects automatically on failure."""
+        import websockets
+        
+        self._running = True
+        
+        while self._running:
+            try:
+                url = f"{self._ws_url}?token={self._token}&vsn=2.0.0"
+                
+                async with websockets.connect(url) as ws:
+                    self._ws = ws
+                    await self._join_channel(ws)
+                    
+                    heartbeat_task = asyncio.create_task(self._heartbeat(ws))
+                    try:
+                        async for raw_msg in ws:
+                            msg = json.loads(raw_msg)
+                            await self._handle_message(msg)
+                    finally:
+                        heartbeat_task.cancel()
+            
+            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."""
+        self._ref_counter += 1
+        join_msg = json.dumps([
+            None,
+            str(self._ref_counter),
+            "user:self",
+            "phx_join",
+            {"last_event_id": self._last_event_id},
+        ])
+        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}")
+
+    async def _heartbeat(self, ws: Any) -> None:
+        """Send periodic heartbeats."""
+        while True:
+            await asyncio.sleep(30)
+            self._ref_counter += 1
+            hb = json.dumps([None, str(self._ref_counter), "phoenix", "heartbeat", {}])
+            await ws.send(hb)
+
+    async def _handle_message(self, msg: list[Any]) -> None:
+        """Dispatch incoming message to registered handlers."""
+        if len(msg) < 5:
+            return
+
+        event_name = msg[3]
+        payload = msg[4]
+
+        if event_name == "event":
+            event = Event.model_validate(payload)
+
+            if event.id > self._last_event_id:
+                self._last_event_id = event.id
+
+            for handler in self._handlers.get(event.type, []):
+                try:
+                    await handler(event)
+                except Exception:
+                    pass
+
+            if event.id > 0 and self._on_event_id:
+                try:
+                    self._on_event_id(event.id)
+                except Exception:
+                    pass
+
+    def stop(self) -> None:
+        """Signal the gateway to stop."""
+        self._running = False