feishulib 0.1.2__py3-none-any.whl

feishulib/__init__.py

@@ -0,0 +1,61 @@
+"""Async Pythonic client for selected Feishu IM capabilities."""
+
+__version__ = "0.1.0"
+
+from feishulib.config import FeishuConfig
+from feishulib.client import FeishuClient
+from feishulib.channel import EventChannel
+from feishulib.events import CardActionEvent, MessageEvent, OperatorIdentity, SenderIdentity
+from feishulib.exceptions import (
+    FeishuApiError,
+    FeishuAuthError,
+    FeishuError,
+    FeishuEventHandlerError,
+    FeishuEventParseError,
+    FeishuHttpStatusError,
+    FeishuProtocolError,
+    FeishuTransientError,
+    FeishuWebSocketError,
+)
+from feishulib.models import (
+    BinaryResponse,
+    BotIdentity,
+    CardActionResponse,
+    CardUpdate,
+    MessageReceipt,
+    OutboundMessage,
+    ReplyMessage,
+    Toast,
+    UpdateMessage,
+)
+from feishulib.websocket import FeishuWebSocket
+
+__all__ = [
+    "BinaryResponse",
+    "BotIdentity",
+    "CardActionResponse",
+    "CardUpdate",
+    "CardActionEvent",
+    "EventChannel",
+    "FeishuApiError",
+    "FeishuAuthError",
+    "FeishuConfig",
+    "FeishuClient",
+    "FeishuError",
+    "FeishuEventHandlerError",
+    "FeishuEventParseError",
+    "FeishuHttpStatusError",
+    "FeishuProtocolError",
+    "FeishuTransientError",
+    "FeishuWebSocketError",
+    "MessageReceipt",
+    "MessageEvent",
+    "OperatorIdentity",
+    "OutboundMessage",
+    "ReplyMessage",
+    "SenderIdentity",
+    "Toast",
+    "UpdateMessage",
+    "FeishuWebSocket",
+    "__version__",
+]

feishulib/auth.py

@@ -0,0 +1,68 @@
+"""Tenant access token caching and refresh coordination."""
+
+import asyncio
+import time
+from collections.abc import Callable
+
+from feishulib.config import FeishuConfig
+from feishulib.exceptions import FeishuAuthError, FeishuError
+from feishulib.http import FeishuHttpClient
+from feishulib.models import JsonValue
+
+
+class TenantAccessTokenManager:
+    """Return cached tenant tokens and collapse concurrent refreshes."""
+
+    def __init__(
+        self,
+        config: FeishuConfig,
+        http: FeishuHttpClient,
+        *,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self._config = config
+        self._http = http
+        self._clock = clock
+        self._lock = asyncio.Lock()
+        self._token: str | None = None
+        self._expires_at = 0.0
+
+    async def get_token(self, *, force_refresh: bool = False) -> str:
+        """Return a valid tenant access token, refreshing it once when needed."""
+        observed_token = self._token
+        if not force_refresh and self._is_fresh():
+            return self._token_or_error()
+        async with self._lock:
+            if not force_refresh and self._is_fresh():
+                return self._token_or_error()
+            if force_refresh and self._token != observed_token and self._is_fresh():
+                return self._token_or_error()
+            return await self._refresh()
+
+    def _is_fresh(self) -> bool:
+        return self._token is not None and self._clock() < self._expires_at - self._config.token_refresh_skew_seconds
+
+    def _token_or_error(self) -> str:
+        if self._token is None:
+            raise FeishuAuthError("tenant token cache was unexpectedly empty")
+        return self._token
+
+    async def _refresh(self) -> str:
+        body: dict[str, JsonValue] = {"app_id": self._config.app_id, "app_secret": self._config.app_secret}
+        try:
+            response = await self._http.request_json(
+                "POST",
+                "/open-apis/auth/v3/tenant_access_token/internal",
+                json_body=body,
+            )
+            token = response.data.get("tenant_access_token")
+            expires_in = response.data.get("expire")
+            if not isinstance(token, str) or not token:
+                raise ValueError("tenant token is missing or invalid")
+            if not isinstance(expires_in, int) or isinstance(expires_in, bool) or expires_in <= 0:
+                raise ValueError("token expiry is missing or invalid")
+        except (FeishuError, ValueError) as error:
+            raise FeishuAuthError("tenant token refresh failed") from error
+        self._token = token
+        self._expires_at = self._clock() + expires_in
+        return token

feishulib/channel.py

@@ -0,0 +1,107 @@
+"""Bounded worker dispatch for parsed Feishu events."""
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+
+from feishulib.config import FeishuConfig
+from feishulib.events import CardActionEvent, MessageEvent, parse_event_payload
+from feishulib.exceptions import FeishuEventHandlerError
+from feishulib.models import CardActionResponse
+
+type EventHandler[TEvent, TResult] = Callable[[TEvent], Awaitable[TResult]]
+
+
+@dataclass(slots=True)
+class _DispatchItem:
+    event: MessageEvent | CardActionEvent
+    result: asyncio.Future[CardActionResponse | None]
+
+
+class EventChannel:
+    """Dispatch parsed events outside of the WebSocket receive loop."""
+
+    def __init__(self, config: FeishuConfig) -> None:
+        self._config = config
+        self._message_handlers: list[EventHandler[MessageEvent, None]] = []
+        self._card_handler: EventHandler[CardActionEvent, CardActionResponse | None] | None = None
+        self._queue: asyncio.Queue[_DispatchItem] = asyncio.Queue(maxsize=config.event_queue_size)
+        self._workers: list[asyncio.Task[None]] = []
+        self._started = False
+        self._closed = False
+
+    def on(self, name: str, handler: Callable[..., Awaitable[object]]) -> None:
+        """Register an asynchronous event handler."""
+        if self._closed:
+            raise RuntimeError("event channel is closed")
+        if name == "message":
+            self._message_handlers.append(handler)  # type: ignore[arg-type]
+            return
+        if name == "card_action":
+            if self._card_handler is not None:
+                raise ValueError("only one card_action handler is allowed")
+            self._card_handler = handler  # type: ignore[assignment]
+            return
+        raise ValueError("unknown event name")
+
+    async def start(self) -> None:
+        """Start the configured worker pool."""
+        if self._closed:
+            raise RuntimeError("event channel is closed")
+        if not self._started:
+            self._started = True
+            self._workers = [asyncio.create_task(self._worker()) for _ in range(self._config.event_worker_count)]
+
+    async def dispatch(self, payload: bytes) -> CardActionResponse | None:
+        """Parse, enqueue, and await one event's handler result."""
+        if not self._started or self._closed:
+            raise RuntimeError("event channel is not running")
+        event = parse_event_payload(payload)
+        result: asyncio.Future[CardActionResponse | None] = asyncio.get_running_loop().create_future()
+        try:
+            self._queue.put_nowait(_DispatchItem(event, result))
+        except asyncio.QueueFull as error:
+            raise FeishuEventHandlerError("queue", error) from error
+        return await result
+
+    async def close(self) -> None:
+        """Cancel workers and reject subsequent dispatches."""
+        if self._closed:
+            return
+        self._closed = True
+        for worker in self._workers:
+            worker.cancel()
+        if self._workers:
+            await asyncio.gather(*self._workers, return_exceptions=True)
+        while not self._queue.empty():
+            item = self._queue.get_nowait()
+            if not item.result.done():
+                item.result.set_exception(FeishuEventHandlerError("shutdown", RuntimeError("channel closed")))
+
+    async def _worker(self) -> None:
+        while True:
+            item = await self._queue.get()
+            try:
+                if isinstance(item.event, MessageEvent):
+                    for handler in self._message_handlers:
+                        await handler(item.event)
+                    if not item.result.done():
+                        item.result.set_result(None)
+                elif self._card_handler is None:
+                    if not item.result.done():
+                        item.result.set_result(None)
+                else:
+                    response = await self._card_handler(item.event)
+                    if response is not None and not isinstance(response, CardActionResponse):  # type: ignore[unnecessary-isinstance]
+                        raise TypeError("card_action handler must return CardActionResponse or None")
+                    if not item.result.done():
+                        item.result.set_result(response)
+            except asyncio.CancelledError as error:
+                if not item.result.done():
+                    item.result.set_exception(FeishuEventHandlerError("shutdown", error))
+                raise
+            except Exception as error:
+                if not item.result.done():
+                    item.result.set_exception(FeishuEventHandlerError("handler", error))
+            finally:
+                self._queue.task_done()

feishulib/client.py

@@ -0,0 +1,191 @@
+"""High-level asynchronous Feishu IM and bot client."""
+
+from collections.abc import Mapping
+from dataclasses import replace
+from typing import Literal, Self
+from urllib.parse import quote
+from uuid import uuid4
+
+import httpx
+
+from feishulib.auth import TenantAccessTokenManager
+from feishulib.config import FeishuConfig
+from feishulib.exceptions import FeishuApiError, FeishuHttpStatusError
+from feishulib.http import FeishuHttpClient
+from feishulib.models import (
+    ApiResponse,
+    BinaryResponse,
+    BotIdentity,
+    JsonValue,
+    MessageReceipt,
+    OutboundMessage,
+    ReceiveIdType,
+    ReplyMessage,
+    UpdateMessage,
+)
+
+
+class FeishuClient:
+    """Facade for the selected Feishu IM REST surface."""
+
+    def __init__(self, config: FeishuConfig, *, session: httpx.AsyncClient | None = None) -> None:
+        self.config = config
+        self._owns_session = session is None
+        self._session = session if session is not None else httpx.AsyncClient()
+        self._http = FeishuHttpClient(config, self._session)
+        self._tokens = TenantAccessTokenManager(config, self._http)
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, exc_type: object, exc: object, traceback: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        if self._owns_session:
+            await self._session.aclose()
+
+    @staticmethod
+    def _outbound_with_uuid(message: OutboundMessage) -> OutboundMessage:
+        if message.uuid is not None:
+            return message
+        return replace(message, uuid=str(uuid4()))
+
+    @staticmethod
+    def _reply_with_uuid(message: ReplyMessage) -> ReplyMessage:
+        if message.uuid is not None:
+            return message
+        return replace(message, uuid=str(uuid4()))
+
+    async def send_message(self, message: OutboundMessage) -> MessageReceipt:
+        message = self._outbound_with_uuid(message)
+        response = await self._authorized_json(
+            "POST",
+            "/open-apis/im/v1/messages",
+            params={"receive_id_type": message.receive_id_type},
+            json_body=message.to_payload(),
+        )
+        return self._receipt(response)
+
+    async def send_text(
+        self,
+        receive_id: str,
+        text: str,
+        *,
+        receive_id_type: ReceiveIdType = "chat_id",
+        uuid: str | None = None,
+    ) -> MessageReceipt:
+        return await self.send_message(OutboundMessage(receive_id, receive_id_type, "text", {"text": text}, uuid))
+
+    async def send_card(
+        self,
+        receive_id: str,
+        card: Mapping[str, JsonValue],
+        *,
+        receive_id_type: ReceiveIdType = "chat_id",
+        uuid: str | None = None,
+    ) -> MessageReceipt:
+        return await self.send_message(OutboundMessage(receive_id, receive_id_type, "interactive", card, uuid))
+
+    async def reply_message(self, message: ReplyMessage) -> MessageReceipt:
+        message = self._reply_with_uuid(message)
+        response = await self._authorized_json(
+            "POST",
+            f"/open-apis/im/v1/messages/{quote(message.message_id, safe='')}/reply",
+            json_body=message.to_payload(),
+        )
+        return self._receipt(response)
+
+    async def reply_text(
+        self,
+        message_id: str,
+        text: str,
+        *,
+        reply_in_thread: bool = False,
+        uuid: str | None = None,
+    ) -> MessageReceipt:
+        return await self.reply_message(ReplyMessage(message_id, "text", {"text": text}, reply_in_thread, uuid))
+
+    async def update_message(self, message: UpdateMessage) -> MessageReceipt:
+        response = await self._authorized_json(
+            "PUT",
+            f"/open-apis/im/v1/messages/{quote(message.message_id, safe='')}",
+            json_body=message.to_payload(),
+        )
+        return self._receipt(response)
+
+    async def update_card(self, message_id: str, card: Mapping[str, JsonValue]) -> MessageReceipt:
+        return await self.update_message(UpdateMessage(message_id, "interactive", card))
+
+    async def delete_message(self, message_id: str) -> None:
+        await self._authorized_json("DELETE", f"/open-apis/im/v1/messages/{quote(message_id, safe='')}")
+
+    async def download_file(
+        self,
+        message_id: str,
+        file_key: str,
+        *,
+        resource_type: Literal["file", "image"] = "file",
+    ) -> bytes:
+        response = await self._authorized_bytes(
+            "GET",
+            f"/open-apis/im/v1/messages/{quote(message_id, safe='')}/resources/{quote(file_key, safe='')}",
+            params={"type": resource_type},
+        )
+        return response.content
+
+    async def get_bot_identity(self) -> BotIdentity:
+        response = await self._authorized_json("GET", "/open-apis/bot/v3/info")
+        candidate = response.data.get("bot")
+        if not isinstance(candidate, Mapping):
+            candidate = response.data
+        open_id = candidate.get("open_id")
+        if not isinstance(open_id, str) or not open_id:
+            raise FeishuApiError(0, "bot identity response has no open_id", response.request_id)
+        return BotIdentity(open_id)
+
+    async def _authorized_json(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, str] | None = None,
+        json_body: Mapping[str, JsonValue] | None = None,
+    ) -> ApiResponse:
+        token = await self._tokens.get_token()
+        try:
+            return await self._http.request_json(method, path, headers={"Authorization": f"Bearer {token}"}, params=params, json_body=json_body)
+        except FeishuHttpStatusError as error:
+            if error.status_code != 401:
+                raise
+        token = await self._tokens.get_token(force_refresh=True)
+        return await self._http.request_json(method, path, headers={"Authorization": f"Bearer {token}"}, params=params, json_body=json_body)
+
+    async def _authorized_bytes(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, str] | None = None,
+    ) -> BinaryResponse:
+        token = await self._tokens.get_token()
+        try:
+            return await self._http.request_bytes(method, path, headers={"Authorization": f"Bearer {token}"}, params=params)
+        except FeishuHttpStatusError as error:
+            if error.status_code != 401:
+                raise
+        token = await self._tokens.get_token(force_refresh=True)
+        return await self._http.request_bytes(method, path, headers={"Authorization": f"Bearer {token}"}, params=params)
+
+    @staticmethod
+    def _receipt(response: ApiResponse) -> MessageReceipt:
+        message_id = response.data.get("message_id")
+        if not isinstance(message_id, str) or not message_id:
+            raise FeishuApiError(0, "message response has no message_id", response.request_id)
+        root_id = response.data.get("root_id")
+        parent_id = response.data.get("parent_id")
+        return MessageReceipt(
+            message_id,
+            root_id if isinstance(root_id, str) else None,
+            parent_id if isinstance(parent_id, str) else None,
+        )

feishulib/config.py

@@ -0,0 +1,55 @@
+"""Runtime configuration for the Feishu IM client."""
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True, slots=True)
+class FeishuConfig:
+    app_id: str
+    app_secret: str = field(repr=False)
+    base_url: str = "https://open.feishu.cn"
+    request_timeout_seconds: float = 10.0
+    max_retries: int = 3
+    retry_backoff_base_seconds: float = 0.5
+    retry_max_delay_seconds: float = 15.0
+    retry_jitter_ratio: float = 0.1
+    token_refresh_skew_seconds: float = 60.0
+    ws_open_timeout_seconds: float = 15.0
+    ws_close_timeout_seconds: float = 10.0
+    ws_ping_timeout_seconds: float = 180.0
+    ws_reconnect_base_seconds: float = 1.0
+    ws_reconnect_max_seconds: float = 60.0
+    ws_reconnect_jitter_ratio: float = 0.1
+    event_queue_size: int = 100
+    event_worker_count: int = 1
+    card_action_timeout_seconds: float = 8.0
+
+    def __post_init__(self) -> None:
+        if not self.app_id:
+            raise ValueError("app_id must not be empty")
+        if not self.app_secret:
+            raise ValueError("app_secret must not be empty")
+        if not self.base_url.startswith("https://"):
+            raise ValueError("base_url must use https")
+        if self.request_timeout_seconds <= 0:
+            raise ValueError("request_timeout_seconds must be positive")
+        if self.max_retries < 0:
+            raise ValueError("max_retries must be non-negative")
+        if self.retry_backoff_base_seconds <= 0 or self.retry_max_delay_seconds <= 0:
+            raise ValueError("retry delays must be positive")
+        if not 0 <= self.retry_jitter_ratio <= 1:
+            raise ValueError("retry_jitter_ratio must be between 0 and 1")
+        if self.token_refresh_skew_seconds < 0:
+            raise ValueError("token_refresh_skew_seconds must be non-negative")
+        if self.ws_open_timeout_seconds <= 0 or self.ws_close_timeout_seconds <= 0:
+            raise ValueError("websocket timeouts must be positive")
+        if self.ws_ping_timeout_seconds <= 0:
+            raise ValueError("ws_ping_timeout_seconds must be positive")
+        if self.ws_reconnect_base_seconds <= 0 or self.ws_reconnect_max_seconds <= 0:
+            raise ValueError("websocket reconnect delays must be positive")
+        if not 0 <= self.ws_reconnect_jitter_ratio <= 1:
+            raise ValueError("ws_reconnect_jitter_ratio must be between 0 and 1")
+        if self.event_queue_size < 1 or self.event_worker_count < 1:
+            raise ValueError("event queue size and worker count must be positive")
+        if self.card_action_timeout_seconds <= 0:
+            raise ValueError("card_action_timeout_seconds must be positive")

feishulib/events.py

@@ -0,0 +1,146 @@
+"""Schema 2.0 event parsing with an explicit trusted identity boundary."""
+
+import json
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import cast
+
+from feishulib.exceptions import FeishuEventParseError
+from feishulib.models import JsonValue
+
+
+@dataclass(frozen=True, slots=True)
+class SenderIdentity:
+    open_id: str | None
+    user_id: str | None
+    union_id: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class OperatorIdentity:
+    tenant_key: str | None
+    user_id: str | None
+    open_id: str
+    union_id: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class MessageEvent:
+    event_id: str | None
+    sender: SenderIdentity
+    message_id: str
+    chat_id: str | None
+    chat_type: str | None
+    message_type: str | None
+    raw_content: str | None
+    content: Mapping[str, JsonValue] | None
+    text: str | None
+    file_key: str | None
+    root_id: str | None
+    parent_id: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class CardActionEvent:
+    event_id: str | None
+    operator: OperatorIdentity
+    action_value: Mapping[str, JsonValue]
+    action_tag: str | None
+    action_name: str | None
+    form_value: Mapping[str, JsonValue] | None
+    token: str | None
+    message_id: str | None
+    chat_id: str | None
+
+
+def parse_event_payload(payload: bytes) -> MessageEvent | CardActionEvent:
+    """Parse one trusted Feishu schema 2.0 event payload."""
+    try:
+        body = json.loads(payload.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as error:
+        raise FeishuEventParseError("event payload is not valid UTF-8 JSON") from error
+    if not isinstance(body, Mapping):
+        raise FeishuEventParseError("event schema must be 2.0")
+    envelope = cast(Mapping[str, object], body)
+    if envelope.get("schema") != "2.0":
+        raise FeishuEventParseError("event schema must be 2.0")
+    header = _mapping(envelope.get("header"), "header")
+    event_type = header.get("event_type")
+    if not isinstance(event_type, str):
+        raise FeishuEventParseError("header.event_type must be a string")
+    event = _mapping(envelope.get("event"), "event", event_type)
+    if event_type == "im.message.receive_v1":
+        return _message_event(header, event)
+    if event_type == "card.action.trigger":
+        return _card_event(header, event)
+    raise FeishuEventParseError(f"{event_type}: unsupported event type")
+
+
+def _message_event(header: Mapping[str, object], event: Mapping[str, object]) -> MessageEvent:
+    message = _mapping(event.get("message"), "event.message", "im.message.receive_v1")
+    sender = _mapping(event.get("sender"), "event.sender", "im.message.receive_v1")
+    ids = _mapping(sender.get("sender_id"), "event.sender.sender_id", "im.message.receive_v1")
+    message_id = message.get("message_id")
+    if not isinstance(message_id, str) or not message_id:
+        raise FeishuEventParseError("im.message.receive_v1: event.message.message_id is required")
+    raw_content = message.get("content")
+    raw = raw_content if isinstance(raw_content, str) else None
+    content = _content(raw)
+    text = content.get("text") if content is not None else None
+    file_key = content.get("file_key") if content is not None else None
+    return MessageEvent(
+        _optional_str(header.get("event_id")),
+        SenderIdentity(_optional_str(ids.get("open_id")), _optional_str(ids.get("user_id")), _optional_str(ids.get("union_id"))),
+        message_id,
+        _optional_str(message.get("chat_id")),
+        _optional_str(message.get("chat_type")),
+        _optional_str(message.get("message_type")),
+        raw,
+        content,
+        text if isinstance(text, str) else None,
+        file_key if isinstance(file_key, str) else None,
+        _optional_str(message.get("root_id")),
+        _optional_str(message.get("parent_id")),
+    )
+
+
+def _card_event(header: Mapping[str, object], event: Mapping[str, object]) -> CardActionEvent:
+    operator = _mapping(event.get("operator"), "event.operator", "card.action.trigger")
+    open_id = operator.get("open_id")
+    if not isinstance(open_id, str) or not open_id:
+        raise FeishuEventParseError("card.action.trigger: event.operator.open_id is required")
+    action = _mapping(event.get("action"), "event.action", "card.action.trigger")
+    value = action.get("value", {})
+    action_value = cast(Mapping[str, JsonValue], _mapping(value, "event.action.value", "card.action.trigger"))
+    form_value = action.get("form_value")
+    return CardActionEvent(
+        _optional_str(header.get("event_id")),
+        OperatorIdentity(_optional_str(operator.get("tenant_key")), _optional_str(operator.get("user_id")), open_id, _optional_str(operator.get("union_id"))),
+        dict(action_value),
+        _optional_str(action.get("tag")),
+        _optional_str(action.get("name")),
+        cast(Mapping[str, JsonValue], form_value) if isinstance(form_value, Mapping) else None,
+        _optional_str(event.get("token")),
+        _optional_str(event.get("open_message_id")),
+        _optional_str(event.get("open_chat_id")),
+    )
+
+
+def _content(raw_content: str | None) -> Mapping[str, JsonValue] | None:
+    if raw_content is None:
+        return None
+    try:
+        value = json.loads(raw_content)
+    except json.JSONDecodeError:
+        return None
+    return cast(Mapping[str, JsonValue], value) if isinstance(value, Mapping) else None
+
+
+def _mapping(value: object, field: str, event_type: str = "event") -> Mapping[str, object]:
+    if not isinstance(value, Mapping):
+        raise FeishuEventParseError(f"{event_type}: {field} must be an object")
+    return cast(Mapping[str, object], value)
+
+
+def _optional_str(value: object) -> str | None:
+    return value if isinstance(value, str) else None

feishulib/exceptions.py

@@ -0,0 +1,60 @@
+"""Explicit exceptions raised by the Feishu IM client."""
+
+
+class FeishuError(Exception):
+    """Base exception for all client failures."""
+
+
+class FeishuAuthError(FeishuError):
+    """Tenant access token retrieval or validation failed."""
+
+
+class FeishuApiError(FeishuError):
+    """The Feishu API returned a non-zero business code."""
+
+    def __init__(self, code: int, message: str, request_id: str | None = None) -> None:
+        self.code = code
+        self.message = message
+        self.request_id = request_id
+        super().__init__(f"Feishu API error {code}: {message}")
+
+
+class FeishuHttpStatusError(FeishuError):
+    """An HTTP response had a non-success status."""
+
+    def __init__(self, status_code: int, message: str, request_id: str | None = None) -> None:
+        self.status_code = status_code
+        self.message = message
+        self.request_id = request_id
+        super().__init__(f"Feishu HTTP status {status_code}: {message}")
+
+
+class FeishuTransientError(FeishuError):
+    """A retryable transport or HTTP failure exhausted its retry budget."""
+
+    def __init__(self, status_code: int | None, attempts: int, request_id: str | None = None) -> None:
+        self.status_code = status_code
+        self.attempts = attempts
+        self.request_id = request_id
+        super().__init__(f"Feishu transient failure after {attempts} attempts")
+
+
+class FeishuProtocolError(FeishuError):
+    """A remote response did not match the expected protocol."""
+
+
+class FeishuWebSocketError(FeishuError):
+    """A WebSocket connection or frame exchange failed."""
+
+
+class FeishuEventParseError(FeishuError):
+    """An incoming event could not be parsed safely."""
+
+
+class FeishuEventHandlerError(FeishuError):
+    """An event handler failed or event dispatch could not proceed."""
+
+    def __init__(self, event_type: str, cause: BaseException) -> None:
+        self.event_type = event_type
+        self.cause = cause
+        super().__init__(f"Feishu event handler failed for {event_type}: {cause}")