xiaohongshu-matrices-cli 0.9.0__py3-none-any.whl

xhs_cli/__init__.py

@@ -0,0 +1,8 @@
+"""xiaohongshu-matrices-cli: Xiaohongshu CLI via reverse-engineered API."""
+
+try:
+    from importlib.metadata import version
+
+    __version__ = version("xiaohongshu-matrices-cli")
+except Exception:
+    __version__ = "0.0.0"

xhs_cli/__main__.py

@@ -0,0 +1,6 @@
+"""Module entry point for ``python -m xhs_cli``."""
+
+from .cli import cli
+
+if __name__ == "__main__":
+    cli()

xhs_cli/account_bridge.py

@@ -0,0 +1,143 @@
+"""Bridge between the dashboard (multi-account) and the CLI client.
+
+The dashboard stores each account's
+cookies in a Camoufox (Firefox) profile as an *encrypted* ``cookies.sqlite`` +
+``key4.db`` pair, while the CLI ``XhsClient`` only understands the flat
+``cookies.json`` file. There was no way to run CLI commands against a specific
+dashboard account without overwriting the global ``cookies.json`` (risk of
+cross-posting).
+
+This module closes the gap: given a dashboard account identifier it reads the
+profile's cookie database **offline** (``browser_cookie3.firefox`` does the
+DPAPI/NSS decryption in-process — no browser launch, no network) and returns a
+plain ``{name: value}`` dict the client can consume. It never writes
+``cookies.json``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .dashboard.config import DashboardConfig
+from .dashboard.db import Database
+from .exceptions import NoCookieError
+
+# Firefox-style profile cookie container used by Camoufox.
+_COOKIE_FILE = "cookies.sqlite"
+_KEY_FILE = "key4.db"
+
+
+def _load_database() -> Database | None:
+    """Best-effort open of the dashboard DB; None if dashboard is unused."""
+    try:
+        cfg = DashboardConfig.load()
+    except Exception:  # dashboard not configured / unreadable
+        return None
+    # Guard: do not *create* a dashboard just because --account was passed.
+    if not cfg.database_path.exists():
+        return None
+    try:
+        return Database(cfg.database_path)
+    except Exception:
+        return None
+
+
+def _resolve_account(db: Database, identifier: str | int) -> dict[str, Any]:
+    """Find an account row by int id, alias, or xhs_user_id (in that order)."""
+    # Numeric id lookup first (most precise).
+    if isinstance(identifier, int) or (isinstance(identifier, str) and identifier.isdigit()):
+        row = db.fetchone("SELECT * FROM accounts WHERE id=?", (int(identifier),))
+        if row:
+            return row
+    ident = str(identifier)
+    row = db.fetchone(
+        "SELECT * FROM accounts WHERE alias=? OR xhs_user_id=?",
+        (ident, ident),
+    )
+    if not row:
+        raise NoCookieError(
+            f"dashboard 账号不存在: {identifier!r} "
+            f"（可用 `xhs status` 查看已登录账号，或用 --account <id/别名/xhs_user_id>）"
+        )
+    return row
+
+
+def get_dashboard_account_cookies(identifier: str | int) -> dict[str, str]:
+    """Return cookies for a dashboard account, decrypting its profile offline.
+
+    Args:
+        identifier: dashboard account ``id`` (int/str), ``alias``, or
+            ``xhs_user_id``.
+
+    Returns:
+        ``{cookie_name: cookie_value}`` dict suitable for ``XhsClient(cookies)``.
+
+    Raises:
+        NoCookieError: if the account is unknown, has no cookie files, or the
+            cookies lack the ``a1`` session token (i.e. the login has expired).
+    """
+    db = _load_database()
+    if db is None:
+        raise NoCookieError(
+            "未找到 dashboard 数据（~/.xiaohongshu-cli/dashboard）。"
+            "请先在 http://127.0.0.1:8765 扫码登录，或改用 cookies.json 登录。"
+        )
+    row = _resolve_account(db, identifier)
+    account_label = row.get("alias") or row.get("xhs_user_id") or str(row.get("id"))
+
+    profile_dir = row.get("profile_dir")
+    if not profile_dir:
+        raise NoCookieError(f"账号 {account_label} 没有关联浏览器 profile，请重新扫码登录")
+    base = Path(profile_dir).expanduser().resolve()
+    cookie_file = base / _COOKIE_FILE
+    key_file = base / _KEY_FILE
+    if not (cookie_file.exists() and key_file.exists()):
+        raise NoCookieError(
+            f"账号 {account_label} 的 cookie 文件缺失，请先在 dashboard 重新扫码登录"
+        )
+
+    import browser_cookie3
+
+    try:
+        jar = browser_cookie3.firefox(
+            cookie_file=str(cookie_file),
+            key_file=str(key_file),
+            domain_name="xiaohongshu.com",
+        )
+    except Exception as exc:  # decryption failure (e.g. profile locked)
+        raise NoCookieError(f"账号 {account_label} 的 cookie 解密失败：{exc}") from exc
+
+    cookies = {c.name: c.value for c in jar}
+    if not cookies.get("a1"):
+        raise NoCookieError(f"账号 {account_label} 的登录态已失效（缺少 a1 token），请重新扫码登录")
+    return cookies
+
+
+def list_dashboard_accounts() -> list[dict[str, Any]]:
+    """Read-only listing of dashboard accounts (for `xhs status`).
+
+    Returns an empty list when the dashboard is not initialised, so callers can
+    treat absence gracefully without side effects.
+    """
+    db = _load_database()
+    if db is None:
+        return []
+    rows = db.fetchall(
+        "SELECT id, alias, xhs_user_id, nickname, login_status, profile_dir "
+        "FROM accounts ORDER BY id"
+    )
+    accounts = []
+    for r in rows:
+        cookie_file = Path(r.get("profile_dir", "")) / _COOKIE_FILE
+        accounts.append(
+            {
+                "id": r.get("id"),
+                "alias": r.get("alias"),
+                "xhs_user_id": r.get("xhs_user_id"),
+                "nickname": r.get("nickname"),
+                "login_status": r.get("login_status"),
+                "has_cookie_file": cookie_file.exists(),
+            }
+        )
+    return accounts

xhs_cli/cli.py

@@ -0,0 +1,153 @@
+"""CLI entry point for xiaohongshu-matrices-cli.
+
+Usage:
+    xhs login / status / logout
+    xhs search <keyword> [--sort popular|latest] [--type video|image] [--page N]
+    xhs read <id_or_url> [--xsec-token TOKEN]
+    xhs comments <id_or_url>
+    xhs user <user_id>
+    xhs user-posts <user_id> [--cursor CURSOR]
+    xhs feed
+    xhs hot [--category CATEGORY]
+    xhs topics <keyword>
+    xhs like <id_or_url> [--undo]
+    xhs favorite <id_or_url>
+    xhs unfavorite <id_or_url>
+    xhs comment <id_or_url> --content "..."
+    xhs reply <id_or_url> --comment-id ID --content "..."
+    xhs favorites [user_id]
+    xhs my-notes [--page N]
+    xhs notifications [--type mentions|likes|connections]
+    xhs unread
+    xhs post --title "..." --body "..." --images img.png
+    xhs delete <id_or_url> [-y]
+
+Global options:
+    --account <id|别名|xhs_user_id>   指定 dashboard 账号，自动桥接其 cookie
+    --cookie-source <browser>         从浏览器读取 cookie（默认 auto）
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+
+import click
+
+from . import __version__
+from .commands import auth, creator, interactions, notifications, reading, social
+
+
+def _fix_windows_encoding() -> None:
+    """Force UTF-8 on Windows where the default codepage (936/GBK) garbles output."""
+    if sys.platform != "win32":
+        return
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding="utf-8", errors="replace")
+
+
+def _check_signing_libs() -> None:
+    """Warn if signing dependencies look outdated or broken (non-blocking)."""
+    try:
+        import pkg_resources
+    except ImportError:
+        return
+    for pkg, min_version in [("xhshow", "0.1.9"), ("pycryptodome", "3.20")]:
+        try:
+            dist = pkg_resources.get_distribution(pkg)
+            parsed = pkg_resources.parse_version
+            if parsed(dist.version) < parsed(min_version):
+                logging.warning(
+                    "%s %s 低于建议版本 %s，签名可能失效", pkg, dist.version, min_version
+                )
+        except pkg_resources.DistributionNotFound:
+            logging.warning("缺少签名依赖 %s，功能可能不可用", pkg)
+
+
+_fix_windows_encoding()
+try:
+    _check_signing_libs()
+except Exception:
+    pass  # 非关键路径，不影响功能
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="xhs")
+@click.option("-v", "--verbose", is_flag=True, help="Enable debug logging")
+@click.option(
+    "--cookie-source",
+    type=str,
+    default="auto",
+    show_default=True,
+    help="Browser to read cookies from (auto = try all installed browsers)",
+)
+@click.option(
+    "--account",
+    type=str,
+    default=None,
+    help="目标 dashboard 账号（id / 别名 / xhs_user_id）。指定后自动桥接该账号的 cookie，"
+    "无需修改全局 cookies.json",
+)
+@click.pass_context
+def cli(ctx, verbose: bool, cookie_source: str, account: str | None):
+    """xhs — Xiaohongshu CLI via reverse-engineered API 📕"""
+    ctx.ensure_object(dict)
+    ctx.obj["cookie_source"] = cookie_source
+    ctx.obj["account"] = account
+
+    if verbose:
+        logging.basicConfig(level=logging.DEBUG, format="%(name)s %(message)s")
+    else:
+        logging.basicConfig(level=logging.WARNING)
+
+
+# ─── Auth commands ───────────────────────────────────────────────────────────
+
+cli.add_command(auth.login)
+cli.add_command(auth.status)
+cli.add_command(auth.logout)
+cli.add_command(auth.whoami)
+
+# ─── Reading commands ────────────────────────────────────────────────────────
+
+cli.add_command(reading.search)
+cli.add_command(reading.read)
+cli.add_command(reading.comments)
+cli.add_command(reading.sub_comments)
+cli.add_command(reading.user)
+cli.add_command(reading.user_posts)
+cli.add_command(reading.feed)
+cli.add_command(reading.hot)
+cli.add_command(reading.topics)
+cli.add_command(reading.search_user)
+
+# ─── Interaction commands ────────────────────────────────────────────────────
+
+cli.add_command(interactions.like)
+cli.add_command(interactions.favorite)
+cli.add_command(interactions.unfavorite)
+cli.add_command(interactions.comment)
+cli.add_command(interactions.reply)
+cli.add_command(interactions.delete_comment)
+
+# ─── Social commands ────────────────────────────────────────────────────────
+
+cli.add_command(social.follow)
+cli.add_command(social.unfollow)
+cli.add_command(social.favorites)
+cli.add_command(social.likes)
+
+# ─── Creator commands ───────────────────────────────────────────────────────
+
+cli.add_command(creator.post)
+cli.add_command(creator.my_notes)
+cli.add_command(creator.delete)
+
+# ─── Notification commands ──────────────────────────────────────────────────
+
+cli.add_command(notifications.notifications)
+cli.add_command(notifications.unread)
+
+if __name__ == "__main__":
+    cli()

xhs_cli/client.py

@@ -0,0 +1,264 @@
+"""
+XHS API client transport, signing, and retry primitives.
+
+Domain-specific endpoint methods live in ``client_mixins.py``.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import random
+import time
+from typing import Any
+
+import httpx
+
+from .client_mixins import (
+    AuthEndpointsMixin,
+    CreatorEndpointsMixin,
+    InteractionEndpointsMixin,
+    NotificationEndpointsMixin,
+    ReadingEndpointsMixin,
+    SocialEndpointsMixin,
+)
+from .constants import CHROME_VERSION, CREATOR_HOST, EDITH_HOST, HOME_URL, USER_AGENT
+from .cookies import cookies_to_string
+from .creator_signing import sign_creator
+from .exceptions import (
+    IpBlockedError,
+    NeedVerifyError,
+    SessionExpiredError,
+    SignatureError,
+    XhsApiError,
+)
+from .signing import build_get_uri, sign_main_api
+
+logger = logging.getLogger(__name__)
+
+
+class XhsClient(
+    ReadingEndpointsMixin,
+    InteractionEndpointsMixin,
+    CreatorEndpointsMixin,
+    SocialEndpointsMixin,
+    NotificationEndpointsMixin,
+    AuthEndpointsMixin,
+):
+    """Xiaohongshu API client with automatic signing, rate limiting, and retry."""
+
+    def __init__(
+        self,
+        cookies: dict[str, str],
+        timeout: float = 30.0,
+        request_delay: float = 1.0,
+        max_retries: int = 3,
+    ):
+        self.cookies = cookies
+        self._http = httpx.Client(timeout=timeout, follow_redirects=True)
+        self._request_delay = request_delay
+        self._base_request_delay = request_delay
+        self._max_retries = max_retries
+        self._last_request_time = 0.0
+        self._verify_count = 0
+        self._request_count = 0
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+    def _rate_limit_delay(self) -> None:
+        """Enforce minimum delay with Gaussian jitter to mimic human browsing."""
+        if self._request_delay <= 0:
+            return
+        elapsed = time.time() - self._last_request_time
+        if elapsed < self._request_delay:
+            jitter = max(0, random.gauss(0.3, 0.15))
+            if random.random() < 0.05:
+                jitter += random.uniform(2.0, 5.0)
+            sleep_time = self._request_delay - elapsed + jitter
+            logger.debug("Rate-limit delay: %.2fs", sleep_time)
+            time.sleep(sleep_time)
+
+    def _mark_request(self) -> None:
+        self._last_request_time = time.time()
+        self._request_count += 1
+
+    def _base_headers(self) -> dict[str, str]:
+        return {
+            "user-agent": USER_AGENT,
+            "content-type": "application/json;charset=UTF-8",
+            "cookie": cookies_to_string(self.cookies),
+            "origin": HOME_URL,
+            "referer": f"{HOME_URL}/",
+            "sec-ch-ua": f'"Not:A-Brand";v="99", "Google Chrome";v="{CHROME_VERSION}", "Chromium";v="{CHROME_VERSION}"',
+            "sec-ch-ua-mobile": "?0",
+            "sec-ch-ua-platform": '"macOS"',
+            "sec-fetch-dest": "empty",
+            "sec-fetch-mode": "cors",
+            "sec-fetch-site": "same-site",
+            "accept": "application/json, text/plain, */*",
+            "accept-language": "zh-CN,zh;q=0.9,en;q=0.8",
+            "dnt": "1",
+            "priority": "u=1, i",
+        }
+
+    def _handle_response(self, resp: httpx.Response) -> Any:
+        if resp.status_code in (461, 471):
+            self._verify_count += 1
+            cooldown = min(30, 5 * (2 ** (self._verify_count - 1)))
+            logger.warning(
+                "Captcha triggered (count=%d), cooling down %.0fs before raising",
+                self._verify_count,
+                cooldown,
+            )
+            self._request_delay = max(self._request_delay, self._base_request_delay * 2)
+            time.sleep(cooldown)
+            raise NeedVerifyError(
+                verify_type=resp.headers.get("verifytype", "unknown"),
+                verify_uuid=resp.headers.get("verifyuuid", "unknown"),
+            )
+
+        self._verify_count = 0
+        text = resp.text
+        if not text:
+            return None
+
+        try:
+            data = json.loads(text)
+        except json.JSONDecodeError:
+            raise XhsApiError(f"Non-JSON response: {text[:200]}") from None
+
+        if data.get("success"):
+            return data.get("data", data.get("success"))
+
+        code = data.get("code")
+        if code == 300012:
+            raise IpBlockedError()
+        if code == 300015:
+            raise SignatureError()
+        if code == -100:
+            raise SessionExpiredError()
+
+        raise XhsApiError(
+            f"API error: {json.dumps(data)[:300]}",
+            code=code,
+            response=data,
+        )
+
+    def _merge_response_cookies(self, resp: httpx.Response) -> None:
+        """Persist response cookies back into the in-memory session jar."""
+        for name, value in resp.cookies.items():
+            if not value:
+                continue
+            self.cookies[name] = value
+
+    def _request_with_retry(self, method: str, url: str, **kwargs) -> httpx.Response:
+        self._rate_limit_delay()
+        last_exc: Exception | None = None
+
+        for attempt in range(self._max_retries):
+            try:
+                resp = self._http.request(method, url, **kwargs)
+                self._merge_response_cookies(resp)
+                self._mark_request()
+                if resp.status_code in (429, 500, 502, 503, 504):
+                    wait = (2**attempt) + random.uniform(0, 1)
+                    logger.warning(
+                        "HTTP %d from %s, retrying in %.1fs (attempt %d/%d)",
+                        resp.status_code,
+                        url[:80],
+                        wait,
+                        attempt + 1,
+                        self._max_retries,
+                    )
+                    time.sleep(wait)
+                    continue
+                return resp
+            except (httpx.TimeoutException, httpx.NetworkError) as exc:
+                last_exc = exc
+                wait = (2**attempt) + random.uniform(0, 1)
+                logger.warning(
+                    "Network error: %s, retrying in %.1fs (attempt %d/%d)",
+                    exc,
+                    wait,
+                    attempt + 1,
+                    self._max_retries,
+                )
+                time.sleep(wait)
+
+        if last_exc:
+            raise XhsApiError(f"Request failed after {self._max_retries} retries: {last_exc}") from last_exc
+        raise XhsApiError(f"Request failed after {self._max_retries} retries: HTTP {resp.status_code}")
+
+    def _main_api_get(
+        self,
+        uri: str,
+        params: dict[str, str | int | list[str]] | None = None,
+    ) -> Any:
+        sign_headers = sign_main_api("GET", uri, self.cookies, params=params)
+        full_uri = build_get_uri(uri, params)
+        url = f"{EDITH_HOST}{full_uri}"
+        logger.debug("GET %s", url)
+        resp = self._request_with_retry("GET", url, headers={**self._base_headers(), **sign_headers})
+        return self._handle_response(resp)
+
+    def _main_api_post(
+        self,
+        uri: str,
+        data: dict[str, Any],
+        header_overrides: dict[str, str] | None = None,
+    ) -> Any:
+        sign_headers = sign_main_api("POST", uri, self.cookies, payload=data)
+        url = f"{EDITH_HOST}{uri}"
+        headers = {**self._base_headers(), **sign_headers}
+        if header_overrides:
+            headers.update(header_overrides)
+        logger.debug("POST %s", url)
+        body = json.dumps(data, separators=(",", ":"), ensure_ascii=False)
+        resp = self._request_with_retry("POST", url, headers=headers, content=body)
+        return self._handle_response(resp)
+
+    def _creator_host(self, uri: str) -> str:
+        return CREATOR_HOST if uri.startswith("/api/galaxy/") else EDITH_HOST
+
+    def _creator_get(
+        self,
+        uri: str,
+        params: dict[str, str | int] | None = None,
+    ) -> Any:
+        full_uri = build_get_uri(uri, params)
+        sign = sign_creator(f"url={full_uri}", None, self.cookies["a1"])
+        host = self._creator_host(uri)
+        url = f"{host}{full_uri}"
+        headers = {
+            **self._base_headers(),
+            "x-s": sign["x-s"],
+            "x-t": sign["x-t"],
+            "origin": CREATOR_HOST,
+            "referer": f"{CREATOR_HOST}/",
+        }
+        logger.debug("Creator GET %s", url)
+        resp = self._request_with_retry("GET", url, headers=headers)
+        return self._handle_response(resp)
+
+    def _creator_post(self, uri: str, data: dict[str, Any]) -> Any:
+        sign = sign_creator(f"url={uri}", data, self.cookies["a1"])
+        host = self._creator_host(uri)
+        url = f"{host}{uri}"
+        headers = {
+            **self._base_headers(),
+            "x-s": sign["x-s"],
+            "x-t": sign["x-t"],
+            "origin": CREATOR_HOST,
+            "referer": f"{CREATOR_HOST}/",
+        }
+        logger.debug("Creator POST %s", url)
+        body = json.dumps(data, separators=(",", ":"), ensure_ascii=False)
+        resp = self._request_with_retry("POST", url, headers=headers, content=body)
+        return self._handle_response(resp)