This commit is contained in:
Ubuntu
2026-07-03 16:58:28 +08:00
commit 32b43f85bd
6240 changed files with 1987678 additions and 0 deletions
@@ -0,0 +1,8 @@
"""xiaohongshu-cli: Xiaohongshu CLI via reverse-engineered API."""
try:
from importlib.metadata import version
__version__ = version("xiaohongshu-cli")
except Exception:
__version__ = "0.0.0"
@@ -0,0 +1,6 @@
"""Module entry point for ``python -m xhs_cli``."""
from .cli import cli
if __name__ == "__main__":
cli()
+105
View File
@@ -0,0 +1,105 @@
"""CLI entry point for xiaohongshu-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]
"""
from __future__ import annotations
import logging
import click
from . import __version__
from .commands import auth, creator, interactions, notifications, reading, social
@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.pass_context
def cli(ctx, verbose: bool, cookie_source: str):
"""xhs — Xiaohongshu CLI via reverse-engineered API 📕"""
ctx.ensure_object(dict)
ctx.obj["cookie_source"] = cookie_source
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)
# ─── 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()
+256
View File
@@ -0,0 +1,256 @@
"""
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)
@@ -0,0 +1,694 @@
"""Domain-specific endpoint mixins for XhsClient."""
from __future__ import annotations
import json
import logging
import mimetypes
import random
import re
import threading
import time
from collections import OrderedDict
from pathlib import Path
from typing import Any
from .constants import CREATOR_HOST, HOME_URL, UPLOAD_HOST, USER_AGENT
from .cookies import (
cache_note_context,
cookies_to_string,
get_cached_note_context,
get_config_dir,
invalidate_note_context,
)
from .exceptions import NeedVerifyError, UnsupportedOperationError, XhsApiError
from .html_parser import extract_note_from_html
logger = logging.getLogger(__name__)
_SEARCH_DEFAULT_FILTERS = [
{"tags": ["general"], "type": "sort_type"},
{"tags": ["不限"], "type": "filter_note_type"},
{"tags": ["不限"], "type": "filter_note_time"},
{"tags": ["不限"], "type": "filter_note_range"},
{"tags": ["不限"], "type": "filter_pos_distance"},
]
_SEARCH_SESSION_TTL_SECONDS = 600
_SEARCH_SESSION_MAX_SIZE = 128
_SEARCH_SESSION_LOCK = threading.RLock()
_SEARCH_SESSION_CACHE: OrderedDict[tuple[str, str, int], dict[str, Any]] = OrderedDict()
_SEARCH_SESSION_CACHE_PATH: Path | None = None
_SEARCH_SESSION_CACHE_LOADED = False
def _generate_search_id() -> str:
"""Generate a unique search ID (base36 of timestamp << 64 + random)."""
e = int(time.time() * 1000) << 64
t = random.randint(0, 2147483646)
num = e + t
alphabet = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"
if num == 0:
return "0"
result = ""
while num > 0:
result = alphabet[num % 36] + result
num //= 36
return result
def _search_session_key(keyword: str, sort: str, note_type: int) -> tuple[str, str, int]:
return (keyword.strip(), sort, note_type)
def _search_session_path() -> Path:
return get_config_dir() / "search_sessions.json"
def _serialize_search_session_key(key: tuple[str, str, int]) -> str:
return json.dumps([key[0], key[1], key[2]], ensure_ascii=False)
def _deserialize_search_session_key(value: str) -> tuple[str, str, int] | None:
try:
keyword, sort, note_type = json.loads(value)
except (TypeError, ValueError, json.JSONDecodeError):
return None
if not isinstance(keyword, str) or not isinstance(sort, str):
return None
try:
normalized_note_type = int(note_type)
except (TypeError, ValueError):
return None
return (keyword, sort, normalized_note_type)
def _load_search_session_cache_from_disk(path: Path) -> OrderedDict[tuple[str, str, int], dict[str, Any]]:
if not path.exists():
return OrderedDict()
try:
data = json.loads(path.read_text())
except (OSError, json.JSONDecodeError):
return OrderedDict()
if not isinstance(data, dict):
return OrderedDict()
normalized: list[tuple[tuple[str, str, int], dict[str, Any]]] = []
for raw_key, value in data.items():
key = _deserialize_search_session_key(raw_key)
if not key or not isinstance(value, dict):
continue
if not value.get("search_id"):
continue
normalized.append((key, {
"search_id": str(value["search_id"]),
"created_at": float(value.get("created_at", 0) or 0),
"last_used_at": float(value.get("last_used_at", 0) or 0),
}))
normalized.sort(key=lambda item: float(item[1].get("last_used_at", 0)))
return OrderedDict(normalized)
def _save_search_session_cache(path: Path) -> None:
payload = OrderedDict(
(
_serialize_search_session_key(key),
dict(value),
)
for key, value in _SEARCH_SESSION_CACHE.items()
)
path.write_text(json.dumps(payload, indent=2, ensure_ascii=False))
path.chmod(0o600)
def _ensure_search_session_cache_loaded() -> None:
global _SEARCH_SESSION_CACHE_LOADED, _SEARCH_SESSION_CACHE_PATH, _SEARCH_SESSION_CACHE
path = _search_session_path()
if _SEARCH_SESSION_CACHE_LOADED and _SEARCH_SESSION_CACHE_PATH == path:
return
_SEARCH_SESSION_CACHE = _load_search_session_cache_from_disk(path)
_SEARCH_SESSION_CACHE_PATH = path
_SEARCH_SESSION_CACHE_LOADED = True
def _prune_search_sessions(now: float) -> None:
expired_keys = [
key
for key, value in _SEARCH_SESSION_CACHE.items()
if now - float(value.get("last_used_at", 0)) > _SEARCH_SESSION_TTL_SECONDS
]
for key in expired_keys:
_SEARCH_SESSION_CACHE.pop(key, None)
while len(_SEARCH_SESSION_CACHE) > _SEARCH_SESSION_MAX_SIZE:
_SEARCH_SESSION_CACHE.popitem(last=False)
def _acquire_search_session(keyword: str, sort: str, note_type: int) -> tuple[str, bool]:
now = time.time()
key = _search_session_key(keyword, sort, note_type)
with _SEARCH_SESSION_LOCK:
_ensure_search_session_cache_loaded()
_prune_search_sessions(now)
existing = _SEARCH_SESSION_CACHE.get(key)
if existing:
existing["last_used_at"] = now
_SEARCH_SESSION_CACHE.move_to_end(key)
_save_search_session_cache(_SEARCH_SESSION_CACHE_PATH or _search_session_path())
return str(existing["search_id"]), False
search_id = _generate_search_id()
_SEARCH_SESSION_CACHE[key] = {
"search_id": search_id,
"created_at": now,
"last_used_at": now,
}
_save_search_session_cache(_SEARCH_SESSION_CACHE_PATH or _search_session_path())
return search_id, True
def get_search_session_stats() -> dict[str, Any]:
"""Return lightweight debug stats for the in-memory search session cache."""
now = time.time()
with _SEARCH_SESSION_LOCK:
_ensure_search_session_cache_loaded()
_prune_search_sessions(now)
if not _SEARCH_SESSION_CACHE:
return {
"active_count": 0,
"last_keyword": "",
"last_sort": "",
"last_note_type": None,
}
last_key = next(reversed(_SEARCH_SESSION_CACHE))
return {
"active_count": len(_SEARCH_SESSION_CACHE),
"last_keyword": last_key[0],
"last_sort": last_key[1],
"last_note_type": last_key[2],
}
class ReadingEndpointsMixin:
"""Read-only note, profile, and discovery endpoints."""
def _search_request_id(self) -> str:
return f"{random.randint(1_000_000_000, 2_147_483_647)}-{int(time.time() * 1000)}"
def _fetch_note_html(
self,
note_id: str,
xsec_token: str = "",
xsec_source: str = "pc_feed",
) -> str:
if xsec_token:
url = f"{HOME_URL}/explore/{note_id}?xsec_token={xsec_token}&xsec_source={xsec_source}"
else:
url = f"{HOME_URL}/explore/{note_id}"
resp = self._request_with_retry(
"GET",
url,
headers={
"user-agent": USER_AGENT,
"referer": f"{HOME_URL}/",
"cookie": cookies_to_string(self.cookies),
},
)
return resp.text
def resolve_xsec_context(
self,
note_id: str,
preferred_token: str = "",
preferred_source: str = "",
) -> tuple[str, str]:
"""Resolve xsec_token/xsec_source from input, cache, or note page metadata."""
if preferred_token:
cache_note_context(note_id, preferred_token, preferred_source)
return preferred_token, preferred_source
cached = get_cached_note_context(note_id)
if cached.get("token"):
return cached["token"], cached.get("source", "")
html = self._fetch_note_html(note_id)
patterns = [
r'"xsec_token"\s*:\s*"([^"]+)"',
r"xsec_token=([^&\"']+)",
r"'xsec_token':'([^']+)'",
]
for pattern in patterns:
match = re.search(pattern, html)
if match:
token = match.group(1)
source_match = re.search(r"xsec_source=([^&\"']+)", html)
source = source_match.group(1) if source_match else preferred_source
cache_note_context(note_id, token, source)
return token, source
return "", preferred_source
def resolve_xsec_token(self, note_id: str, preferred_token: str = "") -> str:
"""Resolve xsec_token from explicit input, cache, or note page metadata."""
token, _source = self.resolve_xsec_context(note_id, preferred_token)
return token
def get_self_info(self) -> dict[str, Any]:
return self._main_api_get("/api/sns/web/v2/user/me")
def get_user_info(self, user_id: str) -> dict[str, Any]:
return self._main_api_get("/api/sns/web/v1/user/otherinfo", {
"target_user_id": user_id,
})
def get_user_notes(self, user_id: str, cursor: str = "") -> dict[str, Any]:
return self._main_api_get("/api/sns/web/v1/user_posted", {
"num": 30,
"cursor": cursor,
"user_id": user_id,
"image_scenes": "FD_WM_WEBP",
})
def search_notes(
self,
keyword: str,
page: int = 1,
page_size: int = 20,
sort: str = "general",
note_type: int = 0,
) -> Any:
search_id, is_new_session = _acquire_search_session(keyword, sort, note_type)
if is_new_session:
request_id = self._search_request_id()
try:
self._main_api_post("/api/sns/web/v1/search/onebox", {
"keyword": keyword,
"search_id": search_id,
"biz_type": "web_search_user",
"request_id": request_id,
})
self._main_api_get("/api/sns/web/v1/search/filter", {
"keyword": keyword,
"search_id": search_id,
})
except XhsApiError as exc:
logger.debug("Search prewarm failed, continuing with search/notes: %s", exc)
result = self._main_api_post("/api/sns/web/v1/search/notes", {
"keyword": keyword,
"page": page,
"page_size": page_size,
"search_id": search_id,
"sort": sort,
"note_type": note_type,
"ext_flags": [],
"filters": _SEARCH_DEFAULT_FILTERS,
"geo": "",
"image_formats": ["jpg", "webp", "avif"],
})
if is_new_session:
try:
self._main_api_get("/api/sns/web/v1/search/recommend", {"keyword": keyword})
except XhsApiError as exc:
logger.debug("Search recommend prefetch failed: %s", exc)
return result
def get_note_by_id(
self,
note_id: str,
xsec_token: str = "",
xsec_source: str = "pc_feed",
) -> Any:
if xsec_token:
cache_note_context(note_id, xsec_token, xsec_source)
return self._main_api_post("/api/sns/web/v1/feed", {
"source_note_id": note_id,
"image_formats": ["jpg", "webp", "avif"],
"extra": {"need_body_topic": "1"},
"xsec_source": xsec_source,
"xsec_token": xsec_token,
})
def get_note_from_html(
self,
note_id: str,
xsec_token: str = "",
xsec_source: str = "pc_feed",
) -> dict[str, Any]:
"""Fetch note by parsing server-rendered HTML (no xsec_token required)."""
html = self._fetch_note_html(note_id, xsec_token=xsec_token, xsec_source=xsec_source)
return extract_note_from_html(html, note_id)
def get_note_detail(
self,
note_id: str,
xsec_token: str = "",
xsec_source: str = "",
) -> dict[str, Any]:
"""Read a note via the best available channel.
Strategy:
- Has xsec_token → try feed API first, fall back to HTML on error
- No xsec_token → go straight to HTML (feed API would reject)
"""
cached = get_cached_note_context(note_id)
token = xsec_token or cached.get("token", "")
source = xsec_source or cached.get("source", "") or "pc_feed"
used_cached_context = not xsec_token and bool(cached.get("token"))
if token:
try:
return self.get_note_by_id(note_id, xsec_token=token, xsec_source=source)
except (NeedVerifyError, XhsApiError) as exc:
logger.info("Feed API failed (%s), falling back to HTML", exc)
if used_cached_context:
invalidate_note_context(note_id)
token = ""
return self.get_note_from_html(note_id, xsec_token=token or "", xsec_source=source)
def get_home_feed(self, category: str = "homefeed_recommend") -> dict[str, Any]:
return self._main_api_post("/api/sns/web/v1/homefeed", {
"cursor_score": "",
"num": 40,
"refresh_type": 1,
"note_index": 0,
"unread_begin_note_id": "",
"unread_end_note_id": "",
"unread_note_count": 0,
"category": category,
"search_key": "",
"need_num": 40,
"image_scenes": ["FD_PRV_WEBP", "FD_WM_WEBP"],
})
def get_hot_feed(self, category: str = "homefeed.fashion_v3") -> dict[str, Any]:
return self.get_home_feed(category=category)
def get_comments(
self,
note_id: str,
cursor: str = "",
xsec_token: str = "",
top_comment_id: str = "",
xsec_source: str = "",
) -> Any:
cached = get_cached_note_context(note_id)
used_cached_context = not xsec_token and bool(cached.get("token"))
token, source = self.resolve_xsec_context(note_id, xsec_token, xsec_source)
if not token:
raise XhsApiError(
"Could not resolve xsec_token for comments. Pass a full note URL or --xsec-token explicitly."
)
if source:
cache_note_context(note_id, token, source)
try:
return self._main_api_get("/api/sns/web/v2/comment/page", {
"note_id": note_id,
"cursor": cursor,
"top_comment_id": top_comment_id,
"image_formats": "jpg,webp,avif",
"xsec_token": token,
})
except (NeedVerifyError, XhsApiError):
if not used_cached_context:
raise
invalidate_note_context(note_id)
refreshed_token, refreshed_source = self.resolve_xsec_context(note_id, "", xsec_source)
if not refreshed_token:
raise
if refreshed_source:
cache_note_context(note_id, refreshed_token, refreshed_source)
return self._main_api_get("/api/sns/web/v2/comment/page", {
"note_id": note_id,
"cursor": cursor,
"top_comment_id": top_comment_id,
"image_formats": "jpg,webp,avif",
"xsec_token": refreshed_token,
})
def get_all_comments(
self,
note_id: str,
xsec_token: str = "",
xsec_source: str = "",
max_pages: int = 20,
) -> dict[str, Any]:
all_comments: list[dict[str, Any]] = []
cursor = ""
pages = 0
while pages < max_pages:
data = self.get_comments(
note_id,
cursor=cursor,
xsec_token=xsec_token,
xsec_source=xsec_source,
)
if not isinstance(data, dict):
break
comments = data.get("comments", [])
all_comments.extend(comments)
pages += 1
has_more = data.get("has_more", False)
next_cursor = data.get("cursor", "")
if not has_more or not next_cursor:
break
cursor = next_cursor
return {
"comments": all_comments,
"has_more": False,
"cursor": "",
"total_fetched": len(all_comments),
"pages_fetched": pages,
}
def get_sub_comments(
self,
note_id: str,
root_comment_id: str,
num: int = 30,
cursor: str = "",
) -> Any:
return self._main_api_get("/api/sns/web/v2/comment/sub/page", {
"note_id": note_id,
"root_comment_id": root_comment_id,
"num": num,
"cursor": cursor,
})
class InteractionEndpointsMixin:
"""Mutating note interaction endpoints."""
def post_comment(self, note_id: str, content: str) -> dict[str, Any]:
return self._main_api_post("/api/sns/web/v1/comment/post", {
"note_id": note_id,
"content": content,
"at_users": [],
})
def reply_comment(self, note_id: str, target_comment_id: str, content: str) -> Any:
return self._main_api_post("/api/sns/web/v1/comment/post", {
"note_id": note_id,
"content": content,
"target_comment_id": target_comment_id,
"at_users": [],
})
def like_note(self, note_id: str) -> dict[str, Any]:
return self._main_api_post("/api/sns/web/v1/note/like", {"note_oid": note_id})
def unlike_note(self, note_id: str) -> dict[str, Any]:
return self._main_api_post("/api/sns/web/v1/note/dislike", {"note_oid": note_id})
def favorite_note(self, note_id: str) -> dict[str, Any]:
return self._main_api_post("/api/sns/web/v1/note/collect", {"note_id": note_id})
def unfavorite_note(self, note_id: str) -> dict[str, Any]:
return self._main_api_post("/api/sns/web/v1/note/uncollect", {"note_ids": note_id})
def delete_comment(self, note_id: str, comment_id: str) -> dict[str, Any]:
return self._main_api_post("/api/sns/web/v1/comment/delete", {
"note_id": note_id,
"comment_id": comment_id,
})
class CreatorEndpointsMixin:
"""Creator platform search, upload, and publishing endpoints."""
def search_topics(self, keyword: str) -> dict[str, Any]:
return self._creator_post("/web_api/sns/v1/search/topic", {
"keyword": keyword,
"suggest_topic_request": {"title": "", "desc": ""},
"page": {"page_size": 20, "page": 1},
})
def search_users(self, keyword: str) -> dict[str, Any]:
return self._creator_post("/web_api/sns/v1/search/user_info", {
"keyword": keyword,
"search_id": str(int(time.time() * 1000)),
"page": {"page_size": 20, "page": 1},
})
def get_upload_permit(self, file_type: str = "image", count: int = 1) -> dict[str, str]:
data = self._creator_get("/api/media/v1/upload/web/permit", {
"biz_name": "spectrum",
"scene": file_type,
"file_count": count,
"version": 1,
"source": "web",
})
permit = data["uploadTempPermits"][0]
return {"fileId": permit["fileIds"][0], "token": permit["token"]}
def upload_file(
self,
file_id: str,
token: str,
file_path: str,
content_type: str | None = None,
) -> None:
with open(file_path, "rb") as f:
file_data = f.read()
url = f"{UPLOAD_HOST}/{file_id}"
content_type = content_type or mimetypes.guess_type(file_path)[0] or "application/octet-stream"
resp = self._request_with_retry(
"PUT",
url,
headers={
"X-Cos-Security-Token": token,
"Content-Type": content_type,
},
content=file_data,
)
if resp.status_code >= 400:
raise XhsApiError(f"Upload failed: {resp.status_code} {resp.reason_phrase}")
def create_image_note(
self,
title: str,
desc: str,
image_file_ids: list[str],
topics: list[dict[str, str]] | None = None,
is_private: bool = False,
) -> Any:
images = [{"file_id": fid, "metadata": {"source": -1}} for fid in image_file_ids]
business_binds = {
"version": 1,
"noteId": 0,
"noteOrderBind": {},
"notePostTiming": {"postTime": None},
"noteCollectionBind": {"id": ""},
}
data = {
"common": {
"type": "normal",
"title": title,
"note_id": "",
"desc": desc,
"source": '{"type":"web","ids":"","extraInfo":"{\\"subType\\":\\"official\\"}"}',
"business_binds": json.dumps(business_binds),
"ats": [],
"hash_tag": topics or [],
"post_loc": {},
"privacy_info": {"op_type": 1, "type": 1 if is_private else 0},
},
"image_info": {"images": images},
"video_info": None,
}
return self._main_api_post("/web_api/sns/v2/note", data, {
"origin": CREATOR_HOST,
"referer": f"{CREATOR_HOST}/",
})
def delete_note(self, note_id: str) -> dict[str, Any]:
try:
return self._creator_post("/api/galaxy/creator/note/delete", {
"note_id": note_id,
})
except XhsApiError as exc:
response = exc.response if isinstance(exc.response, dict) else {}
if response.get("status") == 404 or "404" in str(exc):
raise UnsupportedOperationError(
"Delete note is currently unavailable from the public web API. "
"The command remains experimental until the new endpoint is re-captured."
) from None
raise
def get_creator_note_list(self, tab: int = 0, page: int = 0) -> dict[str, Any]:
return self._creator_get("/api/galaxy/v2/creator/note/user/posted", {
"tab": tab,
"page": page,
})
class SocialEndpointsMixin:
"""Social graph and saved-content endpoints."""
def follow_user(self, user_id: str) -> dict[str, Any]:
return self._main_api_post("/api/sns/web/v1/user/follow", {"target_user_id": user_id})
def unfollow_user(self, user_id: str) -> dict[str, Any]:
return self._main_api_post("/api/sns/web/v1/user/unfollow", {"target_user_id": user_id})
def get_user_favorites(self, user_id: str, cursor: str = "") -> dict[str, Any]:
return self._main_api_get("/api/sns/web/v2/note/collect/page", {
"user_id": user_id,
"cursor": cursor,
"num": 30,
})
class NotificationEndpointsMixin:
"""Notification and unread-count endpoints."""
def get_unread_count(self) -> dict[str, Any]:
return self._main_api_get("/api/sns/web/unread_count", {})
def get_notification_mentions(self, cursor: str = "", num: int = 20) -> dict[str, Any]:
return self._main_api_get("/api/sns/web/v1/you/mentions", {
"num": num,
"cursor": cursor,
})
def get_notification_likes(self, cursor: str = "", num: int = 20) -> dict[str, Any]:
return self._main_api_get("/api/sns/web/v1/you/likes", {
"num": num,
"cursor": cursor,
})
def get_notification_connections(self, cursor: str = "", num: int = 20) -> dict[str, Any]:
return self._main_api_get("/api/sns/web/v1/you/connections", {
"num": num,
"cursor": cursor,
})
class AuthEndpointsMixin:
"""Authentication-specific endpoints."""
def login_activate(self) -> dict[str, Any]:
return self._main_api_post("/api/sns/web/v1/login/activate", {})
def create_qr_login(self) -> dict[str, Any]:
return self._main_api_post("/api/sns/web/v1/login/qrcode/create", {"qr_type": 1})
def check_qr_status(self, qr_id: str, code: str) -> dict[str, Any]:
return self._main_api_post("/api/qrcode/userinfo", {
"qrId": qr_id,
"code": code,
}, {
"service-tag": "webcn",
})
def complete_qr_login(self, qr_id: str, code: str) -> dict[str, Any]:
return self._main_api_get("/api/sns/web/v1/login/qrcode/status", {
"qr_id": qr_id,
"code": code,
})
@@ -0,0 +1,65 @@
"""Helpers that normalize raw client responses for command-layer use."""
from __future__ import annotations
from typing import Any
def normalize_xhs_user_payload(info: dict[str, Any]) -> dict[str, object]:
"""Normalize Xiaohongshu user info for structured command output."""
basic = info.get("basic_info", info) if isinstance(info, dict) else {}
if not isinstance(basic, dict):
basic = {}
user_id = (
basic.get("user_id")
or info.get("user_id")
or info.get("userid")
or basic.get("red_id")
or info.get("red_id")
or ""
)
return {
"id": user_id,
"name": basic.get("nickname") or info.get("nickname", "Unknown"),
"username": basic.get("red_id") or info.get("red_id", ""),
"nickname": basic.get("nickname") or info.get("nickname", "Unknown"),
"red_id": basic.get("red_id") or info.get("red_id", ""),
"ip_location": basic.get("ip_location") or info.get("ip_location", ""),
"desc": basic.get("desc") or info.get("desc", ""),
"guest": bool(info.get("guest", False)),
}
def normalize_unread_summary(data: dict[str, Any]) -> dict[str, int]:
return {
"mentions": int(data.get("mentions", 0)),
"likes": int(data.get("likes", 0)),
"connections": int(data.get("connections", 0)),
"unread_count": int(data.get("unread_count", 0)),
}
def normalize_paged_notes(data: dict[str, Any]) -> dict[str, Any]:
return {
"notes": data.get("notes", []),
"has_more": bool(data.get("has_more", False)),
"cursor": data.get("cursor", ""),
}
def select_topic_payload(topic_data: Any, fallback_name: str) -> list[dict[str, str]]:
topics = topic_data if isinstance(topic_data, list) else topic_data.get("topic_info_dtos", [])
if not topics:
return []
first = topics[0]
return [{
"id": first.get("id", ""),
"name": first.get("name", fallback_name),
"type": "topic",
}]
def resolve_current_user_id(info: dict[str, Any]) -> str:
return info.get("user_id", "") if isinstance(info, dict) else ""
@@ -0,0 +1,104 @@
"""Common helpers for CLI commands."""
from __future__ import annotations
from collections.abc import Callable
from typing import TypeVar
import click
from ..client import XhsClient
from ..cookies import get_cookies
from ..error_codes import error_code_for_exception
from ..exceptions import (
NoCookieError,
SessionExpiredError,
XhsApiError,
)
from ..formatter import emit_error, print_error
T = TypeVar("T")
def structured_output_options(command: Callable) -> Callable:
"""Add --json/--yaml options to a Click command."""
command = click.option("--yaml", "as_yaml", is_flag=True, help="Output as YAML.")(command)
command = click.option("--json", "as_json", is_flag=True, help="Output as JSON.")(command)
return command
def _cookie_source(ctx) -> str:
return ctx.obj.get("cookie_source", "auto") if ctx.obj else "auto"
def get_client(ctx, *, force_refresh: bool = False) -> XhsClient:
"""Get a local client from the click context."""
_browser, cookies = get_cookies(_cookie_source(ctx), force_refresh=force_refresh)
return XhsClient(cookies)
def run_client_action(ctx, action: Callable[[XhsClient], T]) -> T:
"""Run an authenticated client action and retry once with fresh browser cookies."""
try:
with get_client(ctx) as client:
return action(client)
except SessionExpiredError as exc:
try:
with get_client(ctx, force_refresh=True) as client:
return action(client)
except NoCookieError:
raise exc from None
def handle_command(
ctx,
*,
action: Callable[[XhsClient], T],
render: Callable[[T], None] | None,
as_json: bool,
as_yaml: bool,
prefix: str | None = None,
):
"""Run a client action, emit structured output if requested, else render."""
from ..formatter import maybe_print_structured
try:
data = run_client_action(ctx, action)
if not maybe_print_structured(data, as_json=as_json, as_yaml=as_yaml) and render:
render(data)
return data
except (XhsApiError, NoCookieError) as exc:
exit_for_error(exc, as_json=as_json, as_yaml=as_yaml, prefix=prefix)
def handle_errors(
fn: Callable[[], T],
*,
as_json: bool,
as_yaml: bool,
prefix: str | None = None,
) -> T:
"""Run arbitrary command logic and funnel failures through exit_for_error."""
try:
return fn()
except (XhsApiError, NoCookieError) as exc:
exit_for_error(exc, as_json=as_json, as_yaml=as_yaml, prefix=prefix)
def exit_for_error(
exc: Exception,
*,
as_json: bool,
as_yaml: bool,
prefix: str | None = None,
) -> None:
"""Emit a structured/non-structured error and terminate the command."""
message = str(exc)
if prefix:
message = f"{prefix}: {message}"
if emit_error(error_code_for_exception(exc), message, as_json=as_json, as_yaml=as_yaml):
raise SystemExit(1) from None
print_error(message)
raise SystemExit(1) from None
@@ -0,0 +1,170 @@
"""Authentication commands: login, status, logout."""
import time
import click
from ..client import XhsClient
from ..command_normalizers import normalize_xhs_user_payload
from ..cookies import clear_cookies, get_cookies
from ..exceptions import XhsApiError
from ..formatter import (
console,
maybe_print_structured,
print_success,
render_user_info,
success_payload,
)
from ._common import handle_errors, run_client_action, structured_output_options
def _emit_payload(data: dict[str, object], *, as_json: bool, as_yaml: bool) -> bool:
"""Emit a structured success payload when requested."""
return maybe_print_structured(success_payload(data), as_json=as_json, as_yaml=as_yaml)
def _is_valid_login(user: dict[str, object]) -> bool:
"""Check whether the normalized user payload represents a real logged-in session."""
if user.get("guest"):
return False
nickname = user.get("nickname", "")
return bool(nickname and nickname != "Unknown")
def _print_login_success(user: dict[str, object]) -> None:
"""Print a concise login success message."""
print_success(f"Logged in as: {user['nickname']} (ID: {user['red_id']})")
def _print_status_summary(user: dict[str, object]) -> None:
"""Render a short authenticated-user summary."""
console.print("[bold green]✓ Logged in[/bold green]")
console.print(f" 昵称: [bold]{user['nickname']}[/bold]")
if user["red_id"]:
console.print(f" 小红书号: {user['red_id']}")
if user["ip_location"]:
console.print(f" IP 属地: {user['ip_location']}")
if user["desc"]:
console.print(f" 简介: {user['desc']}")
@click.command()
@click.option(
"--cookie-source",
type=str,
default=None,
help="Browser to read cookies from (default: auto-detect all installed browsers)",
)
@structured_output_options
@click.option("--qrcode", "use_qrcode", is_flag=True, default=False,
help="Login via QR code (scan with Xiaohongshu app)")
@click.pass_context
def login(ctx, cookie_source: str | None, as_json: bool, as_yaml: bool, use_qrcode: bool):
"""Log in by extracting cookies from browser, or via QR code."""
if use_qrcode:
def _login_with_qrcode() -> None:
from ..qr_login import qrcode_login
cookies = qrcode_login(prefer_browser_assisted=True)
# Verify by fetching user info (may return guest=true briefly)
import time
time.sleep(1) # brief delay for session propagation
with XhsClient(cookies) as client:
info = client.get_self_info()
user = normalize_xhs_user_payload(info)
if user["guest"]:
# Session not yet propagated; still valid
if not _emit_payload(
{"authenticated": True, "user": {"id": user["id"]}},
as_json=as_json,
as_yaml=as_yaml,
):
print_success("Logged in (session saved)")
else:
if not _emit_payload({"authenticated": True, "user": user}, as_json=as_json, as_yaml=as_yaml):
_print_login_success(user)
handle_errors(
_login_with_qrcode,
as_json=as_json,
as_yaml=as_yaml,
prefix="QR login failed",
)
return
# Browser cookie extraction (default)
if cookie_source is None:
cookie_source = ctx.obj.get("cookie_source", "auto") if ctx.obj else "auto"
def _login_with_browser() -> None:
browser, cookies = get_cookies(cookie_source, force_refresh=True)
print_success(f"Cookies extracted from {browser}")
# Verify by fetching user info, retry once if session not yet propagated
with XhsClient(cookies) as client:
info = client.get_self_info()
user = normalize_xhs_user_payload(info)
if not _is_valid_login(user):
time.sleep(2.5)
with XhsClient(cookies) as client:
info = client.get_self_info()
user = normalize_xhs_user_payload(info)
if not _is_valid_login(user):
raise XhsApiError(
"Browser cookies were extracted, but the session appears invalid "
"(guest or incomplete profile). Try: xhs login --qrcode"
)
if not _emit_payload({"authenticated": True, "user": user}, as_json=as_json, as_yaml=as_yaml):
_print_login_success(user)
handle_errors(
_login_with_browser,
as_json=as_json,
as_yaml=as_yaml,
prefix="Login verification failed",
)
@click.command()
@structured_output_options
@click.pass_context
def status(ctx, as_json: bool, as_yaml: bool):
"""Check current login status and user info."""
def _show_status() -> None:
info = run_client_action(ctx, lambda client: client.get_self_info())
user = normalize_xhs_user_payload(info)
if not _emit_payload({"authenticated": True, "user": user}, as_json=as_json, as_yaml=as_yaml):
_print_status_summary(user)
handle_errors(_show_status, as_json=as_json, as_yaml=as_yaml, prefix="Status check failed")
@click.command()
@structured_output_options
@click.pass_context
def logout(ctx, as_json: bool, as_yaml: bool):
"""Clear saved cookies and log out."""
clear_cookies()
if not _emit_payload({"logged_out": True}, as_json=as_json, as_yaml=as_yaml):
print_success("Logged out — cookies cleared")
@click.command()
@structured_output_options
@click.pass_context
def whoami(ctx, as_json: bool, as_yaml: bool):
"""Show detailed profile of current user (level, fans, likes)."""
def _show_profile() -> None:
info = run_client_action(ctx, lambda client: client.get_self_info())
user = normalize_xhs_user_payload(info)
if not _emit_payload({"user": user}, as_json=as_json, as_yaml=as_yaml):
render_user_info(info)
handle_errors(_show_profile, as_json=as_json, as_yaml=as_yaml, prefix="Failed to get profile")
@@ -0,0 +1,105 @@
"""Creator commands: post, my-notes, delete."""
import click
from ..command_normalizers import select_topic_payload
from ..formatter import (
extract_note_id,
maybe_print_structured,
print_info,
print_success,
render_creator_notes,
)
from ..note_refs import save_index_from_notes
from ._common import exit_for_error, handle_command, run_client_action, structured_output_options
@click.command()
@click.option("--title", required=True, help="Note title")
@click.option("--body", required=True, help="Note body text")
@click.option("--images", required=True, multiple=True, help="Image file path(s)")
@click.option("--topic", default=None, help="Topic/hashtag to search and attach")
@click.option("--private", "is_private", is_flag=True, help="Publish as private note")
@structured_output_options
@click.pass_context
def post(
ctx,
title: str,
body: str,
images: tuple[str, ...],
topic: str | None,
is_private: bool,
as_json: bool,
as_yaml: bool,
):
"""Publish an image note."""
def _publish(client):
file_ids = []
for img_path in images:
print_info(f"Uploading {img_path}...")
permit = client.get_upload_permit()
client.upload_file(permit["fileId"], permit["token"], img_path)
file_ids.append(permit["fileId"])
print_success(f"Uploaded: {img_path}")
topics = []
if topic:
topic_data = client.search_topics(topic)
topics = select_topic_payload(topic_data, topic)
return client.create_image_note(
title=title,
desc=body,
image_file_ids=file_ids,
topics=topics,
is_private=is_private,
)
handle_command(
ctx,
action=_publish,
render=lambda _data: print_success(f"Note published: {title}" + (" (private)" if is_private else "")),
as_json=as_json,
as_yaml=as_yaml,
)
@click.command("my-notes")
@click.option("--page", default=0, help="Page number (0-indexed)")
@structured_output_options
@click.pass_context
def my_notes(ctx, page: int, as_json: bool, as_yaml: bool):
"""List your own published notes."""
def _my_notes_action(client):
data = client.get_creator_note_list(page=page)
notes = data.get("notes", data.get("note_list", []))
save_index_from_notes(notes)
return data
handle_command(
ctx,
action=_my_notes_action,
render=render_creator_notes,
as_json=as_json,
as_yaml=as_yaml,
)
@click.command("delete")
@click.argument("id_or_url")
@structured_output_options
@click.option("--yes", "-y", is_flag=True, help="Skip confirmation")
@click.pass_context
def delete(ctx, id_or_url: str, as_json: bool, as_yaml: bool, yes: bool):
"""Delete a note. Experimental: the public web endpoint is unstable."""
note_id = extract_note_id(id_or_url)
if not yes:
click.confirm(f"Delete note {note_id}?", abort=True)
try:
data = run_client_action(ctx, lambda client: client.delete_note(note_id))
if not maybe_print_structured(data, as_json=as_json, as_yaml=as_yaml):
print_success(f"Deleted note {note_id}")
except Exception as exc:
exit_for_error(exc, as_json=as_json, as_yaml=as_yaml)
@@ -0,0 +1,120 @@
"""Interaction commands: like, collect, comment, reply."""
import click
from ..cookies import cache_note_context
from ..formatter import print_success
from ..note_refs import resolve_note_reference
from ._common import handle_command, structured_output_options
def _resolve_interaction_note(id_or_url: str) -> str:
note_id, token, source = resolve_note_reference(id_or_url)
if token:
cache_note_context(note_id, token, source or "pc_feed")
return note_id
@click.command()
@click.argument("id_or_url")
@click.option("--undo", is_flag=True, help="Unlike instead of like")
@structured_output_options
@click.pass_context
def like(ctx, id_or_url: str, undo: bool, as_json: bool, as_yaml: bool):
"""Like or unlike a note."""
note_id = _resolve_interaction_note(id_or_url)
action = (lambda client: client.unlike_note(note_id)) if undo else (lambda client: client.like_note(note_id))
handle_command(
ctx,
action=action,
render=lambda _data: print_success(f"{'Unliked' if undo else 'Liked'} note {note_id}"),
as_json=as_json,
as_yaml=as_yaml,
)
@click.command()
@click.argument("id_or_url")
@structured_output_options
@click.pass_context
def favorite(ctx, id_or_url: str, as_json: bool, as_yaml: bool):
"""Favorite (bookmark) a note."""
note_id = _resolve_interaction_note(id_or_url)
handle_command(
ctx,
action=lambda client: client.favorite_note(note_id),
render=lambda _data: print_success(f"Favorited note {note_id}"),
as_json=as_json,
as_yaml=as_yaml,
)
@click.command()
@click.argument("id_or_url")
@structured_output_options
@click.pass_context
def unfavorite(ctx, id_or_url: str, as_json: bool, as_yaml: bool):
"""Unfavorite (unbookmark) a note."""
note_id = _resolve_interaction_note(id_or_url)
handle_command(
ctx,
action=lambda client: client.unfavorite_note(note_id),
render=lambda _data: print_success(f"Unfavorited note {note_id}"),
as_json=as_json,
as_yaml=as_yaml,
)
@click.command()
@click.argument("id_or_url")
@click.option("--content", "-c", required=True, help="Comment content")
@structured_output_options
@click.pass_context
def comment(ctx, id_or_url: str, content: str, as_json: bool, as_yaml: bool):
"""Post a comment on a note."""
note_id = _resolve_interaction_note(id_or_url)
handle_command(
ctx,
action=lambda client: client.post_comment(note_id, content),
render=lambda _data: print_success(f"Comment posted on {note_id}"),
as_json=as_json,
as_yaml=as_yaml,
)
@click.command()
@click.argument("id_or_url")
@click.option("--comment-id", required=True, help="Target comment ID to reply to")
@click.option("--content", "-c", required=True, help="Reply content")
@structured_output_options
@click.pass_context
def reply(ctx, id_or_url: str, comment_id: str, content: str, as_json: bool, as_yaml: bool):
"""Reply to a specific comment."""
note_id = _resolve_interaction_note(id_or_url)
handle_command(
ctx,
action=lambda client: client.reply_comment(note_id, comment_id, content),
render=lambda _data: print_success(f"Reply posted on comment {comment_id}"),
as_json=as_json,
as_yaml=as_yaml,
)
@click.command("delete-comment")
@click.argument("note_id")
@click.argument("comment_id")
@structured_output_options
@click.option("--yes", "-y", is_flag=True, help="Skip confirmation")
@click.pass_context
def delete_comment(ctx, note_id: str, comment_id: str, as_json: bool, as_yaml: bool, yes: bool):
"""Delete a comment you posted."""
if not yes:
click.confirm(f"Delete comment {comment_id} on note {note_id}?", abort=True)
handle_command(
ctx,
action=lambda client: client.delete_comment(note_id, comment_id),
render=lambda _data: print_success(f"Deleted comment {comment_id}"),
as_json=as_json,
as_yaml=as_yaml,
)
@@ -0,0 +1,57 @@
"""Notification commands: unread counts and notification feeds."""
import click
from ..command_normalizers import normalize_unread_summary
from ..formatter import console, render_notifications
from ._common import handle_command, structured_output_options
@click.command()
@click.option(
"--type", "notif_type",
type=click.Choice(["mentions", "likes", "connections"]),
default="mentions",
help="Notification type: mentions (评论和@), likes (赞和收藏), connections (新增关注)",
)
@click.option("--cursor", default="", help="Pagination cursor")
@click.option("--num", default=20, help="Number of items per page")
@structured_output_options
@click.pass_context
def notifications(ctx, notif_type: str, cursor: str, num: int, as_json: bool, as_yaml: bool):
"""View notifications (mentions, likes, connections)."""
def _load_notifications(client):
if notif_type == "mentions":
return client.get_notification_mentions(cursor=cursor, num=num)
if notif_type == "likes":
return client.get_notification_likes(cursor=cursor, num=num)
return client.get_notification_connections(cursor=cursor, num=num)
handle_command(
ctx,
action=_load_notifications,
render=lambda data: render_notifications(data, notif_type),
as_json=as_json,
as_yaml=as_yaml,
)
@click.command()
@structured_output_options
@click.pass_context
def unread(ctx, as_json: bool, as_yaml: bool):
"""Show unread notification counts."""
def _render_unread(data):
summary = normalize_unread_summary(data)
console.print(f"📬 未读通知: [bold]{summary['unread_count']}[/bold]")
console.print(f" 💬 评论和@: {summary['mentions']}")
console.print(f" ❤️ 赞和收藏: {summary['likes']}")
console.print(f" 👥 新增关注: {summary['connections']}")
handle_command(
ctx,
action=lambda client: client.get_unread_count(),
render=_render_unread,
as_json=as_json,
as_yaml=as_yaml,
)
@@ -0,0 +1,297 @@
"""Reading commands: search, read, comments, sub-comments, user, user-posts, feed, hot, topics, search-user."""
import click
from ..command_normalizers import normalize_paged_notes
from ..cookies import cache_note_context
from ..formatter import (
maybe_print_structured,
print_info,
render_comments,
render_feed,
render_note,
render_search_results,
render_topics,
render_user_info,
render_user_posts,
render_users,
)
from ..note_refs import resolve_note_reference, save_index_from_items, save_index_from_notes
from ._common import exit_for_error, handle_command, run_client_action, structured_output_options
# ─── Token propagation ─────────────────────────────────────────────────────
def _cache_tokens_from_items(data: dict, *, xsec_source: str) -> None:
"""Auto-cache xsec_token from search/feed API results.
Each note item may carry its own xsec_token bound to the source
(search, feed, explore). Caching them lets a subsequent
`xhs read <note_id>` use the correct token automatically.
"""
for item in data.get("items", []):
note_card = item.get("note_card", {})
note_id = item.get("id", note_card.get("note_id", ""))
token = item.get("xsec_token", note_card.get("xsec_token", ""))
if note_id and token:
cache_note_context(note_id, token, xsec_source)
# ─── Sort mapping ────────────────────────────────────────────────────────────
SORT_MAP = {
"general": "general",
"popular": "popularity_descending",
"latest": "time_descending",
}
TYPE_MAP = {
"all": 0,
"video": 1,
"image": 2,
}
@click.command()
@click.argument("keyword")
@click.option("--sort", type=click.Choice(["general", "popular", "latest"]), default="general", help="Sort order")
@click.option("--type", "note_type", type=click.Choice(["all", "video", "image"]), default="all", help="Note type")
@click.option("--page", default=1, help="Page number")
@structured_output_options
@click.pass_context
def search(ctx, keyword: str, sort: str, note_type: str, page: int, as_json: bool, as_yaml: bool):
"""Search notes by keyword."""
def _search_action(client):
result = client.search_notes(
keyword=keyword,
page=page,
sort=SORT_MAP[sort],
note_type=TYPE_MAP[note_type],
)
_cache_tokens_from_items(result, xsec_source="pc_search")
save_index_from_items(result, xsec_source="pc_search")
return result
handle_command(
ctx,
action=_search_action,
render=render_search_results,
as_json=as_json,
as_yaml=as_yaml,
)
@click.command()
@click.argument("id_or_url")
@click.option("--xsec-token", default="", help="Security token (or reuse a cached token for this note)")
@structured_output_options
@click.pass_context
def read(ctx, id_or_url: str, xsec_token: str, as_json: bool, as_yaml: bool):
"""Read a note by ID, URL, or short index."""
note_id, token, url_source = resolve_note_reference(id_or_url, xsec_token=xsec_token)
xsec_source = url_source or "pc_feed"
if token:
cache_note_context(note_id, token, xsec_source)
def _read_action(client):
kwargs = {"xsec_token": token}
if url_source:
kwargs["xsec_source"] = url_source
return client.get_note_detail(note_id, **kwargs)
handle_command(
ctx,
action=_read_action,
render=render_note,
as_json=as_json,
as_yaml=as_yaml,
)
@click.command()
@click.argument("id_or_url")
@click.option("--cursor", default="", help="Pagination cursor")
@click.option("--xsec-token", default="", help="Security token")
@click.option("--all", "fetch_all", is_flag=True, help="Auto-paginate to fetch ALL comments")
@structured_output_options
@click.pass_context
def comments(ctx, id_or_url: str, cursor: str, xsec_token: str, fetch_all: bool, as_json: bool, as_yaml: bool):
"""View comments on a note by ID, URL, or short index."""
note_id, token, url_source = resolve_note_reference(id_or_url, xsec_token=xsec_token)
xsec_source = url_source or "pc_feed"
if token:
cache_note_context(note_id, token, xsec_source)
def _load_comments(client):
common_kwargs = {"xsec_token": token}
if url_source:
common_kwargs["xsec_source"] = url_source
if fetch_all:
return client.get_all_comments(note_id, **common_kwargs)
return client.get_comments(
note_id,
cursor=cursor,
**common_kwargs,
)
def _render_comments(data):
render_comments(data)
if fetch_all and isinstance(data, dict):
total = data.get("total_fetched", 0)
pages = data.get("pages_fetched", 0)
print_info(f"Fetched {total} comments across {pages} pages")
try:
data = run_client_action(ctx, _load_comments)
if not maybe_print_structured(data, as_json=as_json, as_yaml=as_yaml):
_render_comments(data)
except Exception as exc:
exit_for_error(exc, as_json=as_json, as_yaml=as_yaml)
@click.command()
@click.argument("user_id")
@structured_output_options
@click.pass_context
def user(ctx, user_id: str, as_json: bool, as_yaml: bool):
"""View user profile info."""
handle_command(
ctx,
action=lambda client: client.get_user_info(user_id),
render=render_user_info,
as_json=as_json,
as_yaml=as_yaml,
)
@click.command("user-posts")
@click.argument("user_id")
@click.option("--cursor", default="", help="Pagination cursor")
@structured_output_options
@click.pass_context
def user_posts(ctx, user_id: str, cursor: str, as_json: bool, as_yaml: bool):
"""List a user's published notes."""
def _user_posts_action(client):
data = client.get_user_notes(user_id, cursor=cursor)
page = normalize_paged_notes(data)
save_index_from_notes(page["notes"])
return data
def _render_user_posts(data):
page = normalize_paged_notes(data)
render_user_posts(page["notes"])
if page["has_more"]:
print_info(f"More notes available — use --cursor {page['cursor']}")
handle_command(
ctx,
action=_user_posts_action,
render=_render_user_posts,
as_json=as_json,
as_yaml=as_yaml,
)
@click.command()
@structured_output_options
@click.pass_context
def feed(ctx, as_json: bool, as_yaml: bool):
"""Browse the recommendation feed."""
def _feed_action(client):
result = client.get_home_feed()
_cache_tokens_from_items(result, xsec_source="pc_feed")
save_index_from_items(result, xsec_source="pc_feed")
return result
handle_command(
ctx,
action=_feed_action,
render=render_feed,
as_json=as_json,
as_yaml=as_yaml,
)
@click.command()
@click.argument("keyword")
@structured_output_options
@click.pass_context
def topics(ctx, keyword: str, as_json: bool, as_yaml: bool):
"""Search for topics/hashtags."""
handle_command(
ctx,
action=lambda client: client.search_topics(keyword),
render=render_topics,
as_json=as_json,
as_yaml=as_yaml,
)
@click.command("sub-comments")
@click.argument("note_id")
@click.argument("comment_id")
@click.option("--cursor", default="", help="Pagination cursor")
@structured_output_options
@click.pass_context
def sub_comments(ctx, note_id: str, comment_id: str, cursor: str, as_json: bool, as_yaml: bool):
"""View replies to a specific comment."""
handle_command(
ctx,
action=lambda client: client.get_sub_comments(note_id, comment_id, cursor=cursor),
render=render_comments,
as_json=as_json,
as_yaml=as_yaml,
)
@click.command("search-user")
@click.argument("keyword")
@structured_output_options
@click.pass_context
def search_user(ctx, keyword: str, as_json: bool, as_yaml: bool):
"""Search for users by keyword."""
handle_command(
ctx,
action=lambda client: client.search_users(keyword),
render=render_users,
as_json=as_json,
as_yaml=as_yaml,
)
HOT_CATEGORIES = {
"fashion": "homefeed.fashion_v3",
"food": "homefeed.food_v3",
"cosmetics": "homefeed.cosmetics_v3",
"movie": "homefeed.movie_and_tv_v3",
"career": "homefeed.career_v3",
"love": "homefeed.love_v3",
"home": "homefeed.household_product_v3",
"gaming": "homefeed.gaming_v3",
"travel": "homefeed.travel_v3",
"fitness": "homefeed.fitness_v3",
}
@click.command()
@click.option(
"--category", "-c",
type=click.Choice(list(HOT_CATEGORIES.keys())),
default="food",
help="Category (fashion, food, cosmetics, movie, career, love, home, gaming, travel, fitness)",
)
@structured_output_options
@click.pass_context
def hot(ctx, category: str, as_json: bool, as_yaml: bool):
"""Browse hot/trending notes by category."""
def _hot_action(client):
result = client.get_hot_feed(HOT_CATEGORIES[category])
_cache_tokens_from_items(result, xsec_source="pc_feed")
save_index_from_items(result, xsec_source="pc_feed")
return result
handle_command(
ctx,
action=_hot_action,
render=render_feed,
as_json=as_json,
as_yaml=as_yaml,
)
@@ -0,0 +1,79 @@
"""Social commands: follow, unfollow, favorites, following, followers."""
import click
from ..command_normalizers import normalize_paged_notes, resolve_current_user_id
from ..formatter import print_info, print_success, render_user_posts
from ..note_refs import save_index_from_notes
from ._common import handle_command, run_client_action, structured_output_options
def _resolve_user_id(ctx, user_id: str | None) -> str:
"""Resolve user_id: use provided value or fall back to current user."""
if user_id:
return user_id
info = run_client_action(ctx, lambda client: client.get_self_info())
uid = resolve_current_user_id(info)
if not uid:
raise click.UsageError("Cannot determine current user_id. Please specify user_id explicitly.")
return uid
@click.command()
@click.argument("user_id")
@structured_output_options
@click.pass_context
def follow(ctx, user_id: str, as_json: bool, as_yaml: bool):
"""Follow a user."""
handle_command(
ctx,
action=lambda client: client.follow_user(user_id),
render=lambda _data: print_success(f"Followed user {user_id}"),
as_json=as_json,
as_yaml=as_yaml,
)
@click.command()
@click.argument("user_id")
@structured_output_options
@click.pass_context
def unfollow(ctx, user_id: str, as_json: bool, as_yaml: bool):
"""Unfollow a user."""
handle_command(
ctx,
action=lambda client: client.unfollow_user(user_id),
render=lambda _data: print_success(f"Unfollowed user {user_id}"),
as_json=as_json,
as_yaml=as_yaml,
)
@click.command()
@click.argument("user_id", required=False, default=None)
@click.option("--cursor", default="", help="Pagination cursor")
@structured_output_options
@click.pass_context
def favorites(ctx, user_id: str | None, cursor: str, as_json: bool, as_yaml: bool):
"""List favorited (bookmarked) notes. Defaults to current user if user_id is omitted."""
uid = _resolve_user_id(ctx, user_id)
def _favorites_action(client):
data = client.get_user_favorites(uid, cursor=cursor)
page = normalize_paged_notes(data)
save_index_from_notes(page["notes"])
return data
def _render_favorites(data):
page = normalize_paged_notes(data)
render_user_posts(page["notes"])
if page["has_more"]:
print_info(f"More notes — use --cursor {page['cursor']}")
handle_command(
ctx,
action=_favorites_action,
render=_render_favorites,
as_json=as_json,
as_yaml=as_yaml,
)
@@ -0,0 +1,24 @@
"""Constants for XHS API client."""
EDITH_HOST = "https://edith.xiaohongshu.com"
CREATOR_HOST = "https://creator.xiaohongshu.com"
HOME_URL = "https://www.xiaohongshu.com"
UPLOAD_HOST = "https://ros-upload.xiaohongshu.com"
CHROME_VERSION = "145"
USER_AGENT = (
"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
"AppleWebKit/537.36 (KHTML, like Gecko) "
f"Chrome/{CHROME_VERSION}.0.0.0 Safari/537.36"
)
SDK_VERSION = "4.2.6"
APP_ID = "xhs-pc-web"
PLATFORM = "macOS"
# Config directory
CONFIG_DIR_NAME = ".xiaohongshu-cli"
COOKIE_FILE = "cookies.json"
TOKEN_CACHE_FILE = "token_cache.json"
INDEX_CACHE_FILE = "index_cache.json"
+526
View File
@@ -0,0 +1,526 @@
"""Cookie extraction and management for XHS API client."""
from __future__ import annotations
import functools
import json
import logging
import subprocess
import sys
import threading
import time
from collections import OrderedDict
from pathlib import Path
from typing import Any
from .constants import CONFIG_DIR_NAME, COOKIE_FILE, INDEX_CACHE_FILE, TOKEN_CACHE_FILE
logger = logging.getLogger(__name__)
# Cookie TTL: warn and attempt browser refresh after 7 days
COOKIE_TTL_DAYS = 7
_COOKIE_TTL_SECONDS = COOKIE_TTL_DAYS * 86400
_TOKEN_CACHE_LOCK = threading.RLock()
_TOKEN_CACHE_MEMORY: OrderedDict[str, dict[str, Any]] | None = None
_TOKEN_CACHE_PATH: Path | None = None
NOTE_CONTEXT_TTL_SECONDS = 86400
def get_config_dir() -> Path:
"""Get or create config directory."""
config_dir = Path.home() / CONFIG_DIR_NAME
config_dir.mkdir(parents=True, exist_ok=True)
return config_dir
def get_cookie_path() -> Path:
"""Get cookie file path."""
return get_config_dir() / COOKIE_FILE
def get_token_cache_path() -> Path:
"""Get xsec token cache file path."""
return get_config_dir() / TOKEN_CACHE_FILE
def get_index_cache_path() -> Path:
"""Get note index cache file path."""
return get_config_dir() / INDEX_CACHE_FILE
def load_saved_cookies() -> dict[str, str] | None:
"""Load cookies from local storage."""
cookie_path = get_cookie_path()
if not cookie_path.exists():
return None
try:
data = json.loads(cookie_path.read_text())
if data.get("a1"):
logger.debug("Loaded saved cookies from %s", cookie_path)
return data
except (OSError, json.JSONDecodeError) as e:
logger.debug("Failed to load saved cookies: %s", e)
return None
def save_cookies(cookies: dict[str, str]) -> None:
"""Save cookies to local storage with restricted permissions and TTL timestamp."""
cookie_path = get_cookie_path()
payload = {**cookies, "saved_at": time.time()}
cookie_path.write_text(json.dumps(payload, indent=2))
cookie_path.chmod(0o600)
logger.debug("Saved cookies to %s", cookie_path)
def clear_cookies() -> None:
"""Remove saved cookies."""
cookie_path = get_cookie_path()
if cookie_path.exists():
cookie_path.unlink()
logger.debug("Cleared cookies from %s", cookie_path)
def _normalize_token_entry(value: Any) -> dict[str, Any] | None:
if isinstance(value, str):
return {"token": value, "source": "", "ts": time.time()}
if not isinstance(value, dict):
return None
token = str(value.get("token", "")).strip()
if not token:
return None
source = str(value.get("source", "")).strip()
context = str(value.get("context", "")).strip()
ts = value.get("ts", 0)
try:
ts = float(ts)
except (TypeError, ValueError):
ts = 0.0
entry = {"token": token, "source": source, "ts": ts}
if context:
entry["context"] = context
return entry
def _load_token_cache_from_disk(cache_path: Path) -> OrderedDict[str, dict[str, Any]]:
if not cache_path.exists():
return OrderedDict()
try:
data = json.loads(cache_path.read_text())
except (OSError, json.JSONDecodeError) as exc:
logger.debug("Failed to load token cache: %s", exc)
return OrderedDict()
if not isinstance(data, dict):
return OrderedDict()
normalized: list[tuple[str, dict[str, Any]]] = []
for key, value in data.items():
if not key:
continue
entry = _normalize_token_entry(value)
if entry:
normalized.append((str(key), entry))
normalized.sort(key=lambda item: float(item[1].get("ts", 0)))
return OrderedDict(normalized)
def _prune_token_cache(
cache: OrderedDict[str, dict[str, Any]],
now: float | None = None,
) -> OrderedDict[str, dict[str, Any]]:
now = now or time.time()
pruned = OrderedDict(
(key, value)
for key, value in cache.items()
if now - float(value.get("ts", 0)) <= NOTE_CONTEXT_TTL_SECONDS
)
while len(pruned) > TOKEN_CACHE_MAX_SIZE:
pruned.popitem(last=False)
return pruned
def load_token_cache() -> dict[str, dict[str, Any]]:
"""Load cached note_id -> token context mappings."""
cache_path = get_token_cache_path()
global _TOKEN_CACHE_MEMORY, _TOKEN_CACHE_PATH
with _TOKEN_CACHE_LOCK:
if _TOKEN_CACHE_MEMORY is None or _TOKEN_CACHE_PATH != cache_path:
_TOKEN_CACHE_MEMORY = _prune_token_cache(_load_token_cache_from_disk(cache_path))
_TOKEN_CACHE_PATH = cache_path
return {
key: dict(value)
for key, value in _TOKEN_CACHE_MEMORY.items()
}
def save_token_cache(cache: dict[str, dict[str, Any]]) -> None:
"""Persist xsec token cache with restricted permissions."""
cache_path = get_token_cache_path()
global _TOKEN_CACHE_MEMORY, _TOKEN_CACHE_PATH
normalized = _prune_token_cache(OrderedDict(
sorted(
(
(str(key), dict(value))
for key, value in cache.items()
if key and isinstance(value, dict)
),
key=lambda item: float(item[1].get("ts", 0)),
)
))
with _TOKEN_CACHE_LOCK:
cache_path.write_text(json.dumps(normalized, indent=2))
cache_path.chmod(0o600)
_TOKEN_CACHE_MEMORY = normalized
_TOKEN_CACHE_PATH = cache_path
TOKEN_CACHE_MAX_SIZE = 500
def cache_note_context(
note_id: str,
xsec_token: str,
xsec_source: str = "",
*,
context: str = "",
) -> None:
"""Store a resolved note token and source for later access.
Maintains an LRU-style cache capped at TOKEN_CACHE_MAX_SIZE entries.
Each entry stores token/source/timestamp metadata; overflow evicts the
oldest entries.
"""
if not note_id or not xsec_token:
return
cache = load_token_cache()
existing = cache.get(note_id)
if (
isinstance(existing, dict)
and existing.get("token") == xsec_token
and existing.get("source", "") == xsec_source
and existing.get("context", "") == context
):
existing["ts"] = time.time()
save_token_cache(cache)
return
entry = {
"token": xsec_token,
"source": xsec_source,
"ts": time.time(),
}
if context:
entry["context"] = context
cache[note_id] = entry
# Evict oldest entries if over limit
if len(cache) > TOKEN_CACHE_MAX_SIZE:
sorted_keys = sorted(
cache.keys(),
key=lambda k: cache[k].get("ts", 0) if isinstance(cache[k], dict) else 0,
)
for key in sorted_keys[: len(cache) - TOKEN_CACHE_MAX_SIZE]:
del cache[key]
save_token_cache(cache)
logger.debug("Cached xsec_token for note %s", note_id)
def invalidate_note_context(note_id: str) -> None:
"""Remove cached token/source metadata for a note ID."""
if not note_id:
return
cache = load_token_cache()
if note_id not in cache:
return
del cache[note_id]
save_token_cache(cache)
logger.debug("Invalidated cached note context for %s", note_id)
def _normalize_index_entry(value: Any) -> dict[str, str] | None:
if not isinstance(value, dict):
return None
note_id = str(value.get("note_id", "")).strip()
if not note_id:
return None
return {
"note_id": note_id,
"xsec_token": str(value.get("xsec_token", "")).strip(),
"xsec_source": str(value.get("xsec_source", "")).strip(),
}
def save_note_index(items: list[dict[str, str]]) -> None:
"""Persist the latest ordered note index for short-index navigation."""
path = get_index_cache_path()
normalized = [
entry
for entry in (_normalize_index_entry(item) for item in items)
if entry
]
path.write_text(json.dumps(normalized, indent=2, ensure_ascii=False))
path.chmod(0o600)
logger.debug("Saved note index with %d entries", len(normalized))
def get_note_by_index(index: int) -> dict[str, str] | None:
"""Resolve a 1-based short index to a cached note reference."""
if index <= 0:
return None
path = get_index_cache_path()
if not path.exists():
return None
try:
data = json.loads(path.read_text())
except (OSError, json.JSONDecodeError):
return None
if not isinstance(data, list) or index > len(data):
return None
return _normalize_index_entry(data[index - 1])
def cache_xsec_token(note_id: str, xsec_token: str) -> None:
"""Backwards-compatible wrapper for token-only caching."""
cache_note_context(note_id, xsec_token)
def get_cached_note_context(note_id: str) -> dict[str, Any]:
"""Get cached token/source metadata for a note ID."""
entry = load_token_cache().get(note_id)
if not isinstance(entry, dict):
return {}
return {
"token": str(entry.get("token", "")),
"source": str(entry.get("source", "")),
"context": str(entry.get("context", "")),
"ts": entry.get("ts", 0.0),
}
def get_cached_xsec_token(note_id: str) -> str:
"""Get a cached xsec token for a note ID."""
return get_cached_note_context(note_id).get("token", "")
@functools.lru_cache(maxsize=1)
def _available_browsers() -> tuple[str, ...]:
"""List all browser names supported by browser_cookie3 (cached)."""
import inspect
import browser_cookie3 as bc3
return tuple(sorted(
name
for name in dir(bc3)
if not name.startswith("_")
and name != "load" # 'load' tries all browsers; skip in auto-detect
and callable(getattr(bc3, name))
and hasattr(getattr(bc3, name), "__code__")
and "domain_name" in inspect.signature(getattr(bc3, name)).parameters
))
def _get_browser_loader(source: str):
"""Get browser cookie loader from browser_cookie3 by name."""
import browser_cookie3 as bc3
loader = getattr(bc3, source, None)
if loader is None or not callable(loader):
available = _available_browsers()
raise ValueError(
f"Unknown browser: {source!r}. Available: {', '.join(available)}"
)
return loader
def _extract_in_process(source: str) -> dict[str, str] | None:
"""Extract cookies in-process for macOS Keychain compatibility."""
try:
loader = _get_browser_loader(source)
except ImportError:
logger.debug("browser_cookie3 not installed, skipping in-process extraction")
return None
except ValueError as exc:
logger.debug("%s", exc)
return None
try:
jar = loader(domain_name=".xiaohongshu.com")
except Exception as exc:
logger.debug("%s in-process extraction failed: %s", source, exc)
return None
cookies = {cookie.name: cookie.value for cookie in jar if "xiaohongshu.com" in (cookie.domain or "")}
if cookies.get("a1"):
logger.debug("Loaded XHS cookies from %s in-process", source)
return cookies
logger.debug("No usable a1 cookie found in %s in-process extraction", source)
return None
def _extract_via_subprocess(source: str) -> dict[str, str] | None:
"""Extract cookies via subprocess to avoid browser SQLite locks."""
extract_script = '''
import json, sys
try:
import browser_cookie3 as bc3
except ImportError:
print(json.dumps({"error": "browser-cookie3 not installed"}))
sys.exit(0)
source = sys.argv[1]
loader = getattr(bc3, source, None)
if not loader or not callable(loader):
print(json.dumps({"error": f"Unknown browser: {source}"}))
sys.exit(0)
try:
cj = loader(domain_name=".xiaohongshu.com")
cookies = {c.name: c.value for c in cj if "xiaohongshu.com" in (c.domain or "")}
if cookies.get("a1"):
print(json.dumps({"browser": source, "cookies": cookies}))
else:
print(json.dumps({"error": "no_a1_cookie"}))
except Exception as e:
print(json.dumps({"error": str(e)}))
'''
try:
result = subprocess.run(
[sys.executable, "-c", extract_script, source],
capture_output=True,
text=True,
timeout=15,
)
if result.returncode != 0:
logger.debug("Cookie extraction subprocess failed: %s", result.stderr)
return None
data = json.loads(result.stdout.strip())
if "error" in data:
logger.debug("Cookie extraction error: %s", data["error"])
return None
return data["cookies"]
except subprocess.TimeoutExpired:
logger.debug("Cookie extraction timed out")
return None
except (json.JSONDecodeError, KeyError) as e:
logger.debug("Cookie extraction parse error: %s", e)
return None
def extract_browser_cookies(source: str = "auto") -> tuple[str, dict[str, str]] | None:
"""
Extract XHS cookies from browser using browser-cookie3.
When *source* is ``"auto"``, tries supported browsers with a small
thread pool and returns the first one that has valid cookies.
Returns ``(browser_name, cookies)`` on success, or ``None``.
"""
if source != "auto":
cookies = _extract_in_process(source)
if cookies:
return source, cookies
cookies = _extract_via_subprocess(source)
if cookies:
return source, cookies
return None
# Auto-detect: try all available browsers
try:
browsers = _available_browsers()
except ImportError:
logger.debug("browser_cookie3 not installed")
return None
from concurrent.futures import FIRST_COMPLETED, ThreadPoolExecutor, wait
def _try_browser(browser: str) -> tuple[str, dict[str, str]] | None:
logger.debug("Auto-detect: trying %s …", browser)
cookies = _extract_in_process(browser)
if cookies:
return browser, cookies
cookies = _extract_via_subprocess(browser)
if cookies:
return browser, cookies
return None
with ThreadPoolExecutor(max_workers=min(4, len(browsers) or 1)) as pool:
pending = {pool.submit(_try_browser, browser) for browser in browsers}
while pending:
done, pending = wait(pending, return_when=FIRST_COMPLETED)
for future in done:
result = future.result()
if result:
for rest in pending:
rest.cancel()
return result
return None
def get_cookies(
cookie_source: str = "auto", *, force_refresh: bool = False
) -> tuple[str, dict[str, str]]:
"""
Multi-strategy cookie acquisition with TTL-based auto-refresh.
Returns ``(browser_name, cookies)``.
1. Load saved cookies (skip if stale > 7 days)
2. Extract from browser (auto-detect if *cookie_source* is ``"auto"``)
3. Raise error if all fail
"""
# 1. Try saved cookies first
if not force_refresh:
saved = load_saved_cookies()
if saved:
saved_at = saved.pop("saved_at", 0)
if saved_at and (time.time() - float(saved_at)) > _COOKIE_TTL_SECONDS:
logger.info(
"Cookies older than %d days, attempting browser refresh",
COOKIE_TTL_DAYS,
)
result = extract_browser_cookies(cookie_source)
if result:
save_cookies(result[1])
return result
logger.warning(
"Cookie refresh failed; using existing cookies (age: %d+ days)",
COOKIE_TTL_DAYS,
)
return "saved", saved
# 2. Try browser extraction
from .exceptions import NoCookieError
result = extract_browser_cookies(cookie_source)
if result:
save_cookies(result[1])
return result
raise NoCookieError(cookie_source)
def cookies_to_string(cookies: dict[str, str]) -> str:
"""Format cookies as a cookie header string."""
return "; ".join(f"{k}={v}" for k, v in cookies.items())
@@ -0,0 +1,71 @@
"""
Creator platform signing (XYW_ prefix) for creator.xiaohongshu.com
Algorithm: MD5(api + JSON(data)) → AES-128-CBC encrypt → XYW_ prefix
Much simpler than main API signing.
Ported from: ~/readers/redbook/src/lib/creator-signing.ts
"""
import base64
import hashlib
import json
import time
from Crypto.Cipher import AES
from Crypto.Util.Padding import pad
AES_KEY = b"7cc4adla5ay0701v"
AES_IV = b"4uzjr7mbsibcaldp"
def _aes_encrypt(data: str) -> str:
"""AES-128-CBC encrypt and return hex string."""
cipher = AES.new(AES_KEY, AES.MODE_CBC, AES_IV)
padded = pad(data.encode("utf-8"), AES.block_size)
encrypted = cipher.encrypt(padded)
return encrypted.hex()
def sign_creator(
api: str,
data: dict | None,
a1: str,
) -> dict[str, str]:
"""
Generate creator platform signature headers.
Args:
api: The API path, prefixed with "url=" (e.g., "url=/web_api/sns/v2/note")
data: Request body data (None for GET requests)
a1: The a1 cookie value
Returns:
Dict with x-s and x-t headers
"""
content = api
if data is not None:
content += json.dumps(data, separators=(",", ":"), ensure_ascii=False)
x1 = hashlib.md5(content.encode("utf-8")).hexdigest()
x2 = "0|0|0|1|0|0|1|0|0|0|1|0|0|0|0|1|0|0|0"
x3 = a1
x4 = int(time.time() * 1000)
plaintext = f"x1={x1};x2={x2};x3={x3};x4={x4};"
payload = _aes_encrypt(base64.b64encode(plaintext.encode("utf-8")).decode("utf-8"))
envelope = {
"signSvn": "56",
"signType": "x2",
"appId": "ugc",
"signVersion": "1",
"payload": payload,
}
xs = "XYW_" + base64.b64encode(json.dumps(envelope, separators=(",", ":")).encode("utf-8")).decode("utf-8")
return {
"x-s": xs,
"x-t": str(x4),
}
@@ -0,0 +1,39 @@
"""Stable error-code mapping for structured CLI output."""
from __future__ import annotations
from .exceptions import (
IpBlockedError,
NeedVerifyError,
NoCookieError,
SessionExpiredError,
SignatureError,
UnsupportedOperationError,
XhsApiError,
)
def error_code_for_exception(exc: Exception) -> str:
"""Map domain exceptions to stable structured error codes."""
if isinstance(exc, (NoCookieError, SessionExpiredError)):
return "not_authenticated"
if isinstance(exc, NeedVerifyError):
return "verification_required"
if isinstance(exc, IpBlockedError):
return "ip_blocked"
if isinstance(exc, SignatureError):
return "signature_error"
if isinstance(exc, UnsupportedOperationError):
return "unsupported_operation"
if isinstance(exc, XhsApiError):
if exc.code in {
"not_authenticated",
"verification_required",
"ip_blocked",
"signature_error",
"unsupported_operation",
"api_error",
}:
return str(exc.code)
return "api_error"
return "unknown_error"
@@ -0,0 +1,64 @@
"""Custom exceptions for XHS API client."""
class XhsApiError(Exception):
"""Base exception for XHS API errors."""
def __init__(self, message: str, code: int | str | None = None, response: dict | None = None):
super().__init__(message)
self.code = code
self.response = response
class NeedVerifyError(XhsApiError):
"""Raised when XHS requires captcha verification."""
def __init__(self, verify_type: str, verify_uuid: str):
super().__init__(f"Captcha required: type={verify_type}, uuid={verify_uuid}")
self.verify_type = verify_type
self.verify_uuid = verify_uuid
class SessionExpiredError(XhsApiError):
"""Raised when the session has expired."""
def __init__(self):
super().__init__("Session expired — please re-login with: xhs login", code=-100)
class IpBlockedError(XhsApiError):
"""Raised when IP is blocked by XHS."""
def __init__(self):
super().__init__("IP blocked by XHS — try a different network", code=300012)
class SignatureError(XhsApiError):
"""Raised when signature verification fails."""
def __init__(self):
super().__init__("Signature verification failed", code=300015)
class UnsupportedOperationError(XhsApiError):
"""Raised when the current web API no longer supports an exposed CLI action."""
def __init__(self, message: str):
super().__init__(message, code="unsupported_operation")
class NoCookieError(XhsApiError):
"""Raised when no valid cookies are found."""
def __init__(self, source: str, details: str = ""):
if source == "auto":
msg = "No 'a1' cookie found for xiaohongshu.com in any installed browser."
else:
msg = f"No 'a1' cookie found for xiaohongshu.com in {source}."
if details:
msg += f"\n{details}"
msg += "\n\nTroubleshooting:\n"
msg += " 1. Open a browser and visit https://www.xiaohongshu.com/\n"
msg += " 2. Make sure you are logged in\n"
msg += " 3. Try: xhs login --cookie-source <browser>"
super().__init__(msg)
@@ -0,0 +1,67 @@
"""Rich formatting utilities for XHS CLI output.
Re-exports from formatter_utils (base utilities) and formatter_renderers
(rich display functions). This module is the public API surface that
commands should import from.
"""
from .formatter_renderers import ( # noqa: F401
render_comments,
render_creator_notes,
render_feed,
render_note,
render_notifications,
render_search_results,
render_topics,
render_user_info,
render_user_posts,
render_users,
)
from .formatter_utils import ( # noqa: F401
coerce_int,
console,
emit_error,
error_console,
error_payload,
format_count,
maybe_print_structured,
print_error,
print_info,
print_json,
print_success,
print_yaml,
resolve_output_format,
success_payload,
)
# ─── URL parsing ────────────────────────────────────────────────────────────
def parse_note_reference(id_or_url: str) -> tuple[str, str, str]:
"""Extract note ID, xsec_token, and xsec_source from a URL or plain ID."""
if "xiaohongshu.com" in id_or_url:
from urllib.parse import parse_qs, urlparse
parsed = urlparse(id_or_url)
parts = parsed.path.rstrip("/").split("/")
note_id = parts[-1]
qs = parse_qs(parsed.query)
xsec_token = qs.get("xsec_token", [""])[0]
xsec_source = qs.get("xsec_source", [""])[0]
return note_id, xsec_token, xsec_source
return id_or_url, "", ""
def parse_note_url(id_or_url: str) -> tuple[str, str]:
"""Extract note ID and xsec_token from URL or plain ID.
Returns (note_id, xsec_token). xsec_token may be empty if not in URL.
"""
note_id, xsec_token, _xsec_source = parse_note_reference(id_or_url)
return note_id, xsec_token
def extract_note_id(id_or_url: str) -> str:
"""Extract note ID from URL or return as-is (drops query params)."""
note_id, _ = parse_note_url(id_or_url)
return note_id
@@ -0,0 +1,187 @@
"""Normalize reverse-engineered API payloads into stable renderer-friendly shapes."""
from __future__ import annotations
from typing import Any
def _coerce_int(value: Any, default: int = 0) -> int:
if isinstance(value, bool):
return int(value)
if isinstance(value, int):
return value
if isinstance(value, str):
try:
return int(value.strip())
except ValueError:
return default
return default
def normalize_user_info(data: dict[str, Any]) -> dict[str, Any]:
basic = data.get("basic_info", data)
interactions = data.get("interactions", [])
stats = {}
for item in interactions:
stats[item.get("type", "")] = item.get("count", "0")
return {
"nickname": basic.get("nickname", basic.get("nick_name", "Unknown")),
"red_id": basic.get("red_id", ""),
"desc": basic.get("desc", ""),
"ip_location": basic.get("ip_location", ""),
"user_id": basic.get("user_id", data.get("user_id", "")),
"gender": basic.get("gender"),
"stats": stats,
}
def normalize_note_detail(data: dict[str, Any]) -> dict[str, Any] | None:
items = data.get("items", [])
if not items:
return None
note = items[0].get("note_card", {})
user = note.get("user", {})
interact = note.get("interact_info", {})
tags = note.get("tag_list", [])
return {
"title": note.get("title", "Untitled"),
"desc": note.get("desc", ""),
"author": user.get("nickname", "Unknown"),
"liked_count": interact.get("liked_count", "0"),
"collected_count": interact.get("collected_count", "0"),
"comment_count": interact.get("comment_count", "0"),
"share_count": interact.get("share_count", "0"),
"tags": [tag.get("name", "") for tag in tags if tag.get("name")],
"image_count": len(note.get("image_list", [])),
}
def normalize_note_summary(item: dict[str, Any]) -> dict[str, Any] | None:
note_card = item.get("note_card", item)
if not isinstance(note_card, dict):
return None
user = note_card.get("user", {})
interact = note_card.get("interact_info", {})
return {
"title": str(note_card.get("title", note_card.get("display_title", "")))[:40],
"author": user.get("nickname", ""),
"liked": str(interact.get("liked_count", "")),
"note_type": "video" if note_card.get("type") == "video" else "image",
"note_id": item.get("id", note_card.get("note_id", "")),
"xsec_token": item.get("xsec_token", note_card.get("xsec_token", "")),
}
def normalize_search_results(data: dict[str, Any]) -> dict[str, Any]:
items = [item for item in (normalize_note_summary(item) for item in data.get("items", [])) if item]
return {
"items": items,
"has_more": bool(data.get("has_more", False)),
}
def normalize_comments(data: dict[str, Any]) -> list[dict[str, Any]]:
normalized = []
for comment in data.get("comments", []):
user = comment.get("user_info", {})
normalized.append({
"nickname": user.get("nickname", "Unknown"),
"content": comment.get("content", ""),
"like_count": comment.get("like_count", "0"),
"sub_comment_count": _coerce_int(comment.get("sub_comment_count", 0)),
})
return normalized
def normalize_feed(data: dict[str, Any]) -> list[dict[str, Any]]:
normalized = []
for item in data.get("items", [])[:20]:
note_card = item.get("note_card", {})
user = note_card.get("user", {})
interact = note_card.get("interact_info", {})
normalized.append({
"title": note_card.get("title", note_card.get("display_title", ""))[:40],
"author": user.get("nickname", ""),
"liked": str(interact.get("liked_count", "")),
"note_id": item.get("id", ""),
"xsec_token": item.get("xsec_token", note_card.get("xsec_token", "")),
})
return normalized
def normalize_user_posts(notes: list[dict[str, Any]]) -> list[dict[str, Any]]:
normalized = []
for note in notes:
interact = note.get("interact_info", {})
normalized.append({
"title": note.get("display_title", "")[:40],
"liked": str(interact.get("liked_count", note.get("liked_count", ""))),
"note_type": "video" if note.get("type") == "video" else "image",
"note_id": note.get("note_id", ""),
})
return normalized
def normalize_topics(data: Any) -> list[dict[str, Any]]:
topics = data if isinstance(data, list) else data.get("topic_info_dtos", [])
return [
{
"name": topic.get("name", ""),
"view_num": topic.get("view_num", 0),
"topic_id": topic.get("id", ""),
}
for topic in topics
]
def normalize_users(data: Any) -> list[dict[str, Any]]:
if isinstance(data, list):
users = data
elif isinstance(data, dict):
users = data.get("user_info_dtos") or data.get("users") or data.get("items") or []
else:
users = []
normalized = []
for user in users:
base = user.get("user_base_dto", user)
normalized.append({
"nickname": base.get("user_nickname", base.get("nickname", base.get("nick_name", ""))),
"red_id": base.get("red_id", ""),
"fans": user.get("fans_total", base.get("fans", base.get("fansCount", 0))),
"user_id": base.get("user_id", base.get("id", "")),
})
return normalized
def normalize_creator_notes(data: Any) -> list[dict[str, Any]]:
notes = data if isinstance(data, list) else data.get("notes", data.get("note_list", []))
normalized = []
for note in notes:
interact = note.get("interact_info", {})
normalized.append({
"title": note.get("title", note.get("display_title", ""))[:40],
"liked": str(note.get("liked_count", interact.get("liked_count", ""))),
"comment_count": str(note.get("comment_count", interact.get("comment_count", ""))),
"status": note.get("status"),
"note_id": note.get("note_id", note.get("id", "")),
})
return normalized
def normalize_notifications(data: dict[str, Any]) -> list[dict[str, Any]]:
normalized = []
for message in data.get("message_list", []):
user = message.get("user_info", {}) or {}
item = message.get("item_info", {}) or {}
normalized.append({
"nickname": user.get("nickname", ""),
"title": message.get("title", ""),
"note_content": item.get("content", ""),
"time": message.get("time", 0),
})
return normalized
@@ -0,0 +1,313 @@
"""Rich renderers for human-readable CLI output."""
from __future__ import annotations
from typing import Any
from rich.panel import Panel
from rich.table import Table
from .formatter_normalizers import (
normalize_comments,
normalize_creator_notes,
normalize_feed,
normalize_note_detail,
normalize_notifications,
normalize_search_results,
normalize_topics,
normalize_user_info,
normalize_user_posts,
normalize_users,
)
from .formatter_utils import coerce_int, console, format_count, print_error, print_info
HOME_URL = "https://www.xiaohongshu.com"
def _build_note_url(
note_id: str,
xsec_token: str = "",
source: str = "pc_feed",
route: str = "explore",
) -> str:
"""Build a full note URL, including xsec_token when available."""
if xsec_token:
return f"{HOME_URL}/{route}/{note_id}?xsec_token={xsec_token}&xsec_source={source}"
return note_id # bare ID fallback
def _build_note_link(
note_id: str,
xsec_token: str = "",
source: str = "pc_feed",
route: str = "explore",
) -> str:
url = _build_note_url(note_id, xsec_token=xsec_token, source=source, route=route)
label = f"{route}/{note_id}"
if xsec_token:
return f"[link={url}][dim]{label}[/dim][/link]"
return f"[dim]{label}[/dim]"
def render_user_info(data: dict[str, Any]) -> None:
"""Render user profile info as a Rich panel."""
user = normalize_user_info(data)
nickname = user["nickname"]
red_id = user["red_id"]
desc = user["desc"]
ip_location = user["ip_location"]
user_id = user["user_id"]
gender_val = user["gender"]
gender = "♂️" if gender_val == 0 else "♀️" if gender_val == 1 else ""
stats = user["stats"]
table = Table(show_header=False, box=None, padding=(0, 2))
table.add_column("Key", style="dim")
table.add_column("Value")
table.add_row("昵称", f"[bold]{nickname}[/bold] {gender}")
if red_id:
table.add_row("小红书号", red_id)
if user_id:
table.add_row("User ID", user_id)
if desc:
table.add_row("简介", desc)
if ip_location:
table.add_row("IP 属地", ip_location)
if "fans" in stats:
table.add_row("粉丝", format_count(stats["fans"]))
if "follows" in stats:
table.add_row("关注", format_count(stats["follows"]))
if "interaction" in stats:
table.add_row("获赞与收藏", format_count(stats["interaction"]))
console.print(Panel(table, title=f"👤 {nickname}", border_style="blue"))
def render_note(data: dict[str, Any]) -> None:
"""Render a note as a Rich panel."""
note = normalize_note_detail(data)
if not note:
print_error("No note data found")
return
title = note["title"]
desc = note["desc"]
nickname = note["author"]
liked_count = note["liked_count"]
collected_count = note["collected_count"]
comment_count = note["comment_count"]
share_count = note["share_count"]
table = Table(show_header=False, box=None, padding=(0, 2))
table.add_column("Key", style="dim")
table.add_column("Value")
table.add_row("作者", f"[bold]{nickname}[/bold]")
table.add_row("标题", f"[bold]{title}[/bold]")
if desc:
display_desc = desc[:500] + "..." if len(desc) > 500 else desc
table.add_row("正文", display_desc)
tags = note["tags"]
if tags:
tag_str = " ".join(f"[cyan]#{tag}[/cyan]" for tag in tags)
table.add_row("标签", tag_str)
stats_str = (
f"❤️ {format_count(liked_count)} "
f"⭐ {format_count(collected_count)} "
f"💬 {format_count(comment_count)} "
f"🔗 {format_count(share_count)}"
)
table.add_row("数据", stats_str)
if note["image_count"]:
table.add_row("图片", f"{note['image_count']} 张")
console.print(Panel(table, title=f"📝 {title}", border_style="green"))
def render_search_results(data: dict[str, Any]) -> None:
"""Render search results as a Rich table."""
normalized = normalize_search_results(data)
items = normalized["items"]
if not items:
print_info("No results found")
return
has_next = normalized["has_more"]
table = Table(title="搜索结果", show_lines=True)
table.add_column("#", style="dim", width=3)
table.add_column("标题", width=30)
table.add_column("作者", width=10)
table.add_column("❤️", justify="right", width=8)
table.add_column("类型", width=4)
table.add_column("链接", style="cyan", no_wrap=True)
for i, item in enumerate(items, 1):
note_type = "📹" if item["note_type"] == "video" else "📷"
link = _build_note_link(
item["note_id"],
item.get("xsec_token", ""),
source="pc_search",
route="search_result",
)
table.add_row(str(i), item["title"], item["author"], item["liked"], note_type, link)
console.print(table)
if has_next:
print_info("More results available — use --page to paginate")
def render_comments(data: dict[str, Any]) -> None:
"""Render comments as a Rich display."""
comments = normalize_comments(data)
if not comments:
print_info("No comments found")
return
for comment in comments:
nickname = comment["nickname"]
content = comment["content"]
like_count = format_count(comment["like_count"])
sub_comment_count = coerce_int(comment["sub_comment_count"])
header = f"[bold]{nickname}[/bold] [dim]❤️ {like_count}[/dim]"
if sub_comment_count > 0:
header += f" [dim]💬 {sub_comment_count} replies[/dim]"
console.print(header)
console.print(f" {content}")
console.print()
def render_feed(data: dict[str, Any]) -> None:
"""Render feed items as a Rich table."""
items = normalize_feed(data)
if not items:
print_info("No feed items")
return
table = Table(title="推荐页", show_lines=True)
table.add_column("#", style="dim", width=3)
table.add_column("标题", width=30)
table.add_column("作者", width=10)
table.add_column("❤️", justify="right", width=8)
table.add_column("链接", style="cyan", no_wrap=True)
for i, item in enumerate(items, 1):
link = _build_note_link(item["note_id"], item.get("xsec_token", ""), source="pc_feed")
table.add_row(str(i), item["title"], item["author"], item["liked"], link)
console.print(table)
def render_user_posts(notes: list[dict[str, Any]]) -> None:
"""Render a list of user's notes."""
normalized = normalize_user_posts(notes)
if not normalized:
print_info("No notes found")
return
table = Table(title="用户笔记", show_lines=True)
table.add_column("#", style="dim", width=3)
table.add_column("标题", width=30)
table.add_column("❤️", justify="right", width=8)
table.add_column("类型", width=4)
table.add_column("ID", style="dim", width=24)
for i, note in enumerate(normalized, 1):
note_type = "📹" if note["note_type"] == "video" else "📷"
table.add_row(str(i), note["title"], note["liked"], note_type, note["note_id"])
console.print(table)
def render_topics(data: Any) -> None:
"""Render topic search results."""
topics = normalize_topics(data)
if not topics:
print_info("No topics found")
return
table = Table(title="话题", show_lines=True)
table.add_column("#", style="dim", width=3)
table.add_column("话题名", width=15)
table.add_column("热度", justify="right", width=10)
table.add_column("ID", style="dim", width=24)
for i, topic in enumerate(topics, 1):
table.add_row(str(i), f"#{topic['name']}", format_count(topic["view_num"]), topic["topic_id"])
console.print(table)
def render_users(data: Any) -> None:
"""Render user search/list results."""
users = normalize_users(data)
if not users:
print_info("No users found")
return
table = Table(title="用户列表", show_lines=True)
table.add_column("#", style="dim", width=3)
table.add_column("昵称", width=14)
table.add_column("小红书号", width=12)
table.add_column("粉丝", justify="right", width=8)
table.add_column("ID", style="dim", width=24)
for i, user in enumerate(users, 1):
table.add_row(str(i), user["nickname"], user["red_id"], format_count(user["fans"]), user["user_id"])
console.print(table)
def render_creator_notes(data: Any) -> None:
"""Render creator's own note list."""
notes = normalize_creator_notes(data)
if not notes:
print_info("No notes found")
return
table = Table(title="我的笔记", show_lines=True)
table.add_column("#", style="dim", width=3)
table.add_column("标题", width=30)
table.add_column("❤️", justify="right", width=8)
table.add_column("💬", justify="right", width=6)
table.add_column("状态", width=6)
table.add_column("ID", style="dim", width=24)
for i, note in enumerate(notes, 1):
status = "✅" if note["status"] in (None, 0, "published") else "⏳"
table.add_row(str(i), note["title"], note["liked"], note["comment_count"], status, note["note_id"])
console.print(table)
def render_notifications(data: dict[str, Any], notif_type: str) -> None:
"""Render notification messages."""
import time as _time
messages = normalize_notifications(data)
if not messages:
print_info("No notifications")
return
table = Table(title=f"通知 — {notif_type}", show_lines=True)
table.add_column("#", style="dim", width=3)
table.add_column("用户", width=12)
table.add_column("内容", width=40)
table.add_column("时间", width=12)
for i, msg in enumerate(messages[:20], 1):
nickname = msg["nickname"]
title = msg["title"]
note_content = msg["note_content"]
display = title + (f"\n{note_content[:30]}" if note_content else "")
ts = msg["time"]
time_str = _time.strftime("%m-%d %H:%M", _time.localtime(ts)) if ts else ""
table.add_row(str(i), nickname, display, time_str)
console.print(table)
@@ -0,0 +1,187 @@
"""Base formatting utilities shared across formatter modules.
This module breaks the circular dependency between formatter.py and
formatter_renderers.py by providing the shared primitives both need.
"""
import json
import os
import sys
from typing import Any
import click
import yaml
from rich.console import Console
console = Console(stderr=True)
error_console = Console(stderr=True)
_stdout = Console()
_OUTPUT_ENV = "OUTPUT"
_SCHEMA_VERSION = "1"
# ─── Output format resolution ──────────────────────────────────────────────
def resolve_output_format(*, as_json: bool, as_yaml: bool) -> str | None:
"""Resolve explicit flags first, then env override, then TTY default."""
if as_json and as_yaml:
raise click.UsageError("Use only one of --json or --yaml.")
if as_yaml:
return "yaml"
if as_json:
return "json"
output_mode = os.getenv(_OUTPUT_ENV, "auto").strip().lower()
if output_mode == "yaml":
return "yaml"
if output_mode == "json":
return "json"
if output_mode == "rich":
return None
if not sys.stdout.isatty():
return "yaml"
return None
# ─── Structured output ─────────────────────────────────────────────────────
def print_json(data: Any) -> None:
"""Print raw JSON output to stdout."""
_stdout.print_json(json.dumps(data, ensure_ascii=False, indent=2))
def print_yaml(data: Any) -> None:
"""Print raw YAML output to stdout."""
click.echo(
yaml.safe_dump(
data,
allow_unicode=True,
sort_keys=False,
default_flow_style=False,
)
)
def success_payload(data: Any) -> dict[str, Any]:
"""Wrap structured success data in the shared agent schema."""
return {
"ok": True,
"schema_version": _SCHEMA_VERSION,
"data": data,
}
def error_payload(code: str, message: str, *, details: Any | None = None) -> dict[str, Any]:
"""Wrap structured error data in the shared agent schema."""
error = {
"code": code,
"message": message,
}
if details is not None:
error["details"] = details
return {
"ok": False,
"schema_version": _SCHEMA_VERSION,
"error": error,
}
def _normalize_success_payload(data: Any) -> Any:
"""Wrap plain structured data in the shared agent success schema."""
if isinstance(data, dict) and data.get("schema_version") == _SCHEMA_VERSION and "ok" in data:
return data
return success_payload(data)
def maybe_print_structured(data: Any, *, as_json: bool, as_yaml: bool) -> bool:
"""Print structured output when requested or when stdout is non-TTY."""
fmt = resolve_output_format(as_json=as_json, as_yaml=as_yaml)
if not fmt:
return False
payload = _normalize_success_payload(data)
if fmt == "json":
print_json(payload)
else:
print_yaml(payload)
return True
def emit_error(
code: str,
message: str,
*,
as_json: bool | None = None,
as_yaml: bool | None = None,
details: Any | None = None,
) -> bool:
"""Emit a structured error when the active output mode is machine-readable."""
if as_json is None or as_yaml is None:
ctx = click.get_current_context(silent=True)
params = ctx.params if ctx is not None else {}
as_json = bool(params.get("as_json", False)) if as_json is None else as_json
as_yaml = bool(params.get("as_yaml", False)) if as_yaml is None else as_yaml
fmt = resolve_output_format(as_json=bool(as_json), as_yaml=bool(as_yaml))
if fmt is None:
return False
payload = error_payload(code, message, details=details)
if fmt == "json":
print_json(payload)
else:
print_yaml(payload)
return True
# ─── UI helpers ─────────────────────────────────────────────────────────────
def print_error(message: str) -> None:
"""Print error message."""
if emit_error("api_error", message):
return
error_console.print(f"[red]✗[/red] {message}")
def print_success(message: str) -> None:
"""Print success message."""
console.print(f"[green]✓[/green] {message}")
def print_info(message: str) -> None:
"""Print info message."""
console.print(f"[dim]ℹ[/dim] {message}")
# ─── Data formatting ───────────────────────────────────────────────────────
def coerce_int(value: Any, default: int = 0) -> int:
"""Best-effort integer coercion for reverse-engineered API fields."""
if isinstance(value, bool):
return int(value)
if isinstance(value, int):
return value
if isinstance(value, str):
try:
return int(value.strip())
except ValueError:
return default
return default
def format_count(n: int | str) -> str:
"""Format number for display (e.g., 12345 → 1.2万)."""
if isinstance(n, str):
try:
n = int(n)
except ValueError:
return str(n)
if n >= 100_000_000:
return f"{n / 100_000_000:.1f}亿"
if n >= 10_000:
return f"{n / 10_000:.1f}万"
return str(n)
@@ -0,0 +1,73 @@
"""Parse note data from Xiaohongshu HTML pages (SSR __INITIAL_STATE__).
This module provides an alternative to the feed API for reading notes.
The HTML endpoint embeds note data in a server-rendered `window.__INITIAL_STATE__`
object, which does not require a valid xsec_token to access.
"""
from __future__ import annotations
import json
import logging
import re
from typing import Any
from .exceptions import XhsApiError
logger = logging.getLogger(__name__)
# Regex to extract the __INITIAL_STATE__ JSON blob from the HTML.
_STATE_PATTERN = re.compile(r"window\.__INITIAL_STATE__=({.*?})\s*</script>", re.DOTALL)
def parse_initial_state(html: str) -> dict[str, Any]:
"""Extract and parse `window.__INITIAL_STATE__` from an XHS note page.
The server-rendered HTML contains a global state object with note data.
XHS uses bare `undefined` values in the JS object which are not valid JSON,
so we replace them before parsing.
"""
match = _STATE_PATTERN.search(html)
if not match:
raise XhsApiError("Could not parse __INITIAL_STATE__ from HTML")
raw = match.group(1)
# Replace bare `undefined` with empty string (not valid JSON)
cleaned = re.sub(r":\s*undefined", ':""', raw)
cleaned = re.sub(r",\s*undefined", ',""', cleaned)
try:
return json.loads(cleaned)
except json.JSONDecodeError as exc:
raise XhsApiError(f"Failed to parse __INITIAL_STATE__ JSON: {exc}") from None
def extract_note_from_state(
state: dict[str, Any],
note_id: str,
) -> dict[str, Any]:
"""Extract a single note dict from the parsed __INITIAL_STATE__.
The state structure is:
state.note.noteDetailMap[note_id].note -> full note object
"""
detail_map = state.get("note", {}).get("noteDetailMap", {})
if not detail_map:
raise XhsApiError("Note not found in HTML state: empty noteDetailMap")
# Try exact noteId first, then fall back to first entry
entry = detail_map.get(note_id)
if entry is None:
entry = next(iter(detail_map.values()), None)
if entry and isinstance(entry, dict) and "note" in entry:
return entry["note"]
raise XhsApiError("Note not found in HTML state")
def extract_note_from_html(html: str, note_id: str) -> dict[str, Any]:
"""High-level: parse HTML → extract note in one step."""
state = parse_initial_state(html)
return extract_note_from_state(state, note_id)
@@ -0,0 +1,56 @@
"""Helpers for resolving and persisting note references across commands."""
from __future__ import annotations
import click
from .cookies import get_note_by_index, save_note_index
from .formatter import parse_note_reference
def resolve_note_reference(id_or_url: str, *, xsec_token: str = "") -> tuple[str, str, str]:
"""Resolve a note reference from URL/ID or the last listing index."""
if id_or_url.isdigit():
entry = get_note_by_index(int(id_or_url))
if entry is None:
raise click.UsageError(
f"Index {id_or_url} not found — run a listing command first "
"(search / feed / hot / user-posts / favorites / my-notes)"
)
return (
entry["note_id"],
xsec_token or entry.get("xsec_token", ""),
entry.get("xsec_source", ""),
)
note_id, url_token, url_source = parse_note_reference(id_or_url)
return note_id, xsec_token or url_token, url_source
def save_index_from_items(data: dict, *, xsec_source: str) -> None:
"""Persist ordered note references from list-style responses."""
entries = []
for item in data.get("items", []):
note_card = item.get("note_card", {})
note_id = item.get("id", note_card.get("note_id", ""))
token = item.get("xsec_token", note_card.get("xsec_token", ""))
if note_id:
entries.append({
"note_id": note_id,
"xsec_token": token,
"xsec_source": xsec_source if token else "",
})
save_note_index(entries)
def save_index_from_notes(notes: list[dict]) -> None:
"""Persist ordered note references from paged note payloads."""
save_note_index([
{
"note_id": str(note.get("note_id", note.get("id", ""))).strip(),
"xsec_token": str(note.get("xsec_token", "")).strip(),
"xsec_source": "",
}
for note in notes
if str(note.get("note_id", note.get("id", ""))).strip()
])
+548
View File
@@ -0,0 +1,548 @@
"""QR code login for Xiaohongshu.
Supports two backends:
1. Browser-assisted login via Camoufox. The browser performs the real
QR completion flow, while the CLI renders the QR code in the terminal
from the browser's ``qrcode/create`` response and exports cookies after
login succeeds.
2. Legacy pure-HTTP login flow. This remains as a fallback when the
browser backend is unavailable.
"""
from __future__ import annotations
import logging
import random
import subprocess
import sys
import time
from typing import Any
from .client import XhsClient
from .cookies import save_cookies
from .exceptions import NeedVerifyError, XhsApiError
logger = logging.getLogger(__name__)
LOGIN_URL = "https://www.xiaohongshu.com/login"
QR_CREATE_ENDPOINT = "/api/sns/web/v1/login/qrcode/create"
QR_USERINFO_ENDPOINT = "/api/qrcode/userinfo"
QR_STATUS_ENDPOINT = "/api/sns/web/v1/login/qrcode/status"
# QR code status values
QR_WAITING = 0 # Waiting for scan
QR_SCANNED = 1 # Scanned, awaiting confirmation
QR_CONFIRMED = 2 # Login confirmed
# Poll config
POLL_INTERVAL_S = 2.0
POLL_TIMEOUT_S = 240 # 4 minutes
BROWSER_EXPORT_COOKIE_NAMES = (
"a1",
"webId",
"web_session",
"web_session_sec",
"id_token",
"websectiga",
"sec_poison_id",
"xsecappid",
"gid",
"abRequestId",
"webBuild",
"loadts",
)
class BrowserQrLoginUnavailable(XhsApiError):
"""Raised when the browser-assisted QR backend cannot be started."""
def _emit_status(on_status: callable[[str], None] | None, msg: str) -> None:
"""Send a status message to the callback or stdout."""
if on_status:
on_status(msg)
else:
print(msg)
def _apply_session_cookies(client: XhsClient, payload: dict[str, Any]) -> None:
"""Persist any session cookies returned by the QR login endpoints."""
login_info = payload.get("login_info", {})
if not isinstance(login_info, dict):
login_info = {}
session = payload.get("session") or login_info.get("session", "")
secure_session = payload.get("secure_session") or login_info.get("secure_session", "")
if session:
client.cookies["web_session"] = str(session)
if secure_session:
client.cookies["web_session_sec"] = str(secure_session)
def _build_saved_cookies(a1: str, webid: str, payload: dict[str, Any]) -> dict[str, str]:
"""Build the cookie payload persisted after QR login succeeds."""
login_info = payload.get("login_info", {})
if not isinstance(login_info, dict):
login_info = {}
session = payload.get("session") or login_info.get("session") or payload.get("web_session", "")
secure_session = (
payload.get("secure_session")
or login_info.get("secure_session")
or payload.get("web_session_sec", "")
)
cookies = {
"a1": a1,
"webId": webid,
}
if session:
cookies["web_session"] = str(session)
if secure_session:
cookies["web_session_sec"] = str(secure_session)
return cookies
def _normalize_browser_cookies(raw_cookies: list[dict[str, Any]]) -> dict[str, str]:
"""Convert Playwright cookies into the local persisted cookie shape."""
cookies: dict[str, str] = {}
for entry in raw_cookies:
name = entry.get("name")
value = entry.get("value")
domain = entry.get("domain", "")
if not isinstance(name, str) or not isinstance(value, str):
continue
if name not in BROWSER_EXPORT_COOKIE_NAMES:
continue
if not isinstance(domain, str) or "xiaohongshu.com" not in domain:
continue
cookies[name] = value
return cookies
def _unwrap_browser_response_payload(payload: dict[str, Any]) -> dict[str, Any]:
"""Return the inner `data` payload when browser responses use the common envelope."""
data = payload.get("data")
if isinstance(data, dict):
return data
return payload
def _browser_response_payload(response: Any) -> dict[str, Any]:
"""Decode a browser response body as JSON and unwrap the common envelope."""
try:
data = response.json()
except Exception as exc:
raise XhsApiError(f"Browser response from {response.url} was not valid JSON.") from exc
if not isinstance(data, dict):
raise XhsApiError(f"Browser response from {response.url} returned unexpected payload: {data!r}")
return _unwrap_browser_response_payload(data)
def _raise_for_browser_response(response: Any) -> None:
"""Map browser QR completion failures onto the same domain errors as the HTTP client."""
status = getattr(response, "status", None)
if status in (461, 471):
raise NeedVerifyError(
verify_type=response.headers.get("verifytype", "unknown"),
verify_uuid=response.headers.get("verifyuuid", "unknown"),
)
if status and status >= 400:
try:
body = response.text()
except Exception:
body = "<unavailable>"
raise XhsApiError(
f"Browser-assisted QR completion failed: HTTP {status} body={body[:300]}"
)
def _wait_for_browser_login_settled(page: Any) -> None:
"""Wait briefly for the browser session and post-login page state to stabilize."""
try:
page.wait_for_url("**/explore*", timeout=5_000)
except Exception:
logger.debug("Browser-assisted QR login did not navigate to /explore before timeout")
try:
response = page.wait_for_response(
lambda resp: "/api/sns/web/v2/user/me" in resp.url and resp.request.method == "GET",
timeout=5_000,
)
except Exception:
logger.debug("Browser-assisted QR login did not observe a post-login user/me response before timeout")
return
try:
payload = _browser_response_payload(response)
except Exception as exc:
logger.debug("Failed to parse browser user/me response after QR login: %s", exc)
return
if bool(payload.get("guest", False)):
logger.debug("Browser-assisted QR login settled with guest=true in user/me payload: %s", payload)
def _resolved_user_id(info: dict[str, object]) -> str:
"""Extract the current user ID from activate/self payloads."""
if not isinstance(info, dict):
return ""
login_info = info.get("login_info")
if isinstance(login_info, dict) and login_info.get("user_id"):
return str(login_info["user_id"])
basic = info.get("basic_info", info)
if isinstance(basic, dict) and basic.get("user_id"):
return str(basic["user_id"])
if info.get("user_id"):
return str(info["user_id"])
if info.get("userid"):
return str(info["userid"])
return ""
def _complete_confirmed_session(
client: XhsClient,
qr_id: str,
code: str,
confirmed_user_id: str,
*,
retries: int = 5,
wait_s: float = 1.0,
) -> dict[str, object]:
"""Finalize QR login after confirmation until the session switches users."""
last_data: dict[str, object] = {}
last_self_info_user_id = ""
for attempt in range(retries):
completion_data = client.complete_qr_login(qr_id, code)
_apply_session_cookies(client, completion_data)
last_data = completion_data
completed_user_id = _resolved_user_id(completion_data)
self_info_user_id = ""
try:
self_info_user_id = _resolved_user_id(client.get_self_info())
last_self_info_user_id = self_info_user_id
except Exception as exc:
logger.debug(
"QR post-confirm self info check failed attempt=%d: %s",
attempt + 1,
exc,
)
logger.debug(
"QR post-confirm completion attempt=%d confirmed_user_id=%s "
"completion_user_id=%s self_info_user_id=%s cookies=%s data=%s",
attempt + 1,
confirmed_user_id,
completed_user_id,
self_info_user_id,
{
"web_session": client.cookies.get("web_session"),
"web_session_sec": client.cookies.get("web_session_sec"),
},
completion_data,
)
if completed_user_id and completed_user_id == confirmed_user_id:
return completion_data
if self_info_user_id and self_info_user_id == confirmed_user_id:
return completion_data
if attempt + 1 < retries:
time.sleep(wait_s)
raise XhsApiError(
"QR login confirmed, but completion never returned the confirmed user session. "
f"expected={confirmed_user_id} "
f"completion_user={_resolved_user_id(last_data) or 'unknown'} "
f"self_info_user={last_self_info_user_id or 'unknown'} "
f"completion_data={last_data}"
)
def _generate_a1() -> str:
"""Generate a fresh a1 cookie value (52 hex chars with embedded timestamp)."""
prefix = "".join(random.choices("0123456789abcdef", k=24))
ts = str(int(time.time() * 1000))
suffix = "".join(random.choices("0123456789abcdef", k=15))
return prefix + ts + suffix
def _generate_webid() -> str:
"""Generate a webId cookie value (32 hex chars)."""
return "".join(random.choices("0123456789abcdef", k=32))
def _render_qr_half_blocks(matrix: list[list[bool]]) -> str:
"""Render QR matrix using half-block characters (▀▄█ and space)."""
if not matrix:
return ""
size = len(matrix)
lines: list[str] = []
for row_idx in range(0, size, 2):
line = ""
for col_idx in range(size):
top = matrix[row_idx][col_idx]
bot = matrix[row_idx + 1][col_idx] if row_idx + 1 < size else False
if top and bot:
line += "█"
elif top and not bot:
line += "▀"
elif not top and bot:
line += "▄"
else:
line += " "
lines.append(line)
return "\n".join(lines)
def _display_qr_in_terminal(data: str) -> bool:
"""Display *data* as a QR code in the terminal. Returns True on success."""
try:
import qrcode # type: ignore[import-untyped]
except ImportError:
return False
qr = qrcode.QRCode(border=4)
qr.add_data(data)
qr.make(fit=True)
modules = qr.get_matrix()
print(_render_qr_half_blocks(modules))
return True
def _ensure_camoufox_ready() -> None:
"""Validate that the Camoufox package and browser binary are available."""
try:
import camoufox # noqa: F401
except ImportError as exc:
raise BrowserQrLoginUnavailable(
"Browser-assisted QR login requires the `camoufox` package."
) from exc
try:
result = subprocess.run(
[sys.executable, "-m", "camoufox", "path"],
capture_output=True,
text=True,
timeout=15,
)
except (OSError, subprocess.SubprocessError) as exc:
raise BrowserQrLoginUnavailable(
"Unable to validate the Camoufox browser installation."
) from exc
if result.returncode != 0 or not result.stdout.strip():
raise BrowserQrLoginUnavailable(
"Camoufox browser runtime is missing. Run `python -m camoufox fetch` first."
)
def _browser_assisted_qrcode_login(
*,
on_status: callable[[str], None] | None = None,
timeout_s: int = POLL_TIMEOUT_S,
) -> dict[str, str]:
"""Log in by letting a real browser complete the QR flow, then export cookies."""
_ensure_camoufox_ready()
try:
from camoufox.sync_api import Camoufox
except ImportError as exc:
raise BrowserQrLoginUnavailable(
"Camoufox sync API is unavailable in the current environment."
) from exc
state = {"last_status": -1}
_emit_status(on_status, "🔑 Starting browser-assisted QR login...")
with Camoufox(headless=False) as browser:
page = browser.new_page()
def _handle_response(response) -> None:
url = response.url
if QR_USERINFO_ENDPOINT not in url:
return
try:
payload = _unwrap_browser_response_payload(response.json())
except Exception as exc:
logger.debug("Failed to parse browser QR poll response: %s", exc)
return
code_status = int(payload.get("codeStatus", -1))
if code_status == state["last_status"]:
return
state["last_status"] = code_status
if code_status == QR_SCANNED:
_emit_status(on_status, "📲 Scanned! Waiting for confirmation...")
elif code_status == QR_CONFIRMED:
_emit_status(on_status, "✅ Login confirmed!")
page.on("response", _handle_response)
try:
with page.expect_response(
lambda response: QR_CREATE_ENDPOINT in response.url and response.request.method == "POST",
timeout=20_000,
) as qr_response_info:
page.goto(LOGIN_URL, wait_until="domcontentloaded")
except Exception as exc:
raise XhsApiError("Failed to load Xiaohongshu login page in Camoufox.") from exc
qr_payload = _browser_response_payload(qr_response_info.value)
qr_url = str(qr_payload.get("url", "")).strip()
if not qr_url:
raise XhsApiError(f"Browser-assisted QR login did not expose a QR URL: {qr_payload}")
_emit_status(on_status, "\n📱 Scan the QR code below with the Xiaohongshu app:\n")
if not _display_qr_in_terminal(qr_url):
_emit_status(on_status, "⚠️ Install 'qrcode' for terminal rendering: pip install qrcode")
_emit_status(on_status, f"QR URL: {qr_url}")
_emit_status(on_status, "\n⏳ Waiting for QR code scan...")
try:
with page.expect_response(
lambda response: QR_STATUS_ENDPOINT in response.url and response.request.method == "GET",
timeout=timeout_s * 1000,
) as completion_info:
pass
except Exception as exc:
raise XhsApiError("QR code login timed out while waiting for browser completion.") from exc
_raise_for_browser_response(completion_info.value)
completion_data = _browser_response_payload(completion_info.value)
login_info = completion_data.get("login_info", {})
if not isinstance(login_info, dict):
login_info = {}
_wait_for_browser_login_settled(page)
cookies = _normalize_browser_cookies(page.context.cookies())
session = login_info.get("session")
secure_session = login_info.get("secure_session")
if isinstance(session, str) and session:
cookies["web_session"] = session
if isinstance(secure_session, str) and secure_session:
cookies["web_session_sec"] = secure_session
required = ("a1", "webId", "web_session")
missing = [name for name in required if not cookies.get(name)]
if missing:
raise XhsApiError(
"Browser-assisted QR login succeeded, but exported cookies were incomplete: "
f"missing={', '.join(missing)} completion_data={completion_data}"
)
save_cookies(cookies)
user_id = str(login_info.get("user_id", "")).strip() or _resolved_user_id(completion_data)
if user_id:
_emit_status(on_status, f"👤 User ID: {user_id}")
return cookies
def _http_qrcode_login(
*,
on_status: callable[[str], None] | None = None,
timeout_s: int = POLL_TIMEOUT_S,
) -> dict[str, str]:
"""Run the legacy pure-HTTP QR login flow."""
a1 = _generate_a1()
webid = _generate_webid()
tmp_cookies = {"a1": a1, "webId": webid}
_emit_status(on_status, "🔑 Starting QR code login...")
with XhsClient(tmp_cookies, request_delay=0) as client:
try:
activate_data = client.login_activate()
_apply_session_cookies(client, activate_data)
guest_session = activate_data.get("session", "")
logger.debug(
"Initial activate: session=%s user_id=%s",
guest_session, activate_data.get("user_id"),
)
except Exception as exc:
logger.debug("Initial activate failed (non-fatal): %s", exc)
qr_data = client.create_qr_login()
qr_id = qr_data["qr_id"]
code = qr_data["code"]
qr_url = qr_data["url"]
logger.debug("QR created: qr_id=%s, code=%s", qr_id, code)
_emit_status(on_status, "\n📱 Scan the QR code below with the Xiaohongshu app:\n")
if not _display_qr_in_terminal(qr_url):
_emit_status(on_status, "⚠️ Install 'qrcode' for terminal rendering: pip install qrcode")
_emit_status(on_status, f"QR URL: {qr_url}")
_emit_status(on_status, "\n⏳ Waiting for QR code scan...")
start = time.time()
last_status = -1
consecutive_errors = 0
while (time.time() - start) < timeout_s:
time.sleep(POLL_INTERVAL_S)
try:
status_data = client.check_qr_status(qr_id, code)
except Exception as exc:
logger.debug("QR status check error: %s", exc)
consecutive_errors += 1
if consecutive_errors >= 3:
raise XhsApiError(f"QR status polling failed repeatedly: {exc}") from exc
continue
else:
consecutive_errors = 0
code_status = status_data.get("codeStatus", -1)
logger.debug("QR poll: codeStatus=%s data=%s", code_status, status_data)
if code_status != last_status:
last_status = code_status
if code_status == QR_SCANNED:
_emit_status(on_status, "📲 Scanned! Waiting for confirmation...")
elif code_status == QR_CONFIRMED:
_emit_status(on_status, "✅ Login confirmed!")
if code_status == QR_CONFIRMED:
confirmed_user_id = status_data.get("userId", "")
if not confirmed_user_id:
raise XhsApiError("QR login confirmed but no confirmed userId was returned.")
completion_data = _complete_confirmed_session(
client,
qr_id,
code,
confirmed_user_id,
)
user_id = _resolved_user_id(completion_data) or confirmed_user_id
cookies = _build_saved_cookies(a1, webid, client.cookies)
save_cookies(cookies)
_emit_status(on_status, f"👤 User ID: {user_id}")
return cookies
elapsed = time.time() - start
if int(elapsed) % 30 == 0 and int(elapsed) > 0:
_emit_status(on_status, " Still waiting...")
raise XhsApiError("QR code login timed out after 4 minutes")
def qrcode_login(
*,
on_status: callable[[str], None] | None = None,
timeout_s: int = POLL_TIMEOUT_S,
prefer_browser_assisted: bool = False,
) -> dict[str, str]:
"""Run the QR code login flow."""
if prefer_browser_assisted:
try:
return _browser_assisted_qrcode_login(on_status=on_status, timeout_s=timeout_s)
except BrowserQrLoginUnavailable as exc:
logger.info("Browser-assisted QR login unavailable, falling back to HTTP flow: %s", exc)
return _http_qrcode_login(on_status=on_status, timeout_s=timeout_s)
+85
View File
@@ -0,0 +1,85 @@
"""
Main API signing for edith.xiaohongshu.com
Thin adapter over the xhshow library, configured for macOS/Chrome.
Maintains a persistent SessionManager for realistic session simulation.
Public API (unchanged from previous implementation):
- sign_main_api(method, uri, cookies, ...) -> dict of 5 headers
- build_get_uri(uri, params) -> str
- extract_uri(url) -> str
"""
from __future__ import annotations
from xhshow import CryptoConfig, SessionManager, Xhshow
from xhshow.utils.url_utils import extract_uri # noqa: F401 — re-export
from .constants import APP_ID, PLATFORM, SDK_VERSION, USER_AGENT
# ─── macOS/Chrome configuration ────────────────────────────────────────────
_config = CryptoConfig().with_overrides(
PUBLIC_USERAGENT=USER_AGENT,
SIGNATURE_DATA_TEMPLATE={
"x0": SDK_VERSION,
"x1": APP_ID,
"x2": PLATFORM,
"x3": "",
"x4": "",
},
SIGNATURE_XSCOMMON_TEMPLATE={
"s0": 5,
"s1": "",
"x0": "1",
"x1": SDK_VERSION,
"x2": PLATFORM,
"x3": APP_ID,
"x4": "4.86.0",
"x5": "",
"x6": "",
"x7": "",
"x8": "",
"x9": -596800761,
"x10": 0,
"x11": "normal",
},
)
_xhshow = Xhshow(_config)
_session = SessionManager(_config)
# ─── Public API ─────────────────────────────────────────────────────────────
def sign_main_api(
method: str,
uri: str,
cookies: dict[str, str],
params: dict[str, str | int | list[str]] | None = None,
payload: dict | None = None,
timestamp: float | None = None,
) -> dict[str, str]:
"""
Generate all signing headers for a main API (edith.xiaohongshu.com) request.
Returns dict with keys: x-s, x-s-common, x-t, x-b3-traceid, x-xray-traceid
"""
if method.upper() == "GET":
return _xhshow.sign_headers_get(
uri, cookies, params=params, timestamp=timestamp, session=_session,
)
return _xhshow.sign_headers_post(
uri, cookies, payload=payload, timestamp=timestamp, session=_session,
)
def build_get_uri(
uri: str,
params: dict[str, str | int | list[str]] | None = None,
) -> str:
"""Build URI with query parameters for GET requests."""
if not params:
return uri
return _xhshow.build_url(uri, params)