feishulib 0.1.2__tar.gz

feishulib-0.1.2/PKG-INFO

@@ -0,0 +1,261 @@
+Metadata-Version: 2.3
+Name: feishulib
+Version: 0.1.2
+Summary: Async Pythonic Feishu IM client
+Author: morrisx
+Author-email: morrisx <ifme.in@gmail.com>
+Requires-Dist: httpx>=0.27
+Requires-Dist: protobuf>=7.35.0,<8
+Requires-Dist: websockets>=14
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# feishulib
+
+A lightweight, asynchronous, typed Python client for the Feishu IM API. No runtime dependency on `lark_oapi`.
+
+## Features
+
+- **REST API** — send, reply, update, delete messages; download resources; query bot identity
+- **Long-connection events** — receive text messages and card actions over persistent WebSocket
+- **Async-native** — built on `httpx` and `websockets` with `asyncio`
+- **Typed** — fully annotated public API, strict Pyright validation
+- **Resilient** — automatic tenant-token refresh, HTTP retry with backoff, WebSocket reconnection with exponential backoff and jitter
+
+## Installation
+
+```bash
+uv add feishulib
+```
+
+Requires Python >= 3.12.
+
+## Quick Start
+
+```python
+from feishulib import FeishuClient, FeishuConfig
+
+config = FeishuConfig(app_id="cli_xxx", app_secret="your_secret")
+async with FeishuClient(config) as client:
+    receipt = await client.send_text("oc_xxx", "Hello from feishulib!")
+    print(receipt.message_id)
+```
+
+## REST API
+
+All methods are on `FeishuClient`, used as an async context manager.
+
+### Sending Messages
+
+```python
+from feishulib import FeishuClient, FeishuConfig, OutboundMessage
+
+async with FeishuClient(FeishuConfig(app_id, secret)) as client:
+    # Send text
+    receipt = await client.send_text("oc_xxx", "Hello!")
+
+    # Send card (interactive)
+    card = {
+        "config": {"wide_screen_mode": True},
+        "elements": [{"tag": "markdown", "content": "**Hello**"}],
+    }
+    receipt = await client.send_card("oc_xxx", card)
+
+    # Send with custom message type
+    from feishulib import OutboundMessage
+    message = OutboundMessage(
+        receive_id="oc_xxx",
+        receive_id_type="chat_id",
+        msg_type="post",
+        content={"zh_cn": {"title": "Post", "content": [...]}},
+    )
+    receipt = await client.send_message(message)
+```
+
+`send_message` and `send_text` accept an optional `uuid` parameter. When omitted, the client generates one automatically and retains it across transport retries for idempotency.
+
+### Replying to Messages
+
+```python
+from feishulib import ReplyMessage
+
+# Reply text
+receipt = await client.reply_text("om_xxx", "Got it!")
+
+# Reply with a card
+await client.reply_message(ReplyMessage("om_xxx", "interactive", card))
+
+# Reply in thread
+await client.reply_text("om_xxx", "In thread", reply_in_thread=True)
+```
+
+### Updating and Deleting Messages
+
+```python
+from feishulib import UpdateMessage
+
+# Update message content
+await client.update_message(UpdateMessage("om_xxx", "text", {"text": "Edited"}))
+
+# Update a card
+await client.update_card("om_xxx", card)
+
+# Delete a message
+await client.delete_message("om_xxx")
+```
+
+### Downloading Resources
+
+```python
+content = await client.download_file("om_xxx", "file_key_xxx", resource_type="file")
+# resource_type can be "file" or "image"
+```
+
+### Bot Identity
+
+```python
+bot = await client.get_bot_identity()
+print(bot.open_id)  # e.g. "ou_xxxx"
+```
+
+## Long-Connection Events
+
+feishulib supports receiving events via Feishu's long-connection protocol, using a minimal protobuf frame schema.
+
+### Text Message Reception
+
+```python
+from feishulib import EventChannel, FeishuClient, FeishuConfig, FeishuWebSocket
+from feishulib.events import MessageEvent
+
+config = FeishuConfig(app_id, secret)
+channel = EventChannel(config)
+
+async with FeishuClient(config) as client:
+    bot = await client.get_bot_identity()
+
+    async def on_message(event: MessageEvent) -> None:
+        if event.sender.open_id == bot.open_id:
+            return  # ignore messages from self
+        reply = reply_for_message(event)  # your logic
+        if reply and event.chat_id:
+            await client.send_text(event.chat_id, reply)
+
+    channel.on("message", on_message)
+
+    async with FeishuWebSocket(config, channel) as ws:
+        await ws.run_forever()
+```
+
+### Card Action Handling
+
+```python
+from feishulib import CardActionResponse, EventChannel, FeishuConfig, FeishuWebSocket, Toast
+from feishulib.events import CardActionEvent
+
+config = FeishuConfig(app_id, secret)
+channel = EventChannel(config)
+
+async def on_card_action(event: CardActionEvent) -> CardActionResponse:
+    print(f"Action from {event.operator.open_id}: {event.action_value}")
+    return CardActionResponse(toast=Toast(kind="success", content="Done"))
+
+channel.on("card_action", on_card_action)
+
+async with FeishuWebSocket(config, channel) as ws:
+    await ws.run_forever()
+```
+
+### Event Channel
+
+The `EventChannel` dispatches incoming events to registered handlers:
+
+| Method | Event | Handler signature | Notes |
+| --- | --- | --- | --- |
+| `channel.on("message", fn)` | `im.message.receive_v1` | `async (MessageEvent) -> None` | Multiple handlers allowed; run in registration order |
+| `channel.on("card_action", fn)` | `card.action.trigger` | `async (CardActionEvent) -> CardActionResponse \| None` | At most one handler |
+
+The card action handler can return a `CardActionResponse` with a toast, a card update, or both.
+
+### WebSocket Connection
+
+`FeishuWebSocket` manages the long-connection lifecycle:
+
+- Automatic endpoint discovery via `POST /callback/ws/endpoint`
+- Heartbeat via ping/pong frames
+- Exponential backoff reconnection with jitter on transient failures
+- Configurable open/close timeouts
+- Event ACK: valid events → `200`, handler failures → `503`, timeout → `500`
+- Unsupported or malformed events are acknowledged with `200` and dropped gracefully
+
+## Configuration
+
+```python
+from feishulib import FeishuConfig
+
+config = FeishuConfig(
+    app_id="cli_xxx",
+    app_secret="your_secret",
+    # Optional overrides (defaults shown):
+    base_url="https://open.feishu.cn",
+    request_timeout_seconds=10.0,
+    max_retries=3,
+    retry_backoff_base_seconds=0.5,
+    retry_max_delay_seconds=15.0,
+    retry_jitter_ratio=0.1,
+    token_refresh_skew_seconds=60.0,
+    ws_open_timeout_seconds=15.0,
+    ws_close_timeout_seconds=10.0,
+    ws_ping_timeout_seconds=180.0,
+    ws_reconnect_base_seconds=1.0,
+    ws_reconnect_max_seconds=60.0,
+    ws_reconnect_jitter_ratio=0.1,
+    event_queue_size=100,
+    event_worker_count=1,
+    card_action_timeout_seconds=8.0,
+)
+```
+
+`app_secret` is excluded from `repr()` to prevent accidental leakage in logs.
+
+## Error Handling
+
+All exceptions inherit from `FeishuError`:
+
+| Exception | When it occurs |
+| --- | --- |
+| `FeishuApiError` | Feishu API returned a non-zero business code |
+| `FeishuHttpStatusError` | HTTP response had a non-success status |
+| `FeishuTransientError` | Retryable transport failure exhausted retry budget |
+| `FeishuAuthError` | Tenant access token retrieval or validation failed |
+| `FeishuProtocolError` | Remote response did not match the expected protocol |
+| `FeishuWebSocketError` | WebSocket connection or frame exchange failed |
+| `FeishuEventParseError` | Incoming event could not be parsed |
+| `FeishuEventHandlerError` | Event handler failed or event dispatch could not proceed |
+
+## Security
+
+- **Card action identity** — always use `event.operator` for authentication. Values in `event.action.value` are user-controlled and must never be trusted as an identity source.
+- **Event payload** — malformed and unsupported events are acknowledged and dropped without dispatch. The client logs the parse error and event type, but never logs the raw event payload, credentials, or action values.
+- **Credentials** — `app_secret` is omitted from `FeishuConfig.__repr__`. Authorization headers are redacted in logs.
+
+## Development
+
+```bash
+# Clone and install
+git clone <repo>
+cd feishulib
+uv sync
+
+# Run quality gate
+bash scripts/verify
+
+# Individual checks
+uv run ruff check .
+uv run pyright
+uv run pytest --cov=src/feishulib --cov-report=term-missing
+```
+
+## License
+
+MIT

feishulib-0.1.2/README.md

@@ -0,0 +1,249 @@
+# feishulib
+
+A lightweight, asynchronous, typed Python client for the Feishu IM API. No runtime dependency on `lark_oapi`.
+
+## Features
+
+- **REST API** — send, reply, update, delete messages; download resources; query bot identity
+- **Long-connection events** — receive text messages and card actions over persistent WebSocket
+- **Async-native** — built on `httpx` and `websockets` with `asyncio`
+- **Typed** — fully annotated public API, strict Pyright validation
+- **Resilient** — automatic tenant-token refresh, HTTP retry with backoff, WebSocket reconnection with exponential backoff and jitter
+
+## Installation
+
+```bash
+uv add feishulib
+```
+
+Requires Python >= 3.12.
+
+## Quick Start
+
+```python
+from feishulib import FeishuClient, FeishuConfig
+
+config = FeishuConfig(app_id="cli_xxx", app_secret="your_secret")
+async with FeishuClient(config) as client:
+    receipt = await client.send_text("oc_xxx", "Hello from feishulib!")
+    print(receipt.message_id)
+```
+
+## REST API
+
+All methods are on `FeishuClient`, used as an async context manager.
+
+### Sending Messages
+
+```python
+from feishulib import FeishuClient, FeishuConfig, OutboundMessage
+
+async with FeishuClient(FeishuConfig(app_id, secret)) as client:
+    # Send text
+    receipt = await client.send_text("oc_xxx", "Hello!")
+
+    # Send card (interactive)
+    card = {
+        "config": {"wide_screen_mode": True},
+        "elements": [{"tag": "markdown", "content": "**Hello**"}],
+    }
+    receipt = await client.send_card("oc_xxx", card)
+
+    # Send with custom message type
+    from feishulib import OutboundMessage
+    message = OutboundMessage(
+        receive_id="oc_xxx",
+        receive_id_type="chat_id",
+        msg_type="post",
+        content={"zh_cn": {"title": "Post", "content": [...]}},
+    )
+    receipt = await client.send_message(message)
+```
+
+`send_message` and `send_text` accept an optional `uuid` parameter. When omitted, the client generates one automatically and retains it across transport retries for idempotency.
+
+### Replying to Messages
+
+```python
+from feishulib import ReplyMessage
+
+# Reply text
+receipt = await client.reply_text("om_xxx", "Got it!")
+
+# Reply with a card
+await client.reply_message(ReplyMessage("om_xxx", "interactive", card))
+
+# Reply in thread
+await client.reply_text("om_xxx", "In thread", reply_in_thread=True)
+```
+
+### Updating and Deleting Messages
+
+```python
+from feishulib import UpdateMessage
+
+# Update message content
+await client.update_message(UpdateMessage("om_xxx", "text", {"text": "Edited"}))
+
+# Update a card
+await client.update_card("om_xxx", card)
+
+# Delete a message
+await client.delete_message("om_xxx")
+```
+
+### Downloading Resources
+
+```python
+content = await client.download_file("om_xxx", "file_key_xxx", resource_type="file")
+# resource_type can be "file" or "image"
+```
+
+### Bot Identity
+
+```python
+bot = await client.get_bot_identity()
+print(bot.open_id)  # e.g. "ou_xxxx"
+```
+
+## Long-Connection Events
+
+feishulib supports receiving events via Feishu's long-connection protocol, using a minimal protobuf frame schema.
+
+### Text Message Reception
+
+```python
+from feishulib import EventChannel, FeishuClient, FeishuConfig, FeishuWebSocket
+from feishulib.events import MessageEvent
+
+config = FeishuConfig(app_id, secret)
+channel = EventChannel(config)
+
+async with FeishuClient(config) as client:
+    bot = await client.get_bot_identity()
+
+    async def on_message(event: MessageEvent) -> None:
+        if event.sender.open_id == bot.open_id:
+            return  # ignore messages from self
+        reply = reply_for_message(event)  # your logic
+        if reply and event.chat_id:
+            await client.send_text(event.chat_id, reply)
+
+    channel.on("message", on_message)
+
+    async with FeishuWebSocket(config, channel) as ws:
+        await ws.run_forever()
+```
+
+### Card Action Handling
+
+```python
+from feishulib import CardActionResponse, EventChannel, FeishuConfig, FeishuWebSocket, Toast
+from feishulib.events import CardActionEvent
+
+config = FeishuConfig(app_id, secret)
+channel = EventChannel(config)
+
+async def on_card_action(event: CardActionEvent) -> CardActionResponse:
+    print(f"Action from {event.operator.open_id}: {event.action_value}")
+    return CardActionResponse(toast=Toast(kind="success", content="Done"))
+
+channel.on("card_action", on_card_action)
+
+async with FeishuWebSocket(config, channel) as ws:
+    await ws.run_forever()
+```
+
+### Event Channel
+
+The `EventChannel` dispatches incoming events to registered handlers:
+
+| Method | Event | Handler signature | Notes |
+| --- | --- | --- | --- |
+| `channel.on("message", fn)` | `im.message.receive_v1` | `async (MessageEvent) -> None` | Multiple handlers allowed; run in registration order |
+| `channel.on("card_action", fn)` | `card.action.trigger` | `async (CardActionEvent) -> CardActionResponse \| None` | At most one handler |
+
+The card action handler can return a `CardActionResponse` with a toast, a card update, or both.
+
+### WebSocket Connection
+
+`FeishuWebSocket` manages the long-connection lifecycle:
+
+- Automatic endpoint discovery via `POST /callback/ws/endpoint`
+- Heartbeat via ping/pong frames
+- Exponential backoff reconnection with jitter on transient failures
+- Configurable open/close timeouts
+- Event ACK: valid events → `200`, handler failures → `503`, timeout → `500`
+- Unsupported or malformed events are acknowledged with `200` and dropped gracefully
+
+## Configuration
+
+```python
+from feishulib import FeishuConfig
+
+config = FeishuConfig(
+    app_id="cli_xxx",
+    app_secret="your_secret",
+    # Optional overrides (defaults shown):
+    base_url="https://open.feishu.cn",
+    request_timeout_seconds=10.0,
+    max_retries=3,
+    retry_backoff_base_seconds=0.5,
+    retry_max_delay_seconds=15.0,
+    retry_jitter_ratio=0.1,
+    token_refresh_skew_seconds=60.0,
+    ws_open_timeout_seconds=15.0,
+    ws_close_timeout_seconds=10.0,
+    ws_ping_timeout_seconds=180.0,
+    ws_reconnect_base_seconds=1.0,
+    ws_reconnect_max_seconds=60.0,
+    ws_reconnect_jitter_ratio=0.1,
+    event_queue_size=100,
+    event_worker_count=1,
+    card_action_timeout_seconds=8.0,
+)
+```
+
+`app_secret` is excluded from `repr()` to prevent accidental leakage in logs.
+
+## Error Handling
+
+All exceptions inherit from `FeishuError`:
+
+| Exception | When it occurs |
+| --- | --- |
+| `FeishuApiError` | Feishu API returned a non-zero business code |
+| `FeishuHttpStatusError` | HTTP response had a non-success status |
+| `FeishuTransientError` | Retryable transport failure exhausted retry budget |
+| `FeishuAuthError` | Tenant access token retrieval or validation failed |
+| `FeishuProtocolError` | Remote response did not match the expected protocol |
+| `FeishuWebSocketError` | WebSocket connection or frame exchange failed |
+| `FeishuEventParseError` | Incoming event could not be parsed |
+| `FeishuEventHandlerError` | Event handler failed or event dispatch could not proceed |
+
+## Security
+
+- **Card action identity** — always use `event.operator` for authentication. Values in `event.action.value` are user-controlled and must never be trusted as an identity source.
+- **Event payload** — malformed and unsupported events are acknowledged and dropped without dispatch. The client logs the parse error and event type, but never logs the raw event payload, credentials, or action values.
+- **Credentials** — `app_secret` is omitted from `FeishuConfig.__repr__`. Authorization headers are redacted in logs.
+
+## Development
+
+```bash
+# Clone and install
+git clone <repo>
+cd feishulib
+uv sync
+
+# Run quality gate
+bash scripts/verify
+
+# Individual checks
+uv run ruff check .
+uv run pyright
+uv run pytest --cov=src/feishulib --cov-report=term-missing
+```
+
+## License
+
+MIT

feishulib-0.1.2/pyproject.toml

@@ -0,0 +1,53 @@
+[project]
+name = "feishulib"
+version = "0.1.2"
+description = "Async Pythonic Feishu IM client"
+readme = "README.md"
+authors = [
+    { name = "morrisx", email = "ifme.in@gmail.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "httpx>=0.27",
+    "protobuf>=7.35.0,<8",
+    "websockets>=14",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.28,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv]
+cache-dir = ".cache/uv"
+
+[tool.uv.build-backend]
+module-name = "feishulib"
+
+[dependency-groups]
+dev = [
+    "grpcio-tools>=1.82.1,<1.83",
+    "pyright>=1.1.390",
+    "pytest>=8",
+    "pytest-asyncio>=0.24",
+    "pytest-cov>=5",
+    "ruff>=0.6",
+]
+
+[tool.pytest.ini_options]
+cache_dir = ".cache/.pytest_cache"
+
+[tool.ruff]
+cache-dir = ".cache/.ruff_cache"
+
+[tool.coverage.run]
+data_file = ".cache/.coverage"
+
+[tool.coverage.html]
+directory = ".cache/htmlcov"
+
+[tool.pyright]
+include = ["src/feishulib"]
+exclude = ["tests", "src/feishulib/proto"]
+pythonVersion = "3.12"
+typeCheckingMode = "strict"
+reportMissingTypeStubs = "none"

feishulib-0.1.2/src/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-0.1.2/src/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