tytcli 0.2.0__py3-none-any.whl

tytcli/client.py

@@ -0,0 +1,832 @@
+"""Minimal HTTP client for the 投研通 (TYT) API.
+
+Contract facts below were verified against the live service on 2026-11-06 by
+probing both environments.  They are load-bearing — do not "simplify" them
+without re-verifying:
+
+1. ``POST`` only.  A ``GET`` to the same URL returns ``ErrorCode -1``.
+2. A JSON request body is **mandatory**, but ``{}`` is sufficient.  Sending no
+   body at all returns ``ErrorCode -1`` ("您访问了错误的地址或没有按规定访问").
+   No ``userId`` / ``passportId`` / ``deviceid`` / ``version`` / ``product`` /
+   ``plat`` fields are required.
+3. The ``TYT_Token`` cookie is the only credential needed.  ``Origin``,
+   ``Referer``, ``User-Agent`` and all ``sec-ch-ua*`` / ``Sec-Fetch-*`` headers
+   are unnecessary and are deliberately not sent.
+4. HTTP status is **200 even for failures**.  Success must be read from the
+   JSON body's ``Success`` field.
+5. The response envelope uses PascalCase and prod may add extra fields such as
+   ``TotalCount``.  Payloads are passed through untouched.
+
+Known ``ErrorCode`` values:
+
+    -100  登录超时，请重新登录   -> AUTH_EXPIRED (exit 3)
+      -1  错误的地址/访问方式    -> BAD_REQUEST  (route, method or missing body)
+
+
+公众号 (WeChat Official Account) module — ``WechatPublic/*``
+-----------------------------------------------------------
+
+Probed live on ``test`` 2026-11-06. Several findings contradict the internal
+frontend hand-off document (xuewei, 2026-11-04; deliberately not committed to
+this repo), so trust this section over that file:
+
+1. **Different root.** Routes live under ``/middleApi/WechatPublic/``, not under
+   ``BASE_URLS``. ``{test_base}/WechatPublic/getPostPage`` answers ``-1``; the
+   ``/middleApi`` form works. Hence ``MIDDLE_BASE_URLS`` in ``config.py``.
+   Path case matters: lowercase ``wechatPublic`` gives HTTP **404**.
+2. **The cookie alone is the credential — and ``authkey`` breaks it.** The doc
+   recommends sending ``authkey`` *and* ``Cookie: TYT_Token``. Measured: cookie
+   alone succeeds; ``authkey`` alone gives ``-100 未登录或鉴权失败``; and
+   **sending both also gives ``-100``**. So this client must NOT add an
+   ``authkey`` header. Cookie-only matches the core API, so no new auth path.
+3. **``getPostDetail`` accepts ``articleId``**, which the doc does not mention.
+   ``articleId`` and ``articleKey`` hold the *same* 64-hex value, yet only the
+   name ``articleId`` works for detail; ``{"articleKey": …}`` returns
+   ``-1 文章 identity 参数不完整或超长``. Bad value → ``-1 文章不存在或已失效``;
+   empty/over-64 → ``-1 articleId 不能为空或超过64字符``. The documented
+   ``identity`` triple still works and is kept as a fallback.
+4. ``identity`` must be byte-exact: appending a single space to ``title`` yields
+   ``-1 文章不存在或已失效``.
+5. **``keyword`` search works again.** The doc's §10 blocker (non-empty keyword
+   → ``-1 网络通信异常``) no longer reproduces: ``央行``→4 hits, ``Choice``→1,
+   whitespace-only→same as no keyword. ``--keyword`` is deliberately *not*
+   exposed yet, per product decision; adding it later is a new flag, not a break.
+6. Unlike the core API, **no body at all succeeds** here (defaults applied).
+   We still always send one, for consistency.
+7. Validation messages, verbatim: ``pageNo 必须大于0，pageSize 必须在1到100之间``
+   and ``view 只能为 ALL、SUBSCRIBED 或 FAVORITE``. ``pageNo``/``pageSize`` may
+   be explicit ``null`` (defaults applied), but ``pageNo=0`` is rejected.
+8. Responses carry fields the doc does not list — ``articleId``, ``cleanBody``,
+   ``summary``, ``viewpoints``, and in detail ``paragraphsJson``, ``topicsJson``,
+   ``keywordsJson``, ``parseRunId``. The doc's "不做 AI 总结" is stale. Payloads
+   are passed through untouched, so these simply appear.
+9. **``prod`` has no such module**: every ``/middleApi/`` path 404s there while
+   ``Login/GetLoginInfoV2`` returns ``-100``, proving prod is reachable. The 404
+   is reported as-is with a hint rather than special-cased, so a future prod
+   deploy needs no code change.
+9. **``prod`` has no such module**: every ``/middleApi/`` path 404s there while
+   ``Login/GetLoginInfoV2`` returns ``-100``, proving prod is reachable. The 404
+   is reported as-is with a hint rather than special-cased, so a future prod
+   deploy needs no code change.
+
+
+``sentimentIndex`` module — probed live on ``test`` 2026-11-06
+--------------------------------------------------------------
+
+The Swagger document at ``{middle_base}/v2/api-docs`` (basePath ``/middleApi``,
+413 paths) is the spec of record for this module, and it is wrong in two places:
+
+1. **``getDailyReportDates`` takes NO body.** Swagger says ``consumes:
+   application/json``, and the core ``Login`` endpoint *requires* a body, but
+   here it is the opposite: sending ``{}`` yields ``-101 服务器繁忙，请稍后再试！``
+   while an absent body succeeds. Three endpoints, three body conventions --
+   do not assume one from another.
+2. **``getDailyReportImage`` returns an image, not the JSON envelope.** Swagger
+   declares ``ResponseBodyDecorator«boolean»``; the real response is
+   ``image/png`` at ~4.3 MiB. So this client has a binary transport path
+   (:class:`BinaryResponse`) alongside the JSON one.
+
+Also verified:
+
+* ``reportDate`` validation is a trap. Empty, wrong-format and past-without-a-
+  report dates ALL return ``-101 服务器繁忙`` (a useless message); only a
+  *future* date returns the honest ``-1 指定日期未找到日报``. The CLI therefore
+  validates the format client-side and reports a usage error instead of
+  forwarding a date the server would answer with "server busy".
+* Auth is the same cookie-only scheme; ``authkey`` fails as elsewhere.
+* ``GET`` gives HTTP 405, an unknown method name gives HTTP 404.
+
+RoadShowCenter (路演中心) -- verified live on ``test`` 2026-11-07
+---------------------------------------------------------------
+
+Same root as the two modules above (``MIDDLE_BASE_URLS`` + ``/RoadShowCenter/``).
+Swagger declares 18 endpoints under the 路演中心 tag; the CLI exposes six.
+The handoff document (路演预约与提醒_前端接口对接文档_20261107) was cross-checked
+against the live service and, unlike the 公众号 one, its parameter names and
+Chinese error strings were all accurate. What probing still changed:
+
+1. **A JSON body is required, and omitting it fails differently here.**
+   ``{}`` succeeds; sending *no* body returns **HTTP 400** -- not the core API's
+   ``ErrorCode -1``, and not sentimentIndex's ``-101``. That is a fourth failure
+   signal in this codebase, so ``post_middle_json(send_body=True)`` (the default)
+   is what every roadshow call uses. Do not infer one module's body convention
+   from another's.
+2. **``companyId`` / ``userNo`` are not needed.** Swagger lists both on every
+   request DTO and the document says the server derives the user from the cookie.
+   Verified: ``{"appId": ...}`` alone succeeds. Do not add them "for safety" --
+   the same trap existed for the core API and for 公众号.
+3. **``prod`` HAS this module.** A prod call answers ``-100 登录超时`` rather than
+   404, and per §1 of this docstring that is proof the route exists. This is the
+   opposite of 公众号 and sentimentIndex (both 404 on prod), which matters because
+   ``bookRoadShow`` / ``cancelRoadShowBooking`` are **writes**: on prod they would
+   really create and cancel bookings. That is why the CLI defaults to a read-only
+   pre-flight and requires an explicit ``--yes`` to write.
+4. **Writes return a bare boolean.** ``Data: true`` on success, verified for both
+   book and cancel. There is no object to unwrap, so the commands report the
+   boolean plus a read-back of ``getRoadShowBookingStatus``.
+5. **Both writes are idempotent, verified end to end.** Booking twice succeeds
+   both times and ``bookTime`` does not change (``16:45:06`` on both reads);
+   cancelling twice succeeds both times. The document claimed this; the probe
+   confirmed it, including that a repeat cancel of an already-cancelled booking
+   is a success rather than an error.
+6. **Field presence varies between rows of one response.** Rows filtered by
+   ``theme="1"`` came back without ``duration`` / ``meetingDuration`` /
+   ``meetingPwd`` / ``meetingUrl`` / ``summary``, while unfiltered rows had them.
+   So the trimmed-field set must be derived from the response (see
+   ``commands/shared.observed_fields``), never hardcoded.
+7. **``getPublicRoadShowSummary`` returns 17 fields, Swagger declares 22.**
+   Absent means omitted, not null -- confirmed again by ``bookTime`` disappearing
+   from the status payload after a cancel. Both ``summary`` (brief) and
+   ``detail`` (full text) plus ten topic fields arrive in ONE response, so
+   "brief vs detailed" is field selection, not two endpoints.
+   ``getRoadShowSummaryDetailById`` takes ``{id, publishPath, type}`` (a summary
+   id, not an appId) and is deliberately not exposed.
+8. **Empty page returns ``pageNum: 0``.** ``infos=[] totalData=0 totalPage=0
+   pageNum=0 pageSize=20``. Feeding that 0 back as the next page number would
+   then fail with ``页码和每页条数必须为正整数``, so paging must keep the caller's
+   own page number.
+9. **``endDate`` is exclusive of that day's meetings.** ``startDate=endDate=
+   2026-11-13`` returned 0 rows while ``2026-11-01..2026-11-13`` returned 2, i.e.
+   the cut is 2026-11-13 00:00:00. ``getMyRoadShowBookings`` uses the *opposite*
+   convention (``meetingEndDate`` includes the whole day) and a different format
+   (``yyyy-MM-dd`` vs the listing's ``yyyy/M/d``). The two must not be conflated;
+   the CLI accepts ISO dates for both and translates per endpoint.
+10. **``theme`` accepts ``"1"``..``"6"``; ``"0"``, ``""`` and absent all mean
+    "everything".** Verified by row counts: theme=1 -> 102 of 467.
+11. **Validation errors are HTTP 200 + ``ErrorCode -1`` with these verbatim
+    strings**: ``预约状态只能为BOOKED已预约或ENDED已结束``,
+    ``开始时间不能晚于结束时间``, ``页码和每页条数必须为正整数``,
+    ``请选择路演后重试`` (missing appId), ``路演ID格式不正确`` (bad appId).
+12. **Do not branch on the message text of a write rejection.** book says
+    ``您预约的[标题]路演已经结束`` with half-width brackets while cancel says
+    ``您预约的「标题」路演已经结束，无法取消预约`` with corner brackets, and the
+    document warns the punctuation differs by code path. Branch on ``code``.
+13. Wrong path casing -> HTTP 404; ``GET`` -> HTTP 405. Same as the other two
+    middle modules.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Any, cast
+
+import httpx
+
+from . import __version__
+from .errors import ApiError, AuthError, NetworkError, TytCliError
+
+ERROR_CODE_BAD_REQUEST = -1
+ERROR_CODE_AUTH_TIMEOUT = -100
+#: ``-101 服务器繁忙，请稍后再试！`` -- on some middleApi endpoints this is a
+#: catch-all for bad input, NOT a real server fault (see sentimentIndex §2).
+ERROR_CODE_SERVER_BUSY = -101
+
+#: Floor for binary downloads. ``sentimentIndex/getDailyReportImage`` makes the
+#: server render a ~4.3 MiB PNG on demand; a cold render exceeded the default
+#: 15 s timeout on 2026-11-06 while warm calls take ~9 s. The configured
+#: timeout is tuned for small JSON queries, so the binary path raises the
+#: floor (a user who configured MORE keeps theirs via max()).
+BINARY_DOWNLOAD_TIMEOUT_FLOOR = 60.0
+
+#: Extra attempts for getDailyReportImage when the server answers -101
+#: because the PNG is not rendered yet (see the method's docstring).
+SENTIMENT_IMAGE_RETRIES = 2
+SENTIMENT_IMAGE_RETRY_DELAY = 2.0
+
+# Derived, never hardcoded. A literal `"tytcli/0.1.0"` lived here and silently
+# went stale on the 0.1.1 bump -- the client kept advertising the old version.
+# test_client.py now pins it to __version__ so it cannot drift again.
+DEFAULT_USER_AGENT = f"tytcli/{__version__}"
+COOKIE_NAME = "TYT_Token"
+
+#: Path prefix of the 公众号 module, relative to ``MIDDLE_BASE_URLS``.
+WECHAT_PREFIX = "WechatPublic"
+
+#: Valid ``view`` values for ``getPostPage`` (server-validated; the server's own
+#: message is ``view 只能为 ALL、SUBSCRIBED 或 FAVORITE``).
+WECHAT_POST_VIEWS: tuple[str, ...] = ("ALL", "SUBSCRIBED", "FAVORITE")
+
+#: Server-enforced paging bounds for ``getPostPage``.
+WECHAT_PAGE_SIZE_MIN = 1
+WECHAT_PAGE_SIZE_MAX = 100
+
+#: ``articleId`` is a 64-hex digest; the server rejects longer values with
+#: ``articleId 不能为空或超过64字符``.
+WECHAT_ARTICLE_ID_MAX = 64
+
+#: Path prefix of the 情绪指数 module, relative to ``MIDDLE_BASE_URLS``.
+SENTIMENT_PREFIX = "sentimentIndex"
+
+#: Path prefix of the 路演中心 module, relative to ``MIDDLE_BASE_URLS``.
+ROADSHOW_PREFIX = "RoadShowCenter"
+
+#: Valid ``bookingViewState`` values for ``getMyRoadShowBookings``. The server's
+#: own rejection message is ``预约状态只能为BOOKED已预约或ENDED已结束``; it does
+#: not accept CANCELLED, Chinese text, or numeric states.
+ROADSHOW_BOOKING_STATES: tuple[str, ...] = ("BOOKED", "ENDED")
+
+#: Industry codes for the listing's ``theme`` filter. ``"0"``, ``""`` and an
+#: absent value all mean "no filter" (verified by row count: 102 of 467 for
+#: theme=1). Accepted as either the code or the Chinese label on the CLI.
+ROADSHOW_THEMES: dict[str, str] = {
+    "1": "权益",
+    "2": "固收+",
+    "3": "纯债",
+    "4": "互认",
+    "5": "策略",
+    "6": "热点",
+}
+
+#: ``reportDate`` format, per the Swagger example and the live service.
+SENTIMENT_DATE_FORMAT = "%Y-%m-%d"
+
+#: Magic bytes accepted for a downloaded report image. Anything else is
+#: refused rather than saved under a misleading extension.
+IMAGE_MAGICS: tuple[tuple[bytes, str, str], ...] = (
+    (b"\x89PNG\r\n\x1a\n", "png", ".png"),
+    (b"\xff\xd8\xff", "jpeg", ".jpg"),
+    (b"GIF8", "gif", ".gif"),
+    (b"RIFF", "webp", ".webp"),
+)
+
+BODY_PREVIEW_LIMIT = 400
+
+
+@dataclass(frozen=True)
+class ApiEnvelope:
+    """A parsed TYT response envelope."""
+
+    http_status: int
+    success: bool
+    error_code: int | None
+    error_message: str | None
+    payload: dict[str, Any]
+    url: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "http_status": self.http_status,
+            "success": self.success,
+            "error_code": self.error_code,
+            "error_message": self.error_message,
+            "payload": self.payload,
+        }
+
+
+@dataclass(frozen=True)
+class BinaryResponse:
+    """A non-envelope response: raw bytes plus enough metadata to trust them.
+
+    ``sentimentIndex/getDailyReportImage`` is the first (and so far only)
+    endpoint that does not speak the JSON envelope, so it needs its own type
+    rather than being shoehorned into :class:`ApiEnvelope`.
+    """
+
+    http_status: int
+    content_type: str
+    content: bytes
+    url: str
+
+
+def build_url(base_url: str, path: str) -> str:
+    """Join a base URL that may carry a path prefix with an endpoint path.
+
+    ``https://tytapi.1234567.com.cn`` + ``Login/GetLoginInfoV2``
+        -> ``https://tytapi.1234567.com.cn/Login/GetLoginInfoV2``
+    ``https://tytapitest.1234567.com.cn/api`` + ``Login/GetLoginInfoV2``
+        -> ``https://tytapitest.1234567.com.cn/api/Login/GetLoginInfoV2``
+    """
+    return f"{base_url.rstrip('/')}/{path.lstrip('/')}"
+
+
+def _pick(payload: dict[str, Any], *names: str) -> Any:
+    """Read the first present key, tolerating case differences."""
+    for name in names:
+        if name in payload:
+            return payload[name]
+    lowered = {str(k).lower(): v for k, v in payload.items()}
+    for name in names:
+        key = name.lower()
+        if key in lowered:
+            return lowered[key]
+    return None
+
+
+class TytClient:
+    """Talks to one TYT environment using one ``TYT_Token``."""
+
+    def __init__(
+        self,
+        base_url: str,
+        token: str,
+        *,
+        middle_base_url: str | None = None,
+        timeout: float = 15.0,
+        user_agent: str = DEFAULT_USER_AGENT,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.middle_base_url = middle_base_url.rstrip("/") if middle_base_url else None
+        self.token = token
+        self.timeout = timeout
+        self.user_agent = user_agent
+        self._transport = transport
+
+    # -- public endpoints ------------------------------------------------
+
+    def whoami(self) -> ApiEnvelope:
+        """``POST /Login/GetLoginInfoV2`` — resolve the current login identity."""
+        return self.post_json("Login/GetLoginInfoV2", {})
+
+    def wechat_articles(
+        self,
+        *,
+        view: str = "ALL",
+        fake_id: str | None = None,
+        page_no: int = 1,
+        page_size: int = 20,
+    ) -> ApiEnvelope:
+        """``POST /middleApi/WechatPublic/getPostPage`` — paginate 公众号 articles.
+
+        ``view`` is one of :data:`WECHAT_POST_VIEWS`. ``fake_id`` narrows to one
+        account; omit it (or pass ``None``) for all accounts. ``keyword`` is
+        intentionally not plumbed through — see module docstring §5.
+        """
+        payload: dict[str, Any] = {"view": view, "pageNo": page_no, "pageSize": page_size}
+        # Omitted rather than sent as null: the server accepts both, but an
+        # absent key cannot be mistaken for an intentional filter.
+        if fake_id is not None:
+            payload["fakeId"] = fake_id
+        return self.post_middle_json(f"{WECHAT_PREFIX}/getPostPage", payload)
+
+    def wechat_article(self, *, article_id: str) -> ApiEnvelope:
+        """``POST /middleApi/WechatPublic/getPostDetail`` — one article's detail.
+
+        ``article_id`` is the 64-hex value the list returns. Probing confirmed
+        the documented ``identity`` triple (``{publishTime, account, title}``)
+        locates the same article, but it is deliberately not plumbed through:
+        the title is a long CJK string that must be reproduced byte-exactly (one
+        trailing space yields ``-1 文章不存在或已失效``), which makes it a poor
+        fit for a CLI argument. ``articleKey`` holds the same value yet is NOT
+        accepted under that name — see module docstring §3.
+        """
+        return self.post_middle_json(
+            f"{WECHAT_PREFIX}/getPostDetail", {"articleId": article_id}
+        )
+
+    def sentiment_daily_report_dates(self) -> ApiEnvelope:
+        """``POST /middleApi/sentimentIndex/getDailyReportDates``.
+
+        ``Data`` is a plain list of ``yyyy-MM-dd`` strings, newest first.
+        Sends NO body on purpose -- ``{}`` is rejected with ``-101``.
+        """
+        return self.post_middle_json(
+            f"{SENTIMENT_PREFIX}/getDailyReportDates", send_body=False
+        )
+
+    def sentiment_daily_report_image(self, report_date: str) -> BinaryResponse:
+        """``POST /middleApi/sentimentIndex/getDailyReportImage``.
+
+        Returns the report as an image (``image/png`` in practice), not the
+        JSON envelope.
+
+        Retries up to :data:`SENTIMENT_IMAGE_RETRIES` extra times on ``-101``:
+        verified 2026-11-06, a *valid* date whose PNG has not been rendered yet
+        also answers ``-101 服务器繁忙``, and the next attempt succeeds. Without
+        the retry the command would fail intermittently on first use of a date.
+        Other error codes are raised immediately -- retrying a genuinely bad
+        date cannot help.
+        """
+        last: ApiError | None = None
+        for attempt in range(SENTIMENT_IMAGE_RETRIES + 1):
+            if attempt:
+                time.sleep(SENTIMENT_IMAGE_RETRY_DELAY)
+            try:
+                return self.post_middle_binary(
+                    f"{SENTIMENT_PREFIX}/getDailyReportImage",
+                    {"reportDate": report_date},
+                )
+            except ApiError as exc:
+                if exc.details.get("error_code") != ERROR_CODE_SERVER_BUSY:
+                    raise
+                last = exc
+        assert last is not None
+        last.details["retries_exhausted"] = SENTIMENT_IMAGE_RETRIES
+        raise last
+
+    def roadshow_search(
+        self,
+        *,
+        page_num: int = 1,
+        page_size: int = 20,
+        title: str | None = None,
+        institution: str | None = None,
+        speaker: str | None = None,
+        theme: str | None = None,
+        start_date: str | None = None,
+        end_date: str | None = None,
+    ) -> ApiEnvelope:
+        """``POST /middleApi/RoadShowCenter/getRoadShowInfo`` — search roadshows.
+
+        ``speaker`` maps to the server's ``roadSter`` (its spelling, kept as-is).
+        ``start_date`` / ``end_date`` are the listing's own ``yyyy/M/d`` format —
+        callers pass ISO dates and the command layer translates, because this
+        endpoint's ``endDate`` excludes that day's meetings while
+        ``getMyRoadShowBookings``' includes it.
+
+        Optional filters are omitted rather than sent as ``null`` or ``""``: an
+        absent key cannot be mistaken for an intentional filter.
+        """
+        payload: dict[str, Any] = {"pageNum": page_num, "pageSize": page_size}
+        for key, value in (
+            ("title", title),
+            ("institution", institution),
+            ("roadSter", speaker),
+            ("theme", theme),
+            ("startDate", start_date),
+            ("endDate", end_date),
+        ):
+            if value is not None:
+                payload[key] = value
+        return self.post_middle_json(f"{ROADSHOW_PREFIX}/getRoadShowInfo", payload)
+
+    def roadshow_my_bookings(
+        self,
+        *,
+        page_num: int = 1,
+        page_size: int = 20,
+        booking_view_state: str | None = None,
+        meeting_start_date: str | None = None,
+        meeting_end_date: str | None = None,
+        book_start_time: str | None = None,
+        book_end_time: str | None = None,
+    ) -> ApiEnvelope:
+        """``POST /middleApi/RoadShowCenter/getMyRoadShowBookings``.
+
+        Returns the caller's *non-cancelled* bookings, newest booking first.
+        ``meeting_start_date`` / ``meeting_end_date`` are ``yyyy-MM-dd`` and the
+        end date **includes the whole day** — the opposite of the listing's
+        ``endDate``. ``book_start_time`` / ``book_end_time`` are
+        ``yyyy-MM-dd HH:mm:ss`` and the upper bound is inclusive.
+        """
+        payload: dict[str, Any] = {"pageNum": page_num, "pageSize": page_size}
+        for key, value in (
+            ("bookingViewState", booking_view_state),
+            ("meetingStartDate", meeting_start_date),
+            ("meetingEndDate", meeting_end_date),
+            ("bookStartTime", book_start_time),
+            ("bookEndTime", book_end_time),
+        ):
+            if value is not None:
+                payload[key] = value
+        return self.post_middle_json(f"{ROADSHOW_PREFIX}/getMyRoadShowBookings", payload)
+
+    def roadshow_booking_status(self, *, app_id: str) -> ApiEnvelope:
+        """``POST /middleApi/RoadShowCenter/getRoadShowBookingStatus``.
+
+        ``Data`` carries ``isBooked`` / ``canBook`` / ``canCancel`` / ``reason``
+        and, when booked, ``bookTime``. A meeting that exists but cannot be
+        acted on answers ``Success=true`` with the reason in ``Data.reason``;
+        a missing, delisted or malformed id answers ``Success=false``.
+
+        There is **no batch form** of this endpoint, so a search result cannot
+        show booking state — it has to be asked for one meeting at a time.
+        """
+        return self.post_middle_json(
+            f"{ROADSHOW_PREFIX}/getRoadShowBookingStatus", {"appId": app_id}
+        )
+
+    def roadshow_summary(self, *, app_id: str) -> ApiEnvelope:
+        """``POST /middleApi/RoadShowCenter/getPublicRoadShowSummary``.
+
+        One response holds both the brief (``summary``) and the full text
+        (``detail``) plus ten topic fields, so "brief vs detailed" is field
+        selection rather than two endpoints.
+
+        ``Data`` may be **absent** (not null) when there is no public summary.
+        The endpoint only ever returns audit-approved non-draft records, so
+        "none yet", "pending review", "draft" and "deleted" are indistinguishable
+        — there is no progress status to report, and the command layer says so
+        explicitly instead of letting an empty ``detail`` read as "empty summary".
+        """
+        return self.post_middle_json(
+            f"{ROADSHOW_PREFIX}/getPublicRoadShowSummary", {"appId": app_id}
+        )
+
+    def roadshow_book(self, *, app_id: str) -> ApiEnvelope:
+        """``POST /middleApi/RoadShowCenter/bookRoadShow`` — **write**.
+
+        ``Data`` is a bare ``true`` on success. Idempotent: booking an already
+        booked meeting succeeds again without changing ``bookTime`` (verified).
+        Rejections are HTTP 200 + ``ErrorCode -1`` with a Chinese message whose
+        bracket style differs from cancel's — branch on the code, never the text.
+        """
+        return self.post_middle_json(
+            f"{ROADSHOW_PREFIX}/bookRoadShow", {"appId": app_id}
+        )
+
+    def roadshow_cancel_booking(self, *, app_id: str) -> ApiEnvelope:
+        """``POST /middleApi/RoadShowCenter/cancelRoadShowBooking`` — **write**.
+
+        ``Data`` is a bare ``true`` on success. Idempotent: cancelling twice, or
+        cancelling something never booked, both succeed (verified). Only allowed
+        while the meeting is a visible preview and more than 15 minutes away.
+        """
+        return self.post_middle_json(
+            f"{ROADSHOW_PREFIX}/cancelRoadShowBooking", {"appId": app_id}
+        )
+
+    # -- transport -------------------------------------------------------
+
+    def post_json(self, path: str, payload: dict[str, Any] | None = None) -> ApiEnvelope:
+        """POST to the core API root (``BASE_URLS``)."""
+        return self._post(build_url(self.base_url, path), payload)
+
+    def post_middle_json(
+        self,
+        path: str,
+        payload: dict[str, Any] | None = None,
+        *,
+        send_body: bool = True,
+    ) -> ApiEnvelope:
+        """POST to the ``/middleApi`` root (``MIDDLE_BASE_URLS``).
+
+        Kept separate from :meth:`post_json` because the two roots are siblings
+        on the same host, not prefixes of each other -- ``build_url`` cannot
+        reach ``/middleApi`` from a base that already ends in ``/api``.
+
+        ``send_body=False`` omits the body entirely. Needed because the module's
+        body conventions disagree: ``Login`` requires one, ``WechatPublic``
+        tolerates either, and ``sentimentIndex/getDailyReportDates`` *rejects*
+        ``{}`` with ``-101`` (client docstring, sentimentIndex §1).
+        """
+        if self.middle_base_url is None:
+            raise ApiError(
+                "该命令需要 middleApi 根地址，但客户端未配置。",
+                code="CLIENT_MIDDLE_ROOT_MISSING",
+                details={"path": path},
+            )
+        return self._post(build_url(self.middle_base_url, path), payload, send_body=send_body)
+
+    def post_middle_binary(self, path: str, payload: dict[str, Any]) -> BinaryResponse:
+        """POST to ``/middleApi`` expecting a binary (non-envelope) response.
+
+        ``sentimentIndex/getDailyReportImage`` answers ``image/png`` despite
+        Swagger claiming a boolean envelope. If the server does answer JSON,
+        that is an error envelope (``-100`` / ``-1`` / ``-101``), so it is parsed
+        and raised through the normal path instead of being saved as an image.
+        """
+        if self.middle_base_url is None:
+            raise ApiError(
+                "该命令需要 middleApi 根地址，但客户端未配置。",
+                code="CLIENT_MIDDLE_ROOT_MISSING",
+                details={"path": path},
+            )
+        url = build_url(self.middle_base_url, path)
+        response = self._request(
+            url, payload, timeout=max(self.timeout, BINARY_DOWNLOAD_TIMEOUT_FLOOR)
+        )
+
+        content_type = response.headers.get("content-type", "")
+        if content_type.startswith("application/json"):
+            envelope = self._parse(response, url)
+            error = error_for_envelope(envelope, base_url=self.middle_base_url)
+            if error is not None:
+                raise error
+            raise ApiError(
+                "该接口应返回图片，服务端却返回了成功的 JSON 信封。",
+                code="UNEXPECTED_SHAPE",
+                details={
+                    "url": url,
+                    "http_status": envelope.http_status,
+                    "content_type": content_type,
+                    "payload_keys": sorted(envelope.payload),
+                },
+            )
+        if response.status_code != 200:
+            raise ApiError(
+                f"HTTP {response.status_code}：{url}",
+                code="HTTP_ERROR",
+                details={
+                    "url": url,
+                    "http_status": response.status_code,
+                    "content_type": content_type,
+                    "body_preview": _preview(response.text),
+                },
+            )
+        return BinaryResponse(
+            http_status=response.status_code,
+            content_type=content_type,
+            content=response.content,
+            url=url,
+        )
+
+    def _post(
+        self, url: str, payload: dict[str, Any] | None, *, send_body: bool = True
+    ) -> ApiEnvelope:
+        return self._parse(self._request(url, payload, send_body=send_body), url)
+
+    def _request(
+        self,
+        url: str,
+        payload: dict[str, Any] | None,
+        *,
+        send_body: bool = True,
+        timeout: float | None = None,
+    ) -> httpx.Response:
+        headers = {
+            "Content-Type": "application/json;charset=UTF-8",
+            "Accept": "application/json, text/plain, */*",
+            "Cookie": f"{COOKIE_NAME}={self.token}",
+            "User-Agent": self.user_agent,
+            # No `authkey` header. The 公众号 hand-off doc recommends one, but
+            # probing showed that adding it turns a working cookie-only request
+            # into `-100 未登录或鉴权失败` (client.py docstring §2).
+        }
+        try:
+            with httpx.Client(
+                timeout=timeout if timeout is not None else self.timeout,
+                follow_redirects=False,
+                transport=self._transport,
+            ) as client:
+                if send_body:
+                    # ``json=`` is used even for an empty dict so that a body is
+                    # always sent; an absent body makes the core API answer
+                    # ErrorCode -1. Some middleApi endpoints are the opposite
+                    # (see post_middle_json), hence the flag.
+                    response = client.post(url, json=dict(payload or {}), headers=headers)
+                else:
+                    response = client.post(url, headers=headers)
+        except httpx.TimeoutException as exc:
+            effective = timeout if timeout is not None else self.timeout
+            raise NetworkError(
+                f"请求超时（{effective}s）：{url}",
+                code="NETWORK_TIMEOUT",
+                details={"url": url, "timeout_seconds": effective},
+            ) from exc
+        except httpx.HTTPError as exc:
+            raise NetworkError(
+                f"网络错误：{type(exc).__name__}: {exc}",
+                code="NETWORK_ERROR",
+                details={"url": url, "error_type": type(exc).__name__},
+            ) from exc
+
+        return response
+
+    def _parse(self, response: httpx.Response, url: str) -> ApiEnvelope:
+        content_type = response.headers.get("content-type", "")
+        if response.status_code != 200:
+            details: dict[str, Any] = {
+                "url": url,
+                "http_status": response.status_code,
+                "content_type": content_type,
+                "body_preview": _preview(response.text),
+            }
+            if response.status_code == 404:
+                # Not special-cased into its own error code: 404 already means
+                # "this route does not exist here", which HTTP_ERROR expresses.
+                # The hint exists because the 公众号 module is deployed on test
+                # but not on prod, and a bare 404 reads like a typo otherwise.
+                # Names no environment: this reaches end users, and AGENTS.md
+                # forbids advertising the dev env from user-visible output. The
+                # fact that only `test` deployed the module is recorded in
+                # AGENTS.md and in this module's docstring §9 instead.
+                details["hint"] = (
+                    "该路由在此环境不存在（模块可能未部署），不是路由拼写错误。"
+                    "只有已部署该模块的环境才能使用本命令；"
+                    "用 tytcli env show 查看当前生效的环境。"
+                )
+            raise ApiError(
+                f"HTTP {response.status_code}：{url}",
+                code="HTTP_ERROR",
+                details=details,
+            )
+
+        try:
+            decoded = response.json()
+        except ValueError as exc:
+            raise ApiError(
+                "响应不是合法 JSON（可能是网关拦截页或 HTML 错误页）",
+                code="NON_JSON_RESPONSE",
+                details={
+                    "url": url,
+                    "http_status": response.status_code,
+                    "content_type": content_type,
+                    "body_preview": _preview(response.text),
+                },
+            ) from exc
+
+        if not isinstance(decoded, dict):
+            raise ApiError(
+                "响应 JSON 顶层不是对象",
+                code="UNEXPECTED_SHAPE",
+                details={"url": url, "payload_type": type(decoded).__name__},
+            )
+
+        # `response.json()` is typed `Any`; narrow it once so everything below
+        # is `dict[str, Any]` rather than an untyped `dict[Unknown, Unknown]`.
+        data = cast("dict[str, Any]", decoded)
+
+        success = _pick(data, "Success", "success")
+        error_code = _pick(data, "ErrorCode", "errorCode", "error_code")
+        error_message = _pick(data, "Error", "error", "Message", "message")
+
+        if isinstance(error_code, bool) or not isinstance(error_code, int):
+            try:
+                error_code = int(error_code) if error_code is not None else None
+            except (TypeError, ValueError):
+                error_code = None
+
+        return ApiEnvelope(
+            http_status=response.status_code,
+            success=bool(success),
+            error_code=error_code,
+            error_message=str(error_message) if error_message is not None else None,
+            payload=data,
+            url=url,
+        )
+
+
+def error_for_envelope(
+    envelope: ApiEnvelope, *, env_name: str | None = None, base_url: str | None = None
+) -> TytCliError | None:
+    """Map a non-success envelope onto the error it represents, else ``None``.
+
+    This lives in the protocol layer because two transports need it: the JSON
+    path (wrapped by ``commands.shared.raise_for_envelope``) and the binary
+    path, where an error envelope arrives on an endpoint that normally answers
+    image bytes. ``_parse`` deliberately does NOT raise -- it only parses -- so
+    every caller must consult this mapping; getting that wrong once turned a
+    ``-1`` business error into a bogus UNEXPECTED_SHAPE.
+    """
+    if envelope.success:
+        return None
+
+    common: dict[str, Any] = {
+        "url": envelope.url,
+        "http_status": envelope.http_status,
+        "error_code": envelope.error_code,
+    }
+    if env_name is not None:
+        common["env"] = env_name
+    if base_url is not None:
+        common["base_url"] = base_url
+
+    if envelope.error_code == ERROR_CODE_AUTH_TIMEOUT:
+        return AuthError(
+            envelope.error_message or "登录超时，请重新登录。",
+            code="AUTH_EXPIRED",
+            details={
+                **common,
+                "hint": (
+                    # Names no specific environment: this text is user-visible,
+                    # and AGENTS.md forbids advertising the dev env from it.
+                    # (It used to hardcode "test 的 Token 在 prod 不能用".)
+                    f"TYT_Token 对 '{env_name}' 环境无效或已过期（Token 按环境隔离，"
+                    f"不能跨环境复用）。运行：tytcli auth --env {env_name} --token <TOKEN>"
+                ),
+            },
+        )
+
+    if envelope.error_code == ERROR_CODE_BAD_REQUEST:
+        return ApiError(
+            envelope.error_message or "服务端拒绝了该请求（地址或访问方式不正确）。",
+            code="API_BAD_REQUEST",
+            details={
+                **common,
+                "hint": (
+                    "服务端表示路由不存在或请求不合规定。base_url 已固定在代码中，"
+                    "所以这通常意味着端点路径写错了，而不是环境选错了。"
+                ),
+            },
+        )
+
+    if envelope.error_code == ERROR_CODE_SERVER_BUSY:
+        # Verified 2026-11-06 on sentimentIndex/getDailyReportImage: empty,
+        # wrong-format and past-without-a-report dates all answer -101, while a
+        # future date answers the honest -1. So -101 here usually means "your
+        # input is unusable", and retrying cannot help.
+        common = {
+            **common,
+            "hint": (
+                "-101「服务器繁忙」在部分 middleApi 接口上是兜底码，有两种含义："
+                "① 入参不可用（实测 getDailyReportImage 对空值、格式错误、无日报的"
+                "历史日期都返回它，重试无用，用 sentiment dates 核对日期）；"
+                "② 服务端尚未渲染完成（实测有效日期的首次请求也可能返回它，"
+                "重试可成功；本 CLI 的图片命令已内置有限重试）。"
+            ),
+        }
+
+    return ApiError(
+        envelope.error_message or "API 返回业务失败。",
+        code="API_BUSINESS_ERROR",
+        details=common,
+    )
+
+
+def _preview(text: str) -> str:
+    text = (text or "").strip()
+    if len(text) <= BODY_PREVIEW_LIMIT:
+        return text
+    return text[:BODY_PREVIEW_LIMIT] + "…"