vox-sdk 0.1.0__tar.gz

vox_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: vox-sdk
+Version: 0.1.0
+Summary: Python client SDK for the Vox protocol
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: websockets>=13.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: zstandard>=0.23
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Provides-Extra: media
+Requires-Dist: vox-media>=0.1; extra == "media"

vox_sdk-0.1.0/README.md

@@ -0,0 +1,106 @@
+# Vox Python SDK
+
+Python client SDK for the Vox protocol.
+
+## Install
+
+```bash
+pip install vox-sdk
+```
+
+## Quickstart
+
+```python
+import asyncio
+from vox_sdk import Client
+
+async def main():
+    async with Client("https://vox.example.com") as client:
+        # Login
+        await client.login("alice", "password123")
+
+        # Send a message
+        msg = await client.messages.send(feed_id=1, body="Hello from the SDK!")
+
+        # List members
+        members = await client.members.list()
+        print(f"{len(members.items)} members online")
+
+asyncio.run(main())
+```
+
+## Gateway Events
+
+```python
+import asyncio
+from vox_sdk import Client, GatewayClient
+
+async def main():
+    async with Client("https://vox.example.com") as client:
+        await client.login("alice", "password123")
+
+        info = await client.server.gateway_info()
+        gw = GatewayClient(info.url, client.http.token)
+
+        @gw.on("message_create")
+        async def on_message(event):
+            print(f"[{event.feed_id}] {event.author_id}: {event.body}")
+
+        @gw.on("presence_update")
+        async def on_presence(event):
+            print(f"User {event.user_id} is now {event.status}")
+
+        # run() auto-reconnects on recoverable errors
+        await gw.run()
+
+asyncio.run(main())
+```
+
+## Error Handling
+
+```python
+from vox_sdk import VoxHTTPError, VoxNetworkError
+from vox_sdk.errors import VoxGatewayError
+
+try:
+    await client.messages.send(feed_id=1, body="hello")
+except VoxHTTPError as e:
+    print(f"API error: {e.status} {e.code}")
+except VoxNetworkError as e:
+    print(f"Network error: {e}")
+```
+
+## API Groups
+
+The client exposes these API groups as properties:
+
+| Property | Description |
+|---|---|
+| `client.auth` | Login, register, MFA, sessions |
+| `client.messages` | Send, edit, delete, reactions, pins |
+| `client.channels` | Feeds, rooms, categories, threads |
+| `client.members` | List, get, ban, kick, update |
+| `client.roles` | Create, assign, permissions |
+| `client.server` | Server info, layout, limits |
+| `client.users` | Profiles, friends, blocks |
+| `client.invites` | Create, resolve, delete |
+| `client.dms` | Open, send, close DMs |
+| `client.voice` | Join, leave, mute, stage |
+| `client.webhooks` | Create, execute webhooks |
+| `client.bots` | Commands, interactions |
+| `client.files` | Upload, download, delete |
+| `client.emoji` | Emoji and stickers |
+| `client.e2ee` | Prekeys, devices, MLS |
+| `client.moderation` | Reports, audit log |
+| `client.federation` | Cross-server federation |
+| `client.search` | Message search |
+| `client.sync` | Offline sync |
+| `client.embeds` | URL embed resolution |
+
+## Models
+
+All response models are re-exported from `vox_sdk.models`:
+
+```python
+from vox_sdk.models import MessageResponse, UserResponse, FeedResponse
+```

vox_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vox-sdk"
+version = "0.1.0"
+description = "Python client SDK for the Vox protocol"
+requires-python = ">=3.11"
+dependencies = [
+    "httpx>=0.27",
+    "websockets>=13.0",
+    "pydantic>=2.0",
+    "zstandard>=0.23",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "pytest-cov>=5.0",
+    "ruff>=0.6",
+]
+media = [
+    "vox-media>=0.1",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+addopts = "--cov=vox_sdk --cov-report=term-missing"

vox_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vox_sdk-0.1.0/setup.py

@@ -0,0 +1,43 @@
+"""Custom build hooks — clean stale native extensions before editable installs.
+
+maturin develop can leave .so/.pyd files in src/ that shadow pure-Python
+wrappers and cause hard-to-debug import failures.  This hooks into both
+``pip install -e .`` and ``python setup.py develop`` to wipe them first.
+"""
+
+import glob
+import os
+
+from setuptools import setup
+from setuptools.command.build_py import build_py
+from setuptools.command.develop import develop
+
+_STALE_PATTERNS = ("src/**/*.so", "src/**/*.dylib", "src/**/*.pyd")
+
+
+def _clean_stale_extensions() -> None:
+    root = os.path.dirname(os.path.abspath(__file__))
+    for pattern in _STALE_PATTERNS:
+        for path in glob.glob(os.path.join(root, pattern), recursive=True):
+            print(f"removing stale native extension: {path}")
+            os.remove(path)
+
+
+class CleanDevelop(develop):
+    def run(self) -> None:
+        _clean_stale_extensions()
+        super().run()
+
+
+class CleanBuildPy(build_py):
+    def run(self) -> None:
+        _clean_stale_extensions()
+        super().run()
+
+
+setup(
+    cmdclass={
+        "develop": CleanDevelop,
+        "build_py": CleanBuildPy,
+    },
+)

vox_sdk-0.1.0/src/vox_sdk/__init__.py

@@ -0,0 +1,15 @@
+"""Vox Client SDK — Python client for the Vox protocol."""
+
+from vox_sdk.client import Client
+from vox_sdk.gateway import GatewayClient
+from vox_sdk.errors import VoxHTTPError, VoxGatewayError, VoxNetworkError
+from vox_sdk.permissions import Permissions
+
+__all__ = [
+    "Client",
+    "GatewayClient",
+    "Permissions",
+    "VoxHTTPError",
+    "VoxGatewayError",
+    "VoxNetworkError",
+]

vox_sdk-0.1.0/src/vox_sdk/_media.py

@@ -0,0 +1,6 @@
+"""Re-export the native vox_media extension as vox_sdk._media."""
+
+from vox_media import *  # noqa: F401,F403
+from vox_media import VoxMediaClient
+
+__all__ = ["VoxMediaClient"]

vox_sdk-0.1.0/src/vox_sdk/api/__init__.py

@@ -0,0 +1 @@
+"""SDK API method groups."""

vox_sdk-0.1.0/src/vox_sdk/api/auth.py

@@ -0,0 +1,153 @@
+"""Auth API methods."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from vox_sdk.models.auth import (
+    LoginResponse,
+    MFARequiredResponse,
+    MFASetupConfirmResponse,
+    MFASetupResponse,
+    MFAStatusResponse,
+    RegisterResponse,
+    SessionListResponse,
+    SuccessResponse,
+    WebAuthnChallengeResponse,
+    WebAuthnCredentialResponse,
+)
+
+if TYPE_CHECKING:
+    from vox_sdk.http import HTTPClient
+
+
+class AuthAPI:
+    """Methods for /api/v1/auth endpoints."""
+
+    def __init__(self, http: HTTPClient) -> None:
+        self._http = http
+
+    async def register(
+        self, username: str, password: str, display_name: str | None = None
+    ) -> RegisterResponse:
+        payload: dict[str, Any] = {"username": username, "password": password}
+        if display_name is not None:
+            payload["display_name"] = display_name
+        r = await self._http.post("/api/v1/auth/register", json=payload)
+        return RegisterResponse.model_validate(r.json())
+
+    async def login(self, username: str, password: str) -> LoginResponse | MFARequiredResponse:
+        r = await self._http.post(
+            "/api/v1/auth/login", json={"username": username, "password": password}
+        )
+        data = r.json()
+        if data.get("mfa_required"):
+            return MFARequiredResponse.model_validate(data)
+        return LoginResponse.model_validate(data)
+
+    async def login_2fa(
+        self,
+        mfa_ticket: str,
+        method: str,
+        code: str | None = None,
+        assertion: dict | None = None,
+    ) -> LoginResponse:
+        payload: dict[str, Any] = {"mfa_ticket": mfa_ticket, "method": method}
+        if code is not None:
+            payload["code"] = code
+        if assertion is not None:
+            payload["assertion"] = assertion
+        r = await self._http.post("/api/v1/auth/login/2fa", json=payload)
+        return LoginResponse.model_validate(r.json())
+
+    async def login_webauthn_challenge(self, username: str) -> WebAuthnChallengeResponse:
+        r = await self._http.post(
+            "/api/v1/auth/login/webauthn/challenge", json={"username": username}
+        )
+        return WebAuthnChallengeResponse.model_validate(r.json())
+
+    async def login_webauthn(
+        self,
+        username: str,
+        challenge_id: str,
+        client_data_json: str,
+        authenticator_data: str,
+        signature: str,
+        credential_id: str,
+        user_handle: str | None = None,
+    ) -> LoginResponse:
+        payload: dict[str, Any] = {
+            "username": username,
+            "challenge_id": challenge_id,
+            "client_data_json": client_data_json,
+            "authenticator_data": authenticator_data,
+            "signature": signature,
+            "credential_id": credential_id,
+        }
+        if user_handle is not None:
+            payload["user_handle"] = user_handle
+        r = await self._http.post("/api/v1/auth/login/webauthn", json=payload)
+        return LoginResponse.model_validate(r.json())
+
+    async def login_federation(self, federation_token: str) -> LoginResponse:
+        r = await self._http.post(
+            "/api/v1/auth/login/federation", json={"federation_token": federation_token}
+        )
+        return LoginResponse.model_validate(r.json())
+
+    async def logout(self) -> None:
+        await self._http.post("/api/v1/auth/logout")
+
+    async def mfa_status(self) -> MFAStatusResponse:
+        r = await self._http.get("/api/v1/auth/2fa")
+        return MFAStatusResponse.model_validate(r.json())
+
+    async def mfa_setup(self, method: str) -> MFASetupResponse:
+        r = await self._http.post("/api/v1/auth/2fa/setup", json={"method": method})
+        return MFASetupResponse.model_validate(r.json())
+
+    async def mfa_setup_confirm(
+        self,
+        setup_id: str,
+        code: str | None = None,
+        attestation: dict | None = None,
+        credential_name: str | None = None,
+    ) -> MFASetupConfirmResponse:
+        payload: dict[str, Any] = {"setup_id": setup_id}
+        if code is not None:
+            payload["code"] = code
+        if attestation is not None:
+            payload["attestation"] = attestation
+        if credential_name is not None:
+            payload["credential_name"] = credential_name
+        r = await self._http.post("/api/v1/auth/2fa/setup/confirm", json=payload)
+        return MFASetupConfirmResponse.model_validate(r.json())
+
+    async def mfa_remove(
+        self,
+        method: str,
+        code: str | None = None,
+        assertion: dict | None = None,
+    ) -> SuccessResponse:
+        payload: dict[str, Any] = {"method": method}
+        if code is not None:
+            payload["code"] = code
+        if assertion is not None:
+            payload["assertion"] = assertion
+        r = await self._http.delete("/api/v1/auth/2fa", json=payload)
+        return SuccessResponse.model_validate(r.json())
+
+    async def list_webauthn_credentials(self) -> list[WebAuthnCredentialResponse]:
+        r = await self._http.get("/api/v1/auth/webauthn/credentials")
+        return [WebAuthnCredentialResponse.model_validate(c) for c in r.json()]
+
+    async def delete_webauthn_credential(self, credential_id: str) -> SuccessResponse:
+        r = await self._http.delete(f"/api/v1/auth/webauthn/credentials/{credential_id}")
+        return SuccessResponse.model_validate(r.json())
+
+    async def list_sessions(self) -> SessionListResponse:
+        r = await self._http.get("/api/v1/auth/sessions")
+        return SessionListResponse.model_validate(r.json())
+
+    async def revoke_session(self, session_id: int) -> None:
+        await self._http.delete(f"/api/v1/auth/sessions/{session_id}")

vox_sdk-0.1.0/src/vox_sdk/api/bots.py

@@ -0,0 +1,63 @@
+"""Bots API methods."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from vox_sdk.models.bots import CommandListResponse, OkResponse
+
+if TYPE_CHECKING:
+    from vox_sdk.http import HTTPClient
+
+
+class BotsAPI:
+    def __init__(self, http: HTTPClient) -> None:
+        self._http = http
+
+    async def register_commands(
+        self, user_id: int, commands: list[dict[str, Any]]
+    ) -> OkResponse:
+        r = await self._http.put(
+            f"/api/v1/bots/{user_id}/commands", json={"commands": commands}
+        )
+        return OkResponse.model_validate(r.json())
+
+    async def list_bot_commands(self, user_id: int) -> CommandListResponse:
+        r = await self._http.get(f"/api/v1/bots/{user_id}/commands")
+        return CommandListResponse.model_validate(r.json())
+
+    async def deregister_commands(
+        self, user_id: int, command_names: list[str]
+    ) -> OkResponse:
+        r = await self._http.delete(
+            f"/api/v1/bots/{user_id}/commands", json={"command_names": command_names}
+        )
+        return OkResponse.model_validate(r.json())
+
+    async def list_commands(self) -> CommandListResponse:
+        r = await self._http.get("/api/v1/commands")
+        return CommandListResponse.model_validate(r.json())
+
+    async def respond_to_interaction(
+        self,
+        interaction_id: str,
+        *,
+        body: str | None = None,
+        embeds: list[dict] | None = None,
+        components: list[dict] | None = None,
+        ephemeral: bool = False,
+    ) -> None:
+        payload: dict[str, Any] = {"ephemeral": ephemeral}
+        if body is not None:
+            payload["body"] = body
+        if embeds is not None:
+            payload["embeds"] = embeds
+        if components is not None:
+            payload["components"] = components
+        await self._http.post(f"/api/v1/interactions/{interaction_id}/response", json=payload)
+
+    async def component_interaction(self, msg_id: int, component_id: str) -> None:
+        await self._http.post(
+            "/api/v1/interactions/component",
+            json={"msg_id": msg_id, "component_id": component_id},
+        )

vox_sdk-0.1.0/src/vox_sdk/api/channels.py

@@ -0,0 +1,196 @@
+"""Channels API methods (feeds, rooms, categories, threads)."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from vox_sdk.models.channels import (
+    CategoryListResponse,
+    CategoryResponse,
+    FeedResponse,
+    RoomResponse,
+    ThreadListResponse,
+    ThreadResponse,
+)
+from vox_sdk.models.enums import FeedType, RoomType
+
+if TYPE_CHECKING:
+    from vox_sdk.http import HTTPClient
+
+_UNSET: Any = object()
+
+
+class ChannelsAPI:
+    def __init__(self, http: HTTPClient) -> None:
+        self._http = http
+
+    # --- Feeds ---
+
+    async def get_feed(self, feed_id: int) -> FeedResponse:
+        r = await self._http.get(f"/api/v1/feeds/{feed_id}")
+        return FeedResponse.model_validate(r.json())
+
+    async def create_feed(
+        self,
+        name: str,
+        type: FeedType = FeedType.text,
+        *,
+        category_id: int | None = None,
+        permission_overrides: list[dict] | None = None,
+    ) -> FeedResponse:
+        payload: dict[str, Any] = {"name": name, "type": type}
+        if category_id is not None:
+            payload["category_id"] = category_id
+        if permission_overrides is not None:
+            payload["permission_overrides"] = permission_overrides
+        r = await self._http.post("/api/v1/feeds", json=payload)
+        return FeedResponse.model_validate(r.json())
+
+    async def update_feed(
+        self,
+        feed_id: int,
+        *,
+        name: str | None = None,
+        topic: str | None = None,
+        category_id: int | None = _UNSET,
+        position: int | None = None,
+    ) -> FeedResponse:
+        payload: dict[str, Any] = {}
+        if name is not None:
+            payload["name"] = name
+        if topic is not None:
+            payload["topic"] = topic
+        if category_id is not _UNSET:
+            payload["category_id"] = category_id
+        if position is not None:
+            payload["position"] = position
+        r = await self._http.patch(f"/api/v1/feeds/{feed_id}", json=payload)
+        return FeedResponse.model_validate(r.json())
+
+    async def delete_feed(self, feed_id: int) -> None:
+        await self._http.delete(f"/api/v1/feeds/{feed_id}")
+
+    async def subscribe_feed(self, feed_id: int) -> None:
+        await self._http.put(f"/api/v1/feeds/{feed_id}/subscribers")
+
+    async def unsubscribe_feed(self, feed_id: int) -> None:
+        await self._http.delete(f"/api/v1/feeds/{feed_id}/subscribers")
+
+    # --- Rooms ---
+
+    async def get_room(self, room_id: int) -> RoomResponse:
+        r = await self._http.get(f"/api/v1/rooms/{room_id}")
+        return RoomResponse.model_validate(r.json())
+
+    async def create_room(
+        self,
+        name: str,
+        type: RoomType = RoomType.voice,
+        *,
+        category_id: int | None = None,
+        permission_overrides: list[dict] | None = None,
+    ) -> RoomResponse:
+        payload: dict[str, Any] = {"name": name, "type": type}
+        if category_id is not None:
+            payload["category_id"] = category_id
+        if permission_overrides is not None:
+            payload["permission_overrides"] = permission_overrides
+        r = await self._http.post("/api/v1/rooms", json=payload)
+        return RoomResponse.model_validate(r.json())
+
+    async def update_room(
+        self,
+        room_id: int,
+        *,
+        name: str | None = None,
+        category_id: int | None = _UNSET,
+        position: int | None = None,
+    ) -> RoomResponse:
+        payload: dict[str, Any] = {}
+        if name is not None:
+            payload["name"] = name
+        if category_id is not _UNSET:
+            payload["category_id"] = category_id
+        if position is not None:
+            payload["position"] = position
+        r = await self._http.patch(f"/api/v1/rooms/{room_id}", json=payload)
+        return RoomResponse.model_validate(r.json())
+
+    async def delete_room(self, room_id: int) -> None:
+        await self._http.delete(f"/api/v1/rooms/{room_id}")
+
+    # --- Categories ---
+
+    async def list_categories(self) -> CategoryListResponse:
+        r = await self._http.get("/api/v1/categories")
+        return CategoryListResponse.model_validate(r.json())
+
+    async def get_category(self, category_id: int) -> CategoryResponse:
+        r = await self._http.get(f"/api/v1/categories/{category_id}")
+        return CategoryResponse.model_validate(r.json())
+
+    async def create_category(self, name: str, position: int = 0) -> CategoryResponse:
+        r = await self._http.post(
+            "/api/v1/categories", json={"name": name, "position": position}
+        )
+        return CategoryResponse.model_validate(r.json())
+
+    async def update_category(
+        self, category_id: int, *, name: str | None = None, position: int | None = None
+    ) -> CategoryResponse:
+        payload: dict[str, Any] = {}
+        if name is not None:
+            payload["name"] = name
+        if position is not None:
+            payload["position"] = position
+        r = await self._http.patch(f"/api/v1/categories/{category_id}", json=payload)
+        return CategoryResponse.model_validate(r.json())
+
+    async def delete_category(self, category_id: int) -> None:
+        await self._http.delete(f"/api/v1/categories/{category_id}")
+
+    # --- Threads ---
+
+    async def get_thread(self, thread_id: int) -> ThreadResponse:
+        r = await self._http.get(f"/api/v1/threads/{thread_id}")
+        return ThreadResponse.model_validate(r.json())
+
+    async def list_threads(self, feed_id: int) -> ThreadListResponse:
+        r = await self._http.get(f"/api/v1/feeds/{feed_id}/threads")
+        return ThreadListResponse.model_validate(r.json())
+
+    async def create_thread(
+        self, feed_id: int, parent_msg_id: int, name: str
+    ) -> ThreadResponse:
+        r = await self._http.post(
+            f"/api/v1/feeds/{feed_id}/threads",
+            json={"parent_msg_id": parent_msg_id, "name": name},
+        )
+        return ThreadResponse.model_validate(r.json())
+
+    async def update_thread(
+        self,
+        thread_id: int,
+        *,
+        name: str | None = None,
+        archived: bool | None = None,
+        locked: bool | None = None,
+    ) -> ThreadResponse:
+        payload: dict[str, Any] = {}
+        if name is not None:
+            payload["name"] = name
+        if archived is not None:
+            payload["archived"] = archived
+        if locked is not None:
+            payload["locked"] = locked
+        r = await self._http.patch(f"/api/v1/threads/{thread_id}", json=payload)
+        return ThreadResponse.model_validate(r.json())
+
+    async def delete_thread(self, thread_id: int) -> None:
+        await self._http.delete(f"/api/v1/threads/{thread_id}")
+
+    async def subscribe_thread(self, feed_id: int, thread_id: int) -> None:
+        await self._http.put(f"/api/v1/feeds/{feed_id}/threads/{thread_id}/subscribers")
+
+    async def unsubscribe_thread(self, feed_id: int, thread_id: int) -> None:
+        await self._http.delete(f"/api/v1/feeds/{feed_id}/threads/{thread_id}/subscribers")