nolag 2.0.0__py3-none-any.whl

nolag/__init__.py

@@ -0,0 +1,84 @@
+"""
+NoLag Python SDK
+Real-time messaging for Python applications
+"""
+
+from .client import NoLag
+from .types import (
+    NoLagOptions,
+    ConnectionStatus,
+    ActorType,
+    QoS,
+    SubscribeOptions,
+    EmitOptions,
+    MessageMeta,
+    ActorPresence,
+    LobbyPresenceEvent,
+    LobbyPresenceState,
+    LobbyPresenceHandler,
+)
+from .api import NoLagApi, NoLagApiError
+from .api_types import (
+    NoLagApiOptions,
+    ListOptions,
+    PaginatedResult,
+    ApiError,
+    App,
+    AppCreate,
+    AppUpdate,
+    Room,
+    RoomCreate,
+    RoomUpdate,
+    Actor,
+    ActorWithToken,
+    ActorCreate,
+    ActorUpdate,
+)
+
+# WebRTC support (optional, requires aiortc)
+try:
+    from .webrtc import WebRTCManager, WebRTCOptions, is_webrtc_available
+    _WEBRTC_AVAILABLE = True
+except ImportError:
+    _WEBRTC_AVAILABLE = False
+    WebRTCManager = None
+    WebRTCOptions = None
+    is_webrtc_available = lambda: False
+
+__version__ = "2.0.0"
+__all__ = [
+    # WebSocket Client
+    "NoLag",
+    "NoLagOptions",
+    "ConnectionStatus",
+    "ActorType",
+    "QoS",
+    "SubscribeOptions",
+    "EmitOptions",
+    "MessageMeta",
+    "ActorPresence",
+    "LobbyPresenceEvent",
+    "LobbyPresenceState",
+    "LobbyPresenceHandler",
+    # REST API Client
+    "NoLagApi",
+    "NoLagApiError",
+    "NoLagApiOptions",
+    "ListOptions",
+    "PaginatedResult",
+    "ApiError",
+    "App",
+    "AppCreate",
+    "AppUpdate",
+    "Room",
+    "RoomCreate",
+    "RoomUpdate",
+    "Actor",
+    "ActorWithToken",
+    "ActorCreate",
+    "ActorUpdate",
+    # WebRTC (optional)
+    "WebRTCManager",
+    "WebRTCOptions",
+    "is_webrtc_available",
+]

nolag/api.py

@@ -0,0 +1,268 @@
+"""
+NoLag REST API Client
+
+Provides management operations for NoLag resources via REST API.
+API keys are scoped to a specific project, so no organization or project IDs needed.
+
+Use this for managing apps, rooms, and actors within your project.
+For real-time messaging, use the main NoLag WebSocket client.
+"""
+
+import aiohttp
+from typing import Any, Optional
+from urllib.parse import urljoin, urlencode
+
+from .api_types import (
+    NoLagApiOptions,
+    ListOptions,
+    PaginatedResult,
+    ApiError,
+    App,
+    AppCreate,
+    AppUpdate,
+    Room,
+    RoomCreate,
+    RoomUpdate,
+    Actor,
+    ActorWithToken,
+    ActorCreate,
+    ActorUpdate,
+)
+
+DEFAULT_BASE_URL = "https://api.nolag.app/v1"
+DEFAULT_TIMEOUT = 30.0
+
+
+class NoLagApiError(Exception):
+    """NoLag API Error"""
+
+    def __init__(self, message: str, status_code: int, details: Optional[ApiError] = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.details = details or ApiError(status_code=status_code, message=message)
+
+
+class AppsApi:
+    """Apps API - Manage apps in your project"""
+
+    def __init__(self, api: "NoLagApi"):
+        self._api = api
+
+    async def list(self, options: Optional[ListOptions] = None) -> PaginatedResult:
+        """List all apps in the project"""
+        params = options.to_params() if options else {}
+        data = await self._api._request("GET", "/apps", params=params)
+        return PaginatedResult(
+            data=[App.from_dict(item) for item in data.get("data", [])],
+            total=data.get("total", 0),
+            page=data.get("page", 1),
+            limit=data.get("limit", 10),
+            total_pages=data.get("totalPages", 1),
+        )
+
+    async def get(self, app_id: str) -> App:
+        """Get an app by ID"""
+        data = await self._api._request("GET", f"/apps/{app_id}")
+        return App.from_dict(data)
+
+    async def create(self, data: AppCreate) -> App:
+        """Create a new app"""
+        result = await self._api._request("POST", "/apps", json=data.to_dict())
+        return App.from_dict(result)
+
+    async def update(self, app_id: str, data: AppUpdate) -> App:
+        """Update an app"""
+        result = await self._api._request("PATCH", f"/apps/{app_id}", json=data.to_dict())
+        return App.from_dict(result)
+
+    async def delete(self, app_id: str) -> dict:
+        """Delete an app (soft delete)"""
+        return await self._api._request("DELETE", f"/apps/{app_id}")
+
+    async def reset_to_blueprint(self, app_id: str) -> App:
+        """Reset app to its blueprint configuration"""
+        result = await self._api._request("POST", f"/apps/{app_id}/reset-to-blueprint")
+        return App.from_dict(result)
+
+
+class RoomsApi:
+    """Rooms API - Manage rooms within apps"""
+
+    def __init__(self, api: "NoLagApi"):
+        self._api = api
+
+    async def list(self, app_id: str) -> list[Room]:
+        """List all rooms in an app"""
+        data = await self._api._request("GET", f"/apps/{app_id}/rooms")
+        return [Room.from_dict(item) for item in data]
+
+    async def get(self, app_id: str, room_id: str) -> Room:
+        """Get a room by ID"""
+        data = await self._api._request("GET", f"/apps/{app_id}/rooms/{room_id}")
+        return Room.from_dict(data)
+
+    async def create(self, app_id: str, data: RoomCreate) -> Room:
+        """Create a new dynamic room"""
+        result = await self._api._request("POST", f"/apps/{app_id}/rooms", json=data.to_dict())
+        return Room.from_dict(result)
+
+    async def update(self, app_id: str, room_id: str, data: RoomUpdate) -> Room:
+        """Update a room"""
+        result = await self._api._request(
+            "PATCH", f"/apps/{app_id}/rooms/{room_id}", json=data.to_dict()
+        )
+        return Room.from_dict(result)
+
+    async def delete(self, app_id: str, room_id: str) -> None:
+        """Delete a dynamic room (static rooms cannot be deleted)"""
+        await self._api._request("DELETE", f"/apps/{app_id}/rooms/{room_id}")
+
+
+class ActorsApi:
+    """Actors API - Manage actors in your project"""
+
+    def __init__(self, api: "NoLagApi"):
+        self._api = api
+
+    async def list(self) -> list[Actor]:
+        """List all actors in the project"""
+        data = await self._api._request("GET", "/actors")
+        return [Actor.from_dict(item) for item in data]
+
+    async def get(self, actor_id: str) -> Actor:
+        """Get an actor by ID"""
+        data = await self._api._request("GET", f"/actors/{actor_id}")
+        return Actor.from_dict(data)
+
+    async def create(self, data: ActorCreate) -> ActorWithToken:
+        """
+        Create a new actor
+
+        IMPORTANT: The access token is only returned once! Save it immediately.
+        """
+        result = await self._api._request("POST", "/actors", json=data.to_dict())
+        return ActorWithToken.from_dict(result)
+
+    async def update(self, actor_id: str, data: ActorUpdate) -> Actor:
+        """Update an actor"""
+        result = await self._api._request("PATCH", f"/actors/{actor_id}", json=data.to_dict())
+        return Actor.from_dict(result)
+
+    async def delete(self, actor_id: str) -> None:
+        """Delete an actor"""
+        await self._api._request("DELETE", f"/actors/{actor_id}")
+
+
+class NoLagApi:
+    """
+    NoLag REST API Client
+
+    API keys are project-scoped, so you don't need to pass organization or project IDs.
+
+    Example:
+        ```python
+        from nolag import NoLagApi, AppCreate, ActorCreate
+
+        async with NoLagApi('nlg_live_xxx.secret') as api:
+            # List apps in your project
+            apps = await api.apps.list()
+
+            # Create a room
+            room = await api.rooms.create(app_id, RoomCreate(
+                name='chat-room',
+                description='General chat'
+            ))
+
+            # Create an actor and get the access token
+            actor = await api.actors.create(ActorCreate(
+                name='web-client',
+                actor_type='device'
+            ))
+            print('Save this token:', actor.access_token)
+        ```
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        options: Optional[NoLagApiOptions] = None,
+    ):
+        self._api_key = api_key
+        self._options = options or NoLagApiOptions()
+        self._base_url = self._options.base_url.rstrip("/")
+        self._timeout = aiohttp.ClientTimeout(total=self._options.timeout)
+        self._session: Optional[aiohttp.ClientSession] = None
+
+        # Initialize sub-APIs
+        self.apps = AppsApi(self)
+        self.rooms = RoomsApi(self)
+        self.actors = ActorsApi(self)
+
+    async def __aenter__(self) -> "NoLagApi":
+        """Async context manager entry"""
+        self._session = aiohttp.ClientSession(timeout=self._timeout)
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Async context manager exit"""
+        if self._session:
+            await self._session.close()
+            self._session = None
+
+    async def close(self) -> None:
+        """Close the API client session"""
+        if self._session:
+            await self._session.close()
+            self._session = None
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        params: Optional[dict] = None,
+        json: Optional[dict] = None,
+    ) -> Any:
+        """Make an authenticated request to the NoLag API"""
+        if not self._session:
+            self._session = aiohttp.ClientSession(timeout=self._timeout)
+
+        url = f"{self._base_url}{path}"
+        if params:
+            url = f"{url}?{urlencode(params)}"
+
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Content-Type": "application/json",
+            **self._options.headers,
+        }
+
+        try:
+            async with self._session.request(
+                method, url, headers=headers, json=json
+            ) as response:
+                if not response.ok:
+                    try:
+                        error_data = await response.json()
+                        raise NoLagApiError(
+                            error_data.get("message", "Request failed"),
+                            response.status,
+                            ApiError(
+                                status_code=response.status,
+                                message=error_data.get("message", "Request failed"),
+                                error=error_data.get("error"),
+                            ),
+                        )
+                    except aiohttp.ContentTypeError:
+                        raise NoLagApiError(
+                            response.reason or "Request failed",
+                            response.status,
+                        )
+
+                # Handle 204 No Content
+                if response.status == 204:
+                    return None
+
+                return await response.json()
+
+        except aiohttp.ClientError as e:
+            raise NoLagApiError(str(e), 0, ApiError(status_code=0, message=str(e)))

nolag/api_types.py

@@ -0,0 +1,330 @@
+"""
+NoLag REST API Types
+
+These types are for the project-scoped API.
+API keys are scoped to a specific project, so organization and project IDs
+are implicit and not needed in API calls.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Optional, Literal
+from datetime import datetime
+
+
+# ============ Common Types ============
+
+@dataclass
+class PaginatedResult:
+    """Paginated API response"""
+    data: list
+    total: int
+    page: int
+    limit: int
+    total_pages: int
+
+
+@dataclass
+class ApiError:
+    """API error response"""
+    status_code: int
+    message: str
+    error: Optional[str] = None
+
+
+# ============ App Types ============
+
+@dataclass
+class App:
+    """App resource"""
+    app_id: str
+    project_id: str
+    name: str
+    slug: Optional[str] = None
+    description: Optional[str] = None
+    blueprint_id: Optional[str] = None
+    config: Optional[dict[str, Any]] = None
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+    deleted_at: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "App":
+        return cls(
+            app_id=data.get("appId", ""),
+            project_id=data.get("projectId", ""),
+            name=data.get("name", ""),
+            slug=data.get("slug"),
+            description=data.get("description"),
+            blueprint_id=data.get("blueprintId"),
+            config=data.get("config"),
+            created_at=data.get("createdAt"),
+            updated_at=data.get("updatedAt"),
+            deleted_at=data.get("deletedAt"),
+        )
+
+
+@dataclass
+class AppCreate:
+    """Create app request"""
+    name: str
+    slug: Optional[str] = None
+    description: Optional[str] = None
+    blueprint_id: Optional[str] = None
+    config: Optional[dict[str, Any]] = None
+
+    def to_dict(self) -> dict:
+        result = {"name": self.name}
+        if self.slug:
+            result["slug"] = self.slug
+        if self.description:
+            result["description"] = self.description
+        if self.blueprint_id:
+            result["blueprintId"] = self.blueprint_id
+        if self.config:
+            result["config"] = self.config
+        return result
+
+
+@dataclass
+class AppUpdate:
+    """Update app request"""
+    name: Optional[str] = None
+    slug: Optional[str] = None
+    description: Optional[str] = None
+    config: Optional[dict[str, Any]] = None
+
+    def to_dict(self) -> dict:
+        result = {}
+        if self.name is not None:
+            result["name"] = self.name
+        if self.slug is not None:
+            result["slug"] = self.slug
+        if self.description is not None:
+            result["description"] = self.description
+        if self.config is not None:
+            result["config"] = self.config
+        return result
+
+
+# ============ Room Types ============
+
+RoomType = Literal["static", "dynamic"]
+
+
+@dataclass
+class Room:
+    """Room resource"""
+    room_id: str
+    app_id: str
+    name: str
+    slug: str
+    description: Optional[str] = None
+    room_type: Optional[RoomType] = None
+    is_enabled: bool = True
+    topics: Optional[list[str]] = None
+    config: Optional[dict[str, Any]] = None
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Room":
+        return cls(
+            room_id=data.get("roomId", ""),
+            app_id=data.get("appId", ""),
+            name=data.get("name", ""),
+            slug=data.get("slug", ""),
+            description=data.get("description"),
+            room_type=data.get("roomType"),
+            is_enabled=data.get("isEnabled", True),
+            topics=data.get("topics"),
+            config=data.get("config"),
+            created_at=data.get("createdAt"),
+            updated_at=data.get("updatedAt"),
+        )
+
+
+@dataclass
+class RoomCreate:
+    """Create room request"""
+    name: str
+    slug: Optional[str] = None
+    description: Optional[str] = None
+    topics: Optional[list[str]] = None
+    config: Optional[dict[str, Any]] = None
+
+    def to_dict(self) -> dict:
+        result = {"name": self.name}
+        if self.slug:
+            result["slug"] = self.slug
+        if self.description:
+            result["description"] = self.description
+        if self.topics:
+            result["topics"] = self.topics
+        if self.config:
+            result["config"] = self.config
+        return result
+
+
+@dataclass
+class RoomUpdate:
+    """Update room request"""
+    name: Optional[str] = None
+    description: Optional[str] = None
+    is_enabled: Optional[bool] = None
+    topics: Optional[list[str]] = None
+    config: Optional[dict[str, Any]] = None
+
+    def to_dict(self) -> dict:
+        result = {}
+        if self.name is not None:
+            result["name"] = self.name
+        if self.description is not None:
+            result["description"] = self.description
+        if self.is_enabled is not None:
+            result["isEnabled"] = self.is_enabled
+        if self.topics is not None:
+            result["topics"] = self.topics
+        if self.config is not None:
+            result["config"] = self.config
+        return result
+
+
+# ============ Actor Types ============
+
+ActorTokenType = Literal["device", "user", "server"]
+
+
+@dataclass
+class Actor:
+    """Actor resource"""
+    actor_token_id: str
+    project_id: str
+    name: str
+    actor_type: ActorTokenType
+    description: Optional[str] = None
+    external_id: Optional[str] = None
+    metadata: Optional[dict[str, Any]] = None
+    is_active: bool = True
+    last_connected_at: Optional[str] = None
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Actor":
+        return cls(
+            actor_token_id=data.get("actorTokenId", ""),
+            project_id=data.get("projectId", ""),
+            name=data.get("name", ""),
+            actor_type=data.get("actorType", "device"),
+            description=data.get("description"),
+            external_id=data.get("externalId"),
+            metadata=data.get("metadata"),
+            is_active=data.get("isActive", True),
+            last_connected_at=data.get("lastConnectedAt"),
+            created_at=data.get("createdAt"),
+            updated_at=data.get("updatedAt"),
+        )
+
+
+@dataclass
+class ActorWithToken(Actor):
+    """Actor with access token (returned on creation only)"""
+    access_token: str = ""
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "ActorWithToken":
+        return cls(
+            actor_token_id=data.get("actorTokenId", ""),
+            project_id=data.get("projectId", ""),
+            name=data.get("name", ""),
+            actor_type=data.get("actorType", "device"),
+            description=data.get("description"),
+            external_id=data.get("externalId"),
+            metadata=data.get("metadata"),
+            is_active=data.get("isActive", True),
+            last_connected_at=data.get("lastConnectedAt"),
+            created_at=data.get("createdAt"),
+            updated_at=data.get("updatedAt"),
+            access_token=data.get("accessToken", ""),
+        )
+
+
+@dataclass
+class ActorCreate:
+    """Create actor request"""
+    name: str
+    actor_type: ActorTokenType
+    description: Optional[str] = None
+    external_id: Optional[str] = None
+    metadata: Optional[dict[str, Any]] = None
+
+    def to_dict(self) -> dict:
+        result = {
+            "name": self.name,
+            "actorType": self.actor_type,
+        }
+        if self.description:
+            result["description"] = self.description
+        if self.external_id:
+            result["externalId"] = self.external_id
+        if self.metadata:
+            result["metadata"] = self.metadata
+        return result
+
+
+@dataclass
+class ActorUpdate:
+    """Update actor request"""
+    name: Optional[str] = None
+    description: Optional[str] = None
+    external_id: Optional[str] = None
+    metadata: Optional[dict[str, Any]] = None
+    is_active: Optional[bool] = None
+
+    def to_dict(self) -> dict:
+        result = {}
+        if self.name is not None:
+            result["name"] = self.name
+        if self.description is not None:
+            result["description"] = self.description
+        if self.external_id is not None:
+            result["externalId"] = self.external_id
+        if self.metadata is not None:
+            result["metadata"] = self.metadata
+        if self.is_active is not None:
+            result["isActive"] = self.is_active
+        return result
+
+
+# ============ API Options ============
+
+@dataclass
+class NoLagApiOptions:
+    """Options for the NoLag API client"""
+    base_url: str = "https://api.nolag.app/v1"
+    timeout: float = 30.0
+    headers: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass
+class ListOptions:
+    """Options for list endpoints"""
+    page: Optional[int] = None
+    limit: Optional[int] = None
+    sort_by: Optional[str] = None
+    sort_order: Optional[Literal["asc", "desc"]] = None
+    search: Optional[str] = None
+
+    def to_params(self) -> dict:
+        params = {}
+        if self.page is not None:
+            params["page"] = self.page
+        if self.limit is not None:
+            params["limit"] = self.limit
+        if self.sort_by is not None:
+            params["sortBy"] = self.sort_by
+        if self.sort_order is not None:
+            params["sortOrder"] = self.sort_order
+        if self.search is not None:
+            params["search"] = self.search
+        return params