chzzk-python 0.1.0__py3-none-any.whl

chzzk/http/__init__.py

@@ -0,0 +1,68 @@
+"""HTTP client and endpoint utilities for Chzzk SDK."""
+
+from chzzk.http.client import AsyncHTTPClient, HTTPClient
+from chzzk.http.endpoints import (
+    AUTH_INTERLOCK_URL,
+    AUTH_REVOKE_URL,
+    AUTH_TOKEN_URL,
+    CATEGORIES_SEARCH_URL,
+    CHANNEL_FOLLOWERS_URL,
+    CHANNEL_ROLES_URL,
+    CHANNEL_SUBSCRIBERS_URL,
+    CHANNELS_URL,
+    CHAT_NOTICE_URL,
+    CHAT_SEND_URL,
+    CHAT_SETTINGS_URL,
+    CHZZK_BASE_URL,
+    LIVE_SETTING_URL,
+    LIVES_URL,
+    OPEN_API_PREFIX,
+    OPENAPI_BASE_URL,
+    RESTRICT_CHANNELS_URL,
+    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,
+    STREAM_KEY_URL,
+    USER_ME_URL,
+)
+
+__all__ = [
+    "AUTH_INTERLOCK_URL",
+    "AUTH_REVOKE_URL",
+    "AUTH_TOKEN_URL",
+    "AsyncHTTPClient",
+    "CATEGORIES_SEARCH_URL",
+    "CHANNELS_URL",
+    "CHANNEL_FOLLOWERS_URL",
+    "CHANNEL_ROLES_URL",
+    "CHANNEL_SUBSCRIBERS_URL",
+    "CHAT_NOTICE_URL",
+    "CHAT_SEND_URL",
+    "CHAT_SETTINGS_URL",
+    "CHZZK_BASE_URL",
+    "HTTPClient",
+    "LIVES_URL",
+    "LIVE_SETTING_URL",
+    "OPEN_API_PREFIX",
+    "OPENAPI_BASE_URL",
+    "RESTRICT_CHANNELS_URL",
+    "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",
+    "STREAM_KEY_URL",
+    "USER_ME_URL",
+]

chzzk/http/client.py

@@ -0,0 +1,310 @@
+"""HTTP client wrapper for Chzzk API."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import httpx
+
+from chzzk.exceptions import (
+    ChzzkAPIError,
+    ForbiddenError,
+    InvalidClientError,
+    InvalidTokenError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+DEFAULT_TIMEOUT = 30.0
+USER_AGENT = "chzzk-python/0.1.0"
+
+
+def _extract_content(data: Any) -> Any:
+    """Extract content from Chzzk API response wrapper.
+
+    Chzzk API wraps responses in { code, message, content }.
+    This function extracts the actual content.
+    """
+    if isinstance(data, dict) and "content" in data:
+        return data["content"]
+    return data
+
+
+def _handle_error_response(response: httpx.Response) -> None:
+    """Raise appropriate exception based on response status and content."""
+    status_code = response.status_code
+
+    try:
+        data = response.json()
+        error_code = data.get("code") or data.get("error")
+        message = data.get("message") or data.get("error_description") or str(data)
+    except Exception:
+        error_code = None
+        message = response.text or f"HTTP {status_code}"
+
+    if status_code == 401:
+        if error_code == "INVALID_CLIENT":
+            raise InvalidClientError(message)
+        if error_code == "INVALID_TOKEN":
+            raise InvalidTokenError(message)
+        raise ChzzkAPIError(message, status_code=401, error_code=error_code)
+
+    if status_code == 403:
+        raise ForbiddenError(message)
+
+    if status_code == 404:
+        raise NotFoundError(message)
+
+    if status_code == 429:
+        raise RateLimitError(message)
+
+    if status_code >= 500:
+        raise ServerError(message)
+
+    raise ChzzkAPIError(message, status_code=status_code, error_code=error_code)
+
+
+class HTTPClient:
+    """Synchronous HTTP client for Chzzk API."""
+
+    def __init__(
+        self,
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        headers: Mapping[str, str] | None = None,
+    ) -> None:
+        default_headers = {
+            "User-Agent": USER_AGENT,
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }
+        if headers:
+            default_headers.update(headers)
+
+        self._client = httpx.Client(
+            timeout=timeout,
+            headers=default_headers,
+        )
+
+    def post(
+        self,
+        url: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> dict[str, Any]:
+        """Send a POST request and return JSON response."""
+        response = self._client.post(url, params=params, json=json, headers=headers)
+
+        if response.status_code >= 400:
+            _handle_error_response(response)
+
+        if response.status_code == 204 or not response.content:
+            return {}
+
+        return _extract_content(response.json())
+
+    def get(
+        self,
+        url: str,
+        *,
+        params: dict[str, Any] | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> dict[str, Any]:
+        """Send a GET request and return JSON response."""
+        response = self._client.get(url, params=params, headers=headers)
+
+        if response.status_code >= 400:
+            _handle_error_response(response)
+
+        return _extract_content(response.json())
+
+    def put(
+        self,
+        url: str,
+        *,
+        json: dict[str, Any] | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> dict[str, Any]:
+        """Send a PUT request and return JSON response."""
+        response = self._client.put(url, json=json, headers=headers)
+
+        if response.status_code >= 400:
+            _handle_error_response(response)
+
+        if response.status_code == 204 or not response.content:
+            return {}
+
+        return _extract_content(response.json())
+
+    def patch(
+        self,
+        url: str,
+        *,
+        json: dict[str, Any] | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> dict[str, Any]:
+        """Send a PATCH request and return JSON response."""
+        response = self._client.patch(url, json=json, headers=headers)
+
+        if response.status_code >= 400:
+            _handle_error_response(response)
+
+        if response.status_code == 204 or not response.content:
+            return {}
+
+        return _extract_content(response.json())
+
+    def delete(
+        self,
+        url: str,
+        *,
+        json: dict[str, Any] | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> dict[str, Any]:
+        """Send a DELETE request and return JSON response."""
+        response = self._client.request("DELETE", url, json=json, headers=headers)
+
+        if response.status_code >= 400:
+            _handle_error_response(response)
+
+        if response.status_code == 204 or not response.content:
+            return {}
+
+        return _extract_content(response.json())
+
+    def close(self) -> None:
+        """Close the HTTP client."""
+        self._client.close()
+
+    def __enter__(self) -> HTTPClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+
+class AsyncHTTPClient:
+    """Asynchronous HTTP client for Chzzk API."""
+
+    def __init__(
+        self,
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        headers: Mapping[str, str] | None = None,
+    ) -> None:
+        default_headers = {
+            "User-Agent": USER_AGENT,
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }
+        if headers:
+            default_headers.update(headers)
+
+        self._client = httpx.AsyncClient(
+            timeout=timeout,
+            headers=default_headers,
+        )
+
+    async def post(
+        self,
+        url: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> dict[str, Any]:
+        """Send a POST request and return JSON response."""
+        response = await self._client.post(url, params=params, json=json, headers=headers)
+
+        if response.status_code >= 400:
+            _handle_error_response(response)
+
+        if response.status_code == 204 or not response.content:
+            return {}
+
+        return _extract_content(response.json())
+
+    async def get(
+        self,
+        url: str,
+        *,
+        params: dict[str, Any] | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> dict[str, Any]:
+        """Send a GET request and return JSON response."""
+        response = await self._client.get(url, params=params, headers=headers)
+
+        if response.status_code >= 400:
+            _handle_error_response(response)
+
+        return _extract_content(response.json())
+
+    async def put(
+        self,
+        url: str,
+        *,
+        json: dict[str, Any] | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> dict[str, Any]:
+        """Send a PUT request and return JSON response."""
+        response = await self._client.put(url, json=json, headers=headers)
+
+        if response.status_code >= 400:
+            _handle_error_response(response)
+
+        if response.status_code == 204 or not response.content:
+            return {}
+
+        return _extract_content(response.json())
+
+    async def patch(
+        self,
+        url: str,
+        *,
+        json: dict[str, Any] | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> dict[str, Any]:
+        """Send a PATCH request and return JSON response."""
+        response = await self._client.patch(url, json=json, headers=headers)
+
+        if response.status_code >= 400:
+            _handle_error_response(response)
+
+        if response.status_code == 204 or not response.content:
+            return {}
+
+        return _extract_content(response.json())
+
+    async def delete(
+        self,
+        url: str,
+        *,
+        json: dict[str, Any] | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> dict[str, Any]:
+        """Send a DELETE request and return JSON response."""
+        response = await self._client.request("DELETE", url, json=json, headers=headers)
+
+        if response.status_code >= 400:
+            _handle_error_response(response)
+
+        if response.status_code == 204 or not response.content:
+            return {}
+
+        return _extract_content(response.json())
+
+    async def close(self) -> None:
+        """Close the HTTP client."""
+        await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncHTTPClient:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()

chzzk/http/endpoints.py

@@ -0,0 +1,52 @@
+"""API endpoints and base URLs for Chzzk API."""
+
+# Base URLs
+CHZZK_BASE_URL = "https://chzzk.naver.com"
+OPENAPI_BASE_URL = "https://openapi.chzzk.naver.com"
+
+# Authorization endpoints
+AUTH_INTERLOCK_URL = f"{CHZZK_BASE_URL}/account-interlock"
+AUTH_TOKEN_URL = f"{OPENAPI_BASE_URL}/auth/v1/token"
+AUTH_REVOKE_URL = f"{OPENAPI_BASE_URL}/auth/v1/token/revoke"
+
+# Open API prefix
+OPEN_API_PREFIX = f"{OPENAPI_BASE_URL}/open/v1"
+
+# User endpoints
+USER_ME_URL = f"{OPEN_API_PREFIX}/users/me"
+
+# Channel endpoints
+CHANNELS_URL = f"{OPEN_API_PREFIX}/channels"
+CHANNEL_ROLES_URL = f"{OPEN_API_PREFIX}/channels/streaming-roles"
+CHANNEL_FOLLOWERS_URL = f"{OPEN_API_PREFIX}/channels/followers"
+CHANNEL_SUBSCRIBERS_URL = f"{OPEN_API_PREFIX}/channels/subscribers"
+
+# Category endpoints
+CATEGORIES_SEARCH_URL = f"{OPEN_API_PREFIX}/categories/search"
+
+# Live endpoints
+LIVES_URL = f"{OPEN_API_PREFIX}/lives"
+STREAM_KEY_URL = f"{OPEN_API_PREFIX}/streams/key"
+LIVE_SETTING_URL = f"{OPEN_API_PREFIX}/lives/setting"
+
+# Chat endpoints
+CHAT_SEND_URL = f"{OPEN_API_PREFIX}/chats/send"
+CHAT_NOTICE_URL = f"{OPEN_API_PREFIX}/chats/notice"
+CHAT_SETTINGS_URL = f"{OPEN_API_PREFIX}/chats/settings"
+
+# Restriction endpoints
+RESTRICT_CHANNELS_URL = f"{OPEN_API_PREFIX}/restrict-channels"
+
+# Session endpoints
+SESSIONS_AUTH_URL = f"{OPEN_API_PREFIX}/sessions/auth"
+SESSIONS_AUTH_CLIENT_URL = f"{OPEN_API_PREFIX}/sessions/auth/client"
+SESSIONS_URL = f"{OPEN_API_PREFIX}/sessions"
+SESSIONS_CLIENT_URL = f"{OPEN_API_PREFIX}/sessions/client"
+SESSIONS_SUBSCRIBE_CHAT_URL = f"{OPEN_API_PREFIX}/sessions/events/subscribe/chat"
+SESSIONS_SUBSCRIBE_DONATION_URL = f"{OPEN_API_PREFIX}/sessions/events/subscribe/donation"
+SESSIONS_SUBSCRIBE_SUBSCRIPTION_URL = f"{OPEN_API_PREFIX}/sessions/events/subscribe/subscription"
+SESSIONS_UNSUBSCRIBE_CHAT_URL = f"{OPEN_API_PREFIX}/sessions/events/unsubscribe/chat"
+SESSIONS_UNSUBSCRIBE_DONATION_URL = f"{OPEN_API_PREFIX}/sessions/events/unsubscribe/donation"
+SESSIONS_UNSUBSCRIBE_SUBSCRIPTION_URL = (
+    f"{OPEN_API_PREFIX}/sessions/events/unsubscribe/subscription"
+)

chzzk/models/__init__.py

@@ -0,0 +1,86 @@
+"""Pydantic models for Chzzk API responses."""
+
+from chzzk.models.category import Category
+from chzzk.models.channel import (
+    ChannelInfo,
+    ChannelManager,
+    Follower,
+    Subscriber,
+    SubscriberSortType,
+    UserRole,
+)
+from chzzk.models.chat import (
+    ChatAvailableCondition,
+    ChatAvailableGroup,
+    ChatMessageResponse,
+    ChatSettings,
+    UpdateChatSettingsRequest,
+)
+from chzzk.models.common import CategoryType, Page
+from chzzk.models.live import (
+    LiveInfo,
+    LiveListResponse,
+    LiveSetting,
+    LiveSettingCategory,
+    StreamKey,
+    UpdateLiveSettingRequest,
+)
+from chzzk.models.restriction import RestrictedChannel
+from chzzk.models.session import (
+    Badge,
+    ChatEvent,
+    ChatProfile,
+    DonationEvent,
+    DonationType,
+    EventType,
+    SessionAuthResponse,
+    SessionInfo,
+    SessionListResponse,
+    SubscribedEvent,
+    SubscriptionEvent,
+    SystemEvent,
+    SystemEventData,
+    SystemMessageType,
+    UserRoleCode,
+)
+from chzzk.models.user import UserInfo
+
+__all__ = [
+    "Badge",
+    "Category",
+    "CategoryType",
+    "ChannelInfo",
+    "ChannelManager",
+    "ChatAvailableCondition",
+    "ChatAvailableGroup",
+    "ChatEvent",
+    "ChatMessageResponse",
+    "ChatProfile",
+    "ChatSettings",
+    "DonationEvent",
+    "DonationType",
+    "EventType",
+    "Follower",
+    "LiveInfo",
+    "LiveListResponse",
+    "LiveSetting",
+    "LiveSettingCategory",
+    "Page",
+    "RestrictedChannel",
+    "SessionAuthResponse",
+    "SessionInfo",
+    "SessionListResponse",
+    "StreamKey",
+    "SubscribedEvent",
+    "Subscriber",
+    "SubscriberSortType",
+    "SubscriptionEvent",
+    "SystemEvent",
+    "SystemEventData",
+    "SystemMessageType",
+    "UpdateChatSettingsRequest",
+    "UpdateLiveSettingRequest",
+    "UserInfo",
+    "UserRole",
+    "UserRoleCode",
+]

chzzk/models/category.py

@@ -0,0 +1,18 @@
+"""Pydantic models for Category API."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from chzzk.models.common import CategoryType
+
+
+class Category(BaseModel):
+    """Category information."""
+
+    category_type: CategoryType = Field(alias="categoryType")
+    category_id: str = Field(alias="categoryId")
+    category_value: str = Field(alias="categoryValue")
+    poster_image_url: str | None = Field(default=None, alias="posterImageUrl")
+
+    model_config = {"populate_by_name": True}

chzzk/models/channel.py

@@ -0,0 +1,69 @@
+"""Pydantic models for Channel API."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import StrEnum
+
+from pydantic import BaseModel, Field
+
+
+class UserRole(StrEnum):
+    """User role enumeration for channel management."""
+
+    STREAMING_CHANNEL_OWNER = "STREAMING_CHANNEL_OWNER"
+    STREAMING_CHANNEL_MANAGER = "STREAMING_CHANNEL_MANAGER"
+    STREAMING_CHAT_MANAGER = "STREAMING_CHAT_MANAGER"
+    STREAMING_SETTLEMENT_MANAGER = "STREAMING_SETTLEMENT_MANAGER"
+
+
+class SubscriberSortType(StrEnum):
+    """Sort type enumeration for subscriber list."""
+
+    RECENT = "RECENT"
+    LONGER = "LONGER"
+
+
+class ChannelInfo(BaseModel):
+    """Channel information."""
+
+    channel_id: str = Field(alias="channelId")
+    channel_name: str = Field(alias="channelName")
+    channel_image_url: str | None = Field(default=None, alias="channelImageUrl")
+    follower_count: int = Field(alias="followerCount")
+    verified_mark: bool = Field(alias="verifiedMark")
+
+    model_config = {"populate_by_name": True}
+
+
+class ChannelManager(BaseModel):
+    """Channel manager information."""
+
+    manager_channel_id: str = Field(alias="managerChannelId")
+    manager_channel_name: str = Field(alias="managerChannelName")
+    user_role: UserRole = Field(alias="userRole")
+    created_date: datetime = Field(alias="createdDate")
+
+    model_config = {"populate_by_name": True}
+
+
+class Follower(BaseModel):
+    """Follower information."""
+
+    channel_id: str = Field(alias="channelId")
+    channel_name: str = Field(alias="channelName")
+    created_date: datetime = Field(alias="createdDate")
+
+    model_config = {"populate_by_name": True}
+
+
+class Subscriber(BaseModel):
+    """Subscriber information."""
+
+    channel_id: str = Field(alias="channelId")
+    channel_name: str = Field(alias="channelName")
+    created_date: datetime = Field(alias="createdDate")
+    tier_no: int = Field(alias="tierNo")
+    month: int
+
+    model_config = {"populate_by_name": True}

chzzk/models/chat.py

@@ -0,0 +1,63 @@
+"""Pydantic models for Chat API."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+from pydantic import BaseModel, Field
+
+
+class ChatAvailableCondition(StrEnum):
+    """Chat available condition enumeration."""
+
+    NONE = "NONE"
+    REAL_NAME = "REAL_NAME"
+
+
+class ChatAvailableGroup(StrEnum):
+    """Chat available group enumeration."""
+
+    ALL = "ALL"
+    FOLLOWER = "FOLLOWER"
+    MANAGER = "MANAGER"
+    SUBSCRIBER = "SUBSCRIBER"
+
+
+class ChatMessageResponse(BaseModel):
+    """Response model for sending a chat message."""
+
+    message_id: str = Field(alias="messageId")
+
+    model_config = {"populate_by_name": True}
+
+
+class ChatSettings(BaseModel):
+    """Chat settings information."""
+
+    chat_available_condition: ChatAvailableCondition = Field(alias="chatAvailableCondition")
+    chat_available_group: ChatAvailableGroup = Field(alias="chatAvailableGroup")
+    allow_subscriber_in_follower_mode: bool = Field(alias="allowSubscriberInFollowerMode")
+    min_follower_minute: int = Field(alias="minFollowerMinute")
+    chat_emoji_mode: bool = Field(alias="chatEmojiMode")
+    chat_slow_mode_sec: int = Field(alias="chatSlowModeSec")
+
+    model_config = {"populate_by_name": True}
+
+
+class UpdateChatSettingsRequest(BaseModel):
+    """Request model for updating chat settings."""
+
+    chat_available_condition: ChatAvailableCondition | None = Field(
+        default=None, serialization_alias="chatAvailableCondition"
+    )
+    chat_available_group: ChatAvailableGroup | None = Field(
+        default=None, serialization_alias="chatAvailableGroup"
+    )
+    allow_subscriber_in_follower_mode: bool | None = Field(
+        default=None, serialization_alias="allowSubscriberInFollowerMode"
+    )
+    min_follower_minute: int | None = Field(default=None, serialization_alias="minFollowerMinute")
+    chat_emoji_mode: bool | None = Field(default=None, serialization_alias="chatEmojiMode")
+    chat_slow_mode_sec: int | None = Field(default=None, serialization_alias="chatSlowModeSec")
+
+    model_config = {"populate_by_name": True}

chzzk/models/common.py

@@ -0,0 +1,23 @@
+"""Common models shared across API modules."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+from pydantic import BaseModel
+
+
+class Page(BaseModel):
+    """Pagination information for list responses."""
+
+    next: str | None = None
+
+    model_config = {"populate_by_name": True}
+
+
+class CategoryType(StrEnum):
+    """Category type enumeration."""
+
+    GAME = "GAME"
+    SPORTS = "SPORTS"
+    ETC = "ETC"