lark-bridge 0.1.0__tar.gz

lark_bridge-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install -e ".[dev]"
+      - run: ruff check src/lark_bridge/*.py tests/
+      - run: ruff format --check src/lark_bridge/*.py tests/
+      - run: pytest

lark_bridge-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,19 @@
+name: Publish
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install hatchling build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

lark_bridge-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.env
+*.egg
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+
+.idea/

lark_bridge-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan Zhu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lark_bridge-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: lark-bridge
+Version: 0.1.0
+Summary: Unofficial Feishu/Lark Web SDK - WebSocket listener, message search, send, and drive operations
+Project-URL: Homepage, https://github.com/LiangFu/lark-bridge
+Project-URL: Repository, https://github.com/LiangFu/lark-bridge
+Author: Ryan Zhu
+License-Expression: MIT
+License-File: LICENSE
+Keywords: feishu,im,lark,protobuf,websocket
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: Chat
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: protobuf-to-dict>=0.1.0
+Requires-Dist: protobuf>=5.0.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# lark-bridge
+
+Unofficial Feishu/Lark Web SDK using cookie-based authentication. Provides real-time message listening via WebSocket, message search/fetch, sending, and Drive operations.
+
+> ⚠️ This library is reverse-engineered from Feishu's web client. It is **not** an official API and may break without notice.
+
+## Installation
+
+```bash
+pip install lark-bridge
+```
+
+## Quick Start
+
+```python
+import asyncio
+from lark_bridge import LarkBridge
+
+bridge = LarkBridge("your_cookie_string_here")
+```
+
+### Listen to Messages
+
+```python
+async def main():
+    async for msg in bridge.listen(watch_chats=["chat_id"]):
+        print(f"[{msg['chat_id']}] {msg['from_id']}: {msg['text']}")
+
+asyncio.run(main())
+```
+
+### Search History
+
+```python
+result = await bridge.search_messages(
+    chat_id="7052636707732193282",
+    start_time=1716192000,
+    end_time=1716278400,
+)
+print(result["msg_ids"])
+```
+
+### Fetch Messages
+
+```python
+messages = await bridge.fetch_messages(["msg_id_1", "msg_id_2"])
+for msg in messages:
+    print(msg["text"])
+```
+
+### Send Message
+
+```python
+await bridge.send_message(
+    chat_id="7052636707732193282",
+    text="Hello!",
+    reply_id="optional_msg_id",
+    at_user_ids=["user_id"],
+)
+```
+
+### Drive Operations
+
+```python
+folder = await bridge.create_folder("My Folder", parent_token="root_token")
+result = await bridge.upload_file(folder["token"], "report.txt", b"file content")
+```
+
+## Cookie Setup
+
+1. Open [Feishu Web](https://www.feishu.cn/) in your browser and log in
+2. Open DevTools (F12) → Application → Cookies
+3. Copy the full cookie string (all key=value pairs joined by `; `)
+4. Pass it to `LarkBridge("your_cookie_string")`
+
+Example cookie format:
+
+```python
+cookie = "passport_web_did=YOUR_DID; session=YOUR_SESSION; _csrf_token=YOUR_CSRF_TOKEN"
+
+bridge = LarkBridge(cookie)
+```
+
+Cookie typically stays valid as long as the WebSocket connection is maintained.
+
+## License
+
+[MIT](LICENSE)

lark_bridge-0.1.0/README.md

@@ -0,0 +1,88 @@
+# lark-bridge
+
+Unofficial Feishu/Lark Web SDK using cookie-based authentication. Provides real-time message listening via WebSocket, message search/fetch, sending, and Drive operations.
+
+> ⚠️ This library is reverse-engineered from Feishu's web client. It is **not** an official API and may break without notice.
+
+## Installation
+
+```bash
+pip install lark-bridge
+```
+
+## Quick Start
+
+```python
+import asyncio
+from lark_bridge import LarkBridge
+
+bridge = LarkBridge("your_cookie_string_here")
+```
+
+### Listen to Messages
+
+```python
+async def main():
+    async for msg in bridge.listen(watch_chats=["chat_id"]):
+        print(f"[{msg['chat_id']}] {msg['from_id']}: {msg['text']}")
+
+asyncio.run(main())
+```
+
+### Search History
+
+```python
+result = await bridge.search_messages(
+    chat_id="7052636707732193282",
+    start_time=1716192000,
+    end_time=1716278400,
+)
+print(result["msg_ids"])
+```
+
+### Fetch Messages
+
+```python
+messages = await bridge.fetch_messages(["msg_id_1", "msg_id_2"])
+for msg in messages:
+    print(msg["text"])
+```
+
+### Send Message
+
+```python
+await bridge.send_message(
+    chat_id="7052636707732193282",
+    text="Hello!",
+    reply_id="optional_msg_id",
+    at_user_ids=["user_id"],
+)
+```
+
+### Drive Operations
+
+```python
+folder = await bridge.create_folder("My Folder", parent_token="root_token")
+result = await bridge.upload_file(folder["token"], "report.txt", b"file content")
+```
+
+## Cookie Setup
+
+1. Open [Feishu Web](https://www.feishu.cn/) in your browser and log in
+2. Open DevTools (F12) → Application → Cookies
+3. Copy the full cookie string (all key=value pairs joined by `; `)
+4. Pass it to `LarkBridge("your_cookie_string")`
+
+Example cookie format:
+
+```python
+cookie = "passport_web_did=YOUR_DID; session=YOUR_SESSION; _csrf_token=YOUR_CSRF_TOKEN"
+
+bridge = LarkBridge(cookie)
+```
+
+Cookie typically stays valid as long as the WebSocket connection is maintained.
+
+## License
+
+[MIT](LICENSE)

lark_bridge-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "lark-bridge"
+version = "0.1.0"
+description = "Unofficial Feishu/Lark Web SDK - WebSocket listener, message search, send, and drive operations"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [
+    { name = "Ryan Zhu" },
+]
+keywords = ["feishu", "lark", "websocket", "protobuf", "im"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Communications :: Chat",
+]
+dependencies = [
+    "httpx>=0.27.0",
+    "websockets>=12.0",
+    "protobuf>=5.0.0",
+    "protobuf-to-dict>=0.1.0",
+]
+
+[project.optional-dependencies]
+dev = ["ruff>=0.5.0", "pytest>=8.0", "pytest-asyncio>=0.23"]
+
+[project.urls]
+Homepage = "https://github.com/LiangFu/lark-bridge"
+Repository = "https://github.com/LiangFu/lark-bridge"
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+exclude = ["**/proto/"]
+
+[tool.ruff.lint.per-file-ignores]
+"*_pb2.py" = ["ALL"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/lark_bridge"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

lark_bridge-0.1.0/src/lark_bridge/__init__.py

@@ -0,0 +1,6 @@
+"""lark-bridge: Unofficial Feishu/Lark Web SDK."""
+
+from lark_bridge.client import LarkBridge
+
+__all__ = ["LarkBridge"]
+__version__ = "0.1.0"

lark_bridge-0.1.0/src/lark_bridge/client.py

@@ -0,0 +1,64 @@
+"""Main LarkBridge client class."""
+
+from collections.abc import AsyncGenerator
+
+from lark_bridge import listener, search, sender, drive
+
+
+class LarkBridge:
+    """High-level Feishu/Lark client using web cookie authentication."""
+
+    def __init__(self, cookie: str):
+        self._cookie = cookie.strip()
+        self._cookies = self._parse_cookies(self._cookie)
+
+    @staticmethod
+    def _parse_cookies(cookie_str: str) -> dict[str, str]:
+        return dict(
+            item.split("=", 1) for item in cookie_str.split("; ") if "=" in item
+        )
+
+    async def listen(self, watch_chats: list[str] | None = None) -> AsyncGenerator[dict, None]:
+        """Connect to WebSocket and yield Message dicts."""
+        async for msg in listener.listen(self._cookie, self._cookies, watch_chats):
+            yield msg
+
+    async def search_messages(
+        self,
+        chat_id: str,
+        start_time: int = 0,
+        end_time: int = 0,
+        from_id: str = "",
+        mention_user_id: str = "",
+        limit: int = 15,
+    ) -> dict:
+        """Search message IDs. Returns {"msg_ids": [...], "has_more": bool}."""
+        return await search.search_msg_ids(
+            self._cookie, chat_id, start_time, end_time, from_id, mention_user_id, limit
+        )
+
+    async def fetch_messages(self, msg_ids: list[str]) -> list[dict]:
+        """Fetch message content by IDs."""
+        return await search.fetch_messages(self._cookie, msg_ids)
+
+    async def send_message(
+        self,
+        chat_id: str,
+        text: str,
+        reply_id: str = "",
+        at_user_ids: list[str] | None = None,
+    ) -> bool:
+        """Send a text message. Returns True on success."""
+        return await sender.send_message(self._cookie, chat_id, text, reply_id, at_user_ids)
+
+    async def create_folder(self, name: str, parent_token: str = "") -> dict | None:
+        """Create a Drive folder. Returns {"token", "url"} or None."""
+        return await drive.create_folder(self._cookie, self._cookies, name, parent_token)
+
+    async def upload_file(
+        self, folder_token: str, file_name: str, file_content: bytes
+    ) -> dict | None:
+        """Upload a file to Drive. Returns {"file_token", "node_token"} or None."""
+        return await drive.upload_file(
+            self._cookie, self._cookies, folder_token, file_name, file_content
+        )

lark_bridge-0.1.0/src/lark_bridge/decoder.py

@@ -0,0 +1,144 @@
+"""Text decoding for Feishu message protobuf content."""
+
+import json
+import re
+
+from google.protobuf.internal.decoder import _DecodeVarint
+
+from lark_bridge.proto import proto_pb2 as pb
+from protobuf_to_dict import protobuf_to_dict
+
+
+def decode_text(msg: dict) -> str:
+    """Extract text from a message dict (with 'type' and 'content' fields)."""
+    msg_type = msg.get("type", 0)
+    content = msg.get("content", b"")
+    if not content:
+        return ""
+    if msg_type == 4:
+        return decode_type4(content)
+    elif msg_type == 14:
+        return decode_type14(content)
+    return ""
+
+
+def decode_type4(content: bytes) -> str:
+    """Decode type=4 (plain text) message."""
+    try:
+        tc = pb.TextContent()
+        tc.ParseFromString(content)
+        tc_dict = protobuf_to_dict(tc)
+        rt = tc_dict.get("richText", {})
+        elements = rt.get("elements", {}).get("dictionary", {})
+        element_ids = rt.get("elementIds", [])
+        at_ids = set(rt.get("atIds", []))
+
+        def _extract(eid: str) -> str:
+            el = elements.get(eid, {})
+            prop = el.get("property", b"")
+            parts: list[str] = []
+            if prop:
+                tp = pb.TextProperty()
+                tp.ParseFromString(prop)
+                if eid in at_ids:
+                    parts.append(f"@({tp.content})")
+                elif tp.content:
+                    parts.append(tp.content)
+            for cid in el.get("childIds", []):
+                parts.append(_extract(cid))
+            return "".join(parts)
+
+        return "".join(_extract(eid) for eid in element_ids)
+    except Exception:
+        return ""
+
+
+def decode_type14(content: bytes) -> str:
+    """Decode type=14 (post/card) message."""
+    try:
+        title = ""
+        json_body = ""
+        pos = 0
+        while pos < len(content):
+            tag, new_pos = _DecodeVarint(content, pos)
+            fn = tag >> 3
+            wt = tag & 0x7
+            if wt == 0:
+                _, pos = _DecodeVarint(content, new_pos)
+            elif wt == 2:
+                length, pos = _DecodeVarint(content, new_pos)
+                val = content[pos : pos + length]
+                if fn == 20:
+                    json_body = val.decode("utf-8", errors="replace")
+                elif fn == 8:
+                    try:
+                        tp = 0
+                        _, tp = _DecodeVarint(val, tp)
+                        t_len, tp = _DecodeVarint(val, tp)
+                        title = val[tp : tp + t_len].decode("utf-8", errors="replace")
+                    except Exception:
+                        pass
+                pos += length
+            else:
+                break
+
+        if json_body:
+            body = json.loads(json_body)
+            parts: list[str] = []
+            for el in body.get("body", {}).get("elements", []):
+                tag_name = el.get("tag", "")
+                prop = el.get("property", {})
+                if tag_name == "markdown":
+                    for sub in prop.get("elements", []):
+                        sub_tag = sub.get("tag", "")
+                        sub_prop = sub.get("property", {})
+                        if sub_tag == "plain_text":
+                            parts.append(sub_prop.get("content", ""))
+                        elif sub_tag == "br":
+                            parts.append("\n")
+                        elif sub_tag == "a":
+                            parts.append(sub_prop.get("href", sub_prop.get("content", "")))
+                        elif sub_tag == "at":
+                            parts.append(f"@({sub_prop.get('userID', '')})")
+                        else:
+                            parts.append(sub_prop.get("content", ""))
+                elif tag_name == "plain_text":
+                    parts.append(prop.get("content", ""))
+                elif tag_name == "br":
+                    parts.append("\n")
+            text = "".join(parts)
+            if title:
+                text = f"{title}\n{text}"
+        else:
+            # Fallback: protobuf tree traversal
+            pos = 0
+            _, pos = _DecodeVarint(content, pos)
+            _, pos = _DecodeVarint(content, pos)
+            _, pos = _DecodeVarint(content, pos)
+            length, pos = _DecodeVarint(content, pos)
+            rt = pb.RichText()
+            rt.ParseFromString(content[pos : pos + length])
+            rt_dict = protobuf_to_dict(rt)
+            elems = rt_dict.get("elements", {}).get("dictionary", {})
+            eids = rt_dict.get("elementIds", [])
+
+            def _ext(eid: str) -> str:
+                el = elems.get(eid, {})
+                prop = el.get("property", b"")
+                p: list[str] = []
+                if prop:
+                    tp = pb.TextProperty()
+                    tp.ParseFromString(prop)
+                    if tp.content:
+                        p.append(tp.content)
+                for cid in el.get("childIds", []):
+                    p.append(_ext(cid))
+                return "".join(p)
+
+            text = "".join(_ext(eid) for eid in eids)
+            if title:
+                text = f"{title}\n{text}"
+
+        return re.sub(r"\x1b\[[0-9;]*m", "", text)
+    except Exception:
+        return ""

lark_bridge-0.1.0/src/lark_bridge/drive.py

@@ -0,0 +1,91 @@
+"""Feishu Drive operations: create folder, upload file."""
+
+import logging
+import zlib
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+
+async def create_folder(
+    cookie: str, cookies: dict[str, str], name: str, parent_token: str = ""
+) -> dict | None:
+    """Create a folder in Feishu Drive.
+
+    Returns {"token": "...", "url": "..."} or None.
+    """
+    try:
+        headers = {
+            "Cookie": cookie,
+            "content-type": "application/x-www-form-urlencoded",
+            "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
+            "x-csrftoken": cookies.get("_csrf_token", ""),
+            "referer": "https://ciloa.feishu.cn/",
+            "origin": "https://ciloa.feishu.cn",
+        }
+        data = f"parent_token={parent_token}&name={name}&desc=&source=0"
+        async with httpx.AsyncClient(headers=headers, verify=False, timeout=15) as client:
+            resp = await client.post(
+                "https://ciloa.feishu.cn/space/api/explorer/v2/create/folder/",
+                content=data,
+            )
+            result = resp.json()
+            if result.get("code") != 0:
+                logger.error(f"Create folder failed: {result.get('msg')}")
+                return None
+            nodes = result.get("data", {}).get("entities", {}).get("nodes", {})
+            node = next(iter(nodes.values()), {})
+            return {"token": node.get("token", ""), "url": node.get("url", "")}
+    except Exception as e:
+        logger.error(f"Create folder error: {e}")
+        return None
+
+
+async def upload_file(
+    cookie: str,
+    cookies: dict[str, str],
+    folder_token: str,
+    file_name: str,
+    file_content: bytes,
+) -> dict | None:
+    """Upload a file to Feishu Drive.
+
+    Returns {"file_token": "...", "node_token": "..."} or None.
+    """
+    try:
+        checksum = zlib.adler32(file_content) & 0xFFFFFFFF
+        params = {
+            "name": file_name,
+            "size": len(file_content),
+            "checksum": str(checksum),
+            "mount_node_token": folder_token,
+            "mount_point": "explorer",
+            "push_open_history_record": "1",
+            "size_checker": "true",
+        }
+        headers = {
+            "Cookie": cookie,
+            "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
+            "x-csrftoken": cookies.get("_csrf_token", ""),
+            "referer": "https://ciloa.feishu.cn/",
+            "origin": "https://ciloa.feishu.cn",
+        }
+        async with httpx.AsyncClient(headers=headers, verify=False, timeout=60) as client:
+            resp = await client.post(
+                "https://internal-api-drive-stream.feishu.cn/space/api/box/stream/upload/all/",
+                params=params,
+                files={"file": (file_name, file_content)},
+            )
+            result = resp.json()
+            if result.get("code") != 0:
+                logger.error(f"Upload file failed: {result.get('message')}")
+                return None
+            data = result.get("data", {})
+            return {
+                "file_token": data.get("file_token", ""),
+                "node_token": data.get("extra", {}).get("node_token", ""),
+            }
+    except Exception as e:
+        logger.error(f"Upload file error: {e}")
+        return None