chzzk-python 0.1.0__py3-none-any.whl

chzzk/api/session.py

@@ -0,0 +1,389 @@
+"""Session API service for Chzzk."""
+
+from __future__ import annotations
+
+from chzzk.api.base import AsyncBaseService, BaseService
+from chzzk.http import (
+    SESSIONS_AUTH_CLIENT_URL,
+    SESSIONS_AUTH_URL,
+    SESSIONS_CLIENT_URL,
+    SESSIONS_SUBSCRIBE_CHAT_URL,
+    SESSIONS_SUBSCRIBE_DONATION_URL,
+    SESSIONS_SUBSCRIBE_SUBSCRIPTION_URL,
+    SESSIONS_UNSUBSCRIBE_CHAT_URL,
+    SESSIONS_UNSUBSCRIBE_DONATION_URL,
+    SESSIONS_UNSUBSCRIBE_SUBSCRIPTION_URL,
+    SESSIONS_URL,
+)
+from chzzk.models.session import SessionAuthResponse, SessionInfo, SessionListResponse
+
+
+class SessionService(BaseService):
+    """Synchronous Session API service.
+
+    Provides access to session-related API endpoints for WebSocket event subscriptions.
+    """
+
+    def create_session(self) -> SessionAuthResponse:
+        """Create a session for WebSocket connection (user authentication).
+
+        Creates a session URL using access token authentication.
+        Maximum 3 connections per user.
+
+        Returns:
+            SessionAuthResponse containing the WebSocket connection URL.
+
+        Raises:
+            InvalidTokenError: If the access token is invalid.
+            ChzzkAPIError: If the API request fails.
+        """
+        data = self._http.get(SESSIONS_AUTH_URL, headers=self._get_token_headers())
+        return SessionAuthResponse.model_validate(data)
+
+    def create_client_session(self) -> SessionAuthResponse:
+        """Create a session for WebSocket connection (client authentication).
+
+        Creates a session URL using client credentials authentication.
+        Maximum 10 connections per client.
+
+        Returns:
+            SessionAuthResponse containing the WebSocket connection URL.
+
+        Raises:
+            InvalidClientError: If the client credentials are invalid.
+            ChzzkAPIError: If the API request fails.
+        """
+        data = self._http.get(SESSIONS_AUTH_CLIENT_URL, headers=self._get_client_headers())
+        return SessionAuthResponse.model_validate(data)
+
+    def get_sessions(self, *, size: int = 20, page: int = 0) -> list[SessionInfo]:
+        """Get session list (user authentication).
+
+        Retrieves sessions created with access token authentication.
+
+        Args:
+            size: Number of sessions to retrieve (1-50). Default is 20.
+            page: Page number to retrieve (0-indexed). Default is 0.
+
+        Returns:
+            List of SessionInfo objects.
+
+        Raises:
+            InvalidTokenError: If the access token is invalid.
+            ChzzkAPIError: If the API request fails.
+        """
+        params = {"size": size, "page": page}
+        data = self._http.get(SESSIONS_URL, params=params, headers=self._get_token_headers())
+        response = SessionListResponse.model_validate(data)
+        return response.data
+
+    def get_client_sessions(self, *, size: int = 20, page: int = 0) -> list[SessionInfo]:
+        """Get session list (client authentication).
+
+        Retrieves sessions created with client credentials authentication.
+
+        Args:
+            size: Number of sessions to retrieve (1-50). Default is 20.
+            page: Page number to retrieve (0-indexed). Default is 0.
+
+        Returns:
+            List of SessionInfo objects.
+
+        Raises:
+            InvalidClientError: If the client credentials are invalid.
+            ChzzkAPIError: If the API request fails.
+        """
+        params = {"size": size, "page": page}
+        headers = self._get_client_headers()
+        data = self._http.get(SESSIONS_CLIENT_URL, params=params, headers=headers)
+        response = SessionListResponse.model_validate(data)
+        return response.data
+
+    def subscribe_chat(self, session_key: str) -> None:
+        """Subscribe to chat events for a session.
+
+        Maximum 30 events (chat, donation, subscription) per session.
+
+        Args:
+            session_key: The session key to subscribe events to.
+
+        Raises:
+            InvalidTokenError: If the access token is invalid.
+            ChzzkAPIError: If the API request fails.
+        """
+        self._http.post(
+            SESSIONS_SUBSCRIBE_CHAT_URL,
+            params={"sessionKey": session_key},
+            headers=self._get_token_headers(),
+        )
+
+    def subscribe_donation(self, session_key: str) -> None:
+        """Subscribe to donation events for a session.
+
+        Maximum 30 events (chat, donation, subscription) per session.
+
+        Args:
+            session_key: The session key to subscribe events to.
+
+        Raises:
+            InvalidTokenError: If the access token is invalid.
+            ChzzkAPIError: If the API request fails.
+        """
+        self._http.post(
+            SESSIONS_SUBSCRIBE_DONATION_URL,
+            params={"sessionKey": session_key},
+            headers=self._get_token_headers(),
+        )
+
+    def subscribe_subscription(self, session_key: str) -> None:
+        """Subscribe to subscription events for a session.
+
+        Maximum 30 events (chat, donation, subscription) per session.
+
+        Args:
+            session_key: The session key to subscribe events to.
+
+        Raises:
+            InvalidTokenError: If the access token is invalid.
+            ChzzkAPIError: If the API request fails.
+        """
+        self._http.post(
+            SESSIONS_SUBSCRIBE_SUBSCRIPTION_URL,
+            params={"sessionKey": session_key},
+            headers=self._get_token_headers(),
+        )
+
+    def unsubscribe_chat(self, session_key: str) -> None:
+        """Unsubscribe from chat events for a session.
+
+        Args:
+            session_key: The session key to unsubscribe events from.
+
+        Raises:
+            InvalidTokenError: If the access token is invalid.
+            ChzzkAPIError: If the API request fails.
+        """
+        self._http.post(
+            SESSIONS_UNSUBSCRIBE_CHAT_URL,
+            params={"sessionKey": session_key},
+            headers=self._get_token_headers(),
+        )
+
+    def unsubscribe_donation(self, session_key: str) -> None:
+        """Unsubscribe from donation events for a session.
+
+        Args:
+            session_key: The session key to unsubscribe events from.
+
+        Raises:
+            InvalidTokenError: If the access token is invalid.
+            ChzzkAPIError: If the API request fails.
+        """
+        self._http.post(
+            SESSIONS_UNSUBSCRIBE_DONATION_URL,
+            params={"sessionKey": session_key},
+            headers=self._get_token_headers(),
+        )
+
+    def unsubscribe_subscription(self, session_key: str) -> None:
+        """Unsubscribe from subscription events for a session.
+
+        Args:
+            session_key: The session key to unsubscribe events from.
+
+        Raises:
+            InvalidTokenError: If the access token is invalid.
+            ChzzkAPIError: If the API request fails.
+        """
+        self._http.post(
+            SESSIONS_UNSUBSCRIBE_SUBSCRIPTION_URL,
+            params={"sessionKey": session_key},
+            headers=self._get_token_headers(),
+        )
+
+
+class AsyncSessionService(AsyncBaseService):
+    """Asynchronous Session API service.
+
+    Provides access to session-related API endpoints for WebSocket event subscriptions.
+    """
+
+    async def create_session(self) -> SessionAuthResponse:
+        """Create a session for WebSocket connection (user authentication).
+
+        Creates a session URL using access token authentication.
+        Maximum 3 connections per user.
+
+        Returns:
+            SessionAuthResponse containing the WebSocket connection URL.
+
+        Raises:
+            InvalidTokenError: If the access token is invalid.
+            ChzzkAPIError: If the API request fails.
+        """
+        data = await self._http.get(SESSIONS_AUTH_URL, headers=await self._get_token_headers())
+        return SessionAuthResponse.model_validate(data)
+
+    async def create_client_session(self) -> SessionAuthResponse:
+        """Create a session for WebSocket connection (client authentication).
+
+        Creates a session URL using client credentials authentication.
+        Maximum 10 connections per client.
+
+        Returns:
+            SessionAuthResponse containing the WebSocket connection URL.
+
+        Raises:
+            InvalidClientError: If the client credentials are invalid.
+            ChzzkAPIError: If the API request fails.
+        """
+        data = await self._http.get(SESSIONS_AUTH_CLIENT_URL, headers=self._get_client_headers())
+        return SessionAuthResponse.model_validate(data)
+
+    async def get_sessions(self, *, size: int = 20, page: int = 0) -> list[SessionInfo]:
+        """Get session list (user authentication).
+
+        Retrieves sessions created with access token authentication.
+
+        Args:
+            size: Number of sessions to retrieve (1-50). Default is 20.
+            page: Page number to retrieve (0-indexed). Default is 0.
+
+        Returns:
+            List of SessionInfo objects.
+
+        Raises:
+            InvalidTokenError: If the access token is invalid.
+            ChzzkAPIError: If the API request fails.
+        """
+        params = {"size": size, "page": page}
+        data = await self._http.get(
+            SESSIONS_URL, params=params, headers=await self._get_token_headers()
+        )
+        response = SessionListResponse.model_validate(data)
+        return response.data
+
+    async def get_client_sessions(self, *, size: int = 20, page: int = 0) -> list[SessionInfo]:
+        """Get session list (client authentication).
+
+        Retrieves sessions created with client credentials authentication.
+
+        Args:
+            size: Number of sessions to retrieve (1-50). Default is 20.
+            page: Page number to retrieve (0-indexed). Default is 0.
+
+        Returns:
+            List of SessionInfo objects.
+
+        Raises:
+            InvalidClientError: If the client credentials are invalid.
+            ChzzkAPIError: If the API request fails.
+        """
+        params = {"size": size, "page": page}
+        data = await self._http.get(
+            SESSIONS_CLIENT_URL, params=params, headers=self._get_client_headers()
+        )
+        response = SessionListResponse.model_validate(data)
+        return response.data
+
+    async def subscribe_chat(self, session_key: str) -> None:
+        """Subscribe to chat events for a session.
+
+        Maximum 30 events (chat, donation, subscription) per session.
+
+        Args:
+            session_key: The session key to subscribe events to.
+
+        Raises:
+            InvalidTokenError: If the access token is invalid.
+            ChzzkAPIError: If the API request fails.
+        """
+        await self._http.post(
+            SESSIONS_SUBSCRIBE_CHAT_URL,
+            params={"sessionKey": session_key},
+            headers=await self._get_token_headers(),
+        )
+
+    async def subscribe_donation(self, session_key: str) -> None:
+        """Subscribe to donation events for a session.
+
+        Maximum 30 events (chat, donation, subscription) per session.
+
+        Args:
+            session_key: The session key to subscribe events to.
+
+        Raises:
+            InvalidTokenError: If the access token is invalid.
+            ChzzkAPIError: If the API request fails.
+        """
+        await self._http.post(
+            SESSIONS_SUBSCRIBE_DONATION_URL,
+            params={"sessionKey": session_key},
+            headers=await self._get_token_headers(),
+        )
+
+    async def subscribe_subscription(self, session_key: str) -> None:
+        """Subscribe to subscription events for a session.
+
+        Maximum 30 events (chat, donation, subscription) per session.
+
+        Args:
+            session_key: The session key to subscribe events to.
+
+        Raises:
+            InvalidTokenError: If the access token is invalid.
+            ChzzkAPIError: If the API request fails.
+        """
+        await self._http.post(
+            SESSIONS_SUBSCRIBE_SUBSCRIPTION_URL,
+            params={"sessionKey": session_key},
+            headers=await self._get_token_headers(),
+        )
+
+    async def unsubscribe_chat(self, session_key: str) -> None:
+        """Unsubscribe from chat events for a session.
+
+        Args:
+            session_key: The session key to unsubscribe events from.
+
+        Raises:
+            InvalidTokenError: If the access token is invalid.
+            ChzzkAPIError: If the API request fails.
+        """
+        await self._http.post(
+            SESSIONS_UNSUBSCRIBE_CHAT_URL,
+            params={"sessionKey": session_key},
+            headers=await self._get_token_headers(),
+        )
+
+    async def unsubscribe_donation(self, session_key: str) -> None:
+        """Unsubscribe from donation events for a session.
+
+        Args:
+            session_key: The session key to unsubscribe events from.
+
+        Raises:
+            InvalidTokenError: If the access token is invalid.
+            ChzzkAPIError: If the API request fails.
+        """
+        await self._http.post(
+            SESSIONS_UNSUBSCRIBE_DONATION_URL,
+            params={"sessionKey": session_key},
+            headers=await self._get_token_headers(),
+        )
+
+    async def unsubscribe_subscription(self, session_key: str) -> None:
+        """Unsubscribe from subscription events for a session.
+
+        Args:
+            session_key: The session key to unsubscribe events from.
+
+        Raises:
+            InvalidTokenError: If the access token is invalid.
+            ChzzkAPIError: If the API request fails.
+        """
+        await self._http.post(
+            SESSIONS_UNSUBSCRIBE_SUBSCRIPTION_URL,
+            params={"sessionKey": session_key},
+            headers=await self._get_token_headers(),
+        )

chzzk/api/user.py

@@ -0,0 +1,47 @@
+"""User API service for Chzzk."""
+
+from __future__ import annotations
+
+from chzzk.api.base import AsyncBaseService, BaseService
+from chzzk.http import USER_ME_URL
+from chzzk.models.user import UserInfo
+
+
+class UserService(BaseService):
+    """Synchronous User API service.
+
+    Provides access to user-related API endpoints.
+    """
+
+    def get_me(self) -> UserInfo:
+        """Get the current authenticated user's information.
+
+        Returns:
+            UserInfo containing the user's channel ID and name.
+
+        Raises:
+            InvalidTokenError: If the access token is invalid.
+            ChzzkAPIError: If the API request fails.
+        """
+        data = self._http.get(USER_ME_URL, headers=self._get_token_headers())
+        return UserInfo.model_validate(data)
+
+
+class AsyncUserService(AsyncBaseService):
+    """Asynchronous User API service.
+
+    Provides access to user-related API endpoints.
+    """
+
+    async def get_me(self) -> UserInfo:
+        """Get the current authenticated user's information.
+
+        Returns:
+            UserInfo containing the user's channel ID and name.
+
+        Raises:
+            InvalidTokenError: If the access token is invalid.
+            ChzzkAPIError: If the API request fails.
+        """
+        data = await self._http.get(USER_ME_URL, headers=await self._get_token_headers())
+        return UserInfo.model_validate(data)

chzzk/auth/__init__.py

@@ -0,0 +1,34 @@
+"""Authentication module for Chzzk SDK."""
+
+from chzzk.auth.models import (
+    AuthorizationCodeRequest,
+    GrantType,
+    RefreshTokenRequest,
+    RevokeTokenRequest,
+    Token,
+    TokenResponse,
+    TokenTypeHint,
+)
+from chzzk.auth.oauth import (
+    AsyncChzzkOAuth,
+    ChzzkOAuth,
+    InMemoryTokenStorage,
+    TokenStorage,
+)
+from chzzk.auth.token import CallbackTokenStorage, FileTokenStorage
+
+__all__ = [
+    "AsyncChzzkOAuth",
+    "AuthorizationCodeRequest",
+    "CallbackTokenStorage",
+    "ChzzkOAuth",
+    "FileTokenStorage",
+    "GrantType",
+    "InMemoryTokenStorage",
+    "RefreshTokenRequest",
+    "RevokeTokenRequest",
+    "Token",
+    "TokenResponse",
+    "TokenStorage",
+    "TokenTypeHint",
+]

chzzk/auth/models.py

@@ -0,0 +1,115 @@
+"""Pydantic models for Chzzk OAuth authentication."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+from enum import StrEnum
+from typing import Self
+
+from pydantic import BaseModel, Field, computed_field
+
+
+class GrantType(StrEnum):
+    """OAuth grant type enumeration."""
+
+    AUTHORIZATION_CODE = "authorization_code"
+    REFRESH_TOKEN = "refresh_token"
+
+
+class TokenTypeHint(StrEnum):
+    """Token type hint for revocation."""
+
+    ACCESS_TOKEN = "access_token"
+    REFRESH_TOKEN = "refresh_token"
+
+
+class TokenResponse(BaseModel):
+    """Response model for token endpoint (camelCase from API)."""
+
+    access_token: str = Field(alias="accessToken")
+    refresh_token: str = Field(alias="refreshToken")
+    token_type: str = Field(alias="tokenType")
+    expires_in: int = Field(alias="expiresIn")
+    scope: str | None = None
+
+    model_config = {"populate_by_name": True}
+
+
+class Token(BaseModel):
+    """Token model with expiration tracking.
+
+    This model stores the token data along with the timestamp when it was issued,
+    allowing for accurate expiration checking.
+    """
+
+    access_token: str
+    refresh_token: str
+    token_type: str = "Bearer"
+    expires_in: int
+    scope: str | None = None
+    issued_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+
+    model_config = {"populate_by_name": True}
+
+    @computed_field
+    @property
+    def expires_at(self) -> datetime:
+        """Calculate the expiration time of the access token."""
+        return self.issued_at + timedelta(seconds=self.expires_in)
+
+    @property
+    def is_expired(self) -> bool:
+        """Check if the access token is expired.
+
+        Returns True if the token has expired or will expire within 60 seconds.
+        """
+        buffer = timedelta(seconds=60)
+        return datetime.now(UTC) >= (self.expires_at - buffer)
+
+    @classmethod
+    def from_response(cls, response: TokenResponse) -> Self:
+        """Create a Token instance from a TokenResponse."""
+        return cls(
+            access_token=response.access_token,
+            refresh_token=response.refresh_token,
+            token_type=response.token_type,
+            expires_in=response.expires_in,
+            scope=response.scope,
+        )
+
+
+class AuthorizationCodeRequest(BaseModel):
+    """Request model for authorization code token exchange."""
+
+    grant_type: str = Field(default=GrantType.AUTHORIZATION_CODE, serialization_alias="grantType")
+    client_id: str = Field(serialization_alias="clientId")
+    client_secret: str = Field(serialization_alias="clientSecret")
+    code: str
+    state: str
+
+    model_config = {"populate_by_name": True}
+
+
+class RefreshTokenRequest(BaseModel):
+    """Request model for token refresh."""
+
+    grant_type: str = Field(default=GrantType.REFRESH_TOKEN, serialization_alias="grantType")
+    client_id: str = Field(serialization_alias="clientId")
+    client_secret: str = Field(serialization_alias="clientSecret")
+    refresh_token: str = Field(serialization_alias="refreshToken")
+
+    model_config = {"populate_by_name": True}
+
+
+class RevokeTokenRequest(BaseModel):
+    """Request model for token revocation."""
+
+    client_id: str = Field(serialization_alias="clientId")
+    client_secret: str = Field(serialization_alias="clientSecret")
+    token: str
+    token_type_hint: str = Field(
+        default=TokenTypeHint.ACCESS_TOKEN,
+        serialization_alias="tokenTypeHint",
+    )
+
+    model_config = {"populate_by_name": True}