hap-cli 0.9.0__tar.gz → 0.9.1__tar.gz

{hap_cli-0.9.0 → hap_cli-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hap-cli
-Version: 0.9.0
+Version: 0.9.1
 Summary: CLI harness for Mingdao HAP - Enterprise no-code platform
 Author: hap-cli
 License: Apache-2.0
@@ -312,6 +312,7 @@ discover every subcommand.
 
 | Command | Description |
 |---|---|
+| `attachment download FILE_ID --worksheet-id WS --row-id ROW --control-id FIELD [-o PATH]` | Download a worksheet-record attachment with the same record and field permission checks as the web app; existing local files are never overwritten |
 | `attachment share [ADDRESS]` | Create a link to a stored file that you can pass on (`--hours`, default 48; `--file-id` to share by attachment id, `--short` for a landing page instead of the storage address) |
 
 > ADDRESS is the file's link — one that has already stopped working is fine, paste it as-is — or just the path part of it. The file itself does not expire, only the link does, so a dead link can always be revived.

{hap_cli-0.9.0/hap_cli → hap_cli-0.9.1}/README.md

@@ -283,6 +283,7 @@ discover every subcommand.
 
 | Command | Description |
 |---|---|
+| `attachment download FILE_ID --worksheet-id WS --row-id ROW --control-id FIELD [-o PATH]` | Download a worksheet-record attachment with the same record and field permission checks as the web app; existing local files are never overwritten |
 | `attachment share [ADDRESS]` | Create a link to a stored file that you can pass on (`--hours`, default 48; `--file-id` to share by attachment id, `--short` for a landing page instead of the storage address) |
 
 > ADDRESS is the file's link — one that has already stopped working is fine, paste it as-is — or just the path part of it. The file itself does not expire, only the link does, so a dead link can always be revived.

{hap_cli-0.9.0 → hap_cli-0.9.1/hap_cli}/README.md

@@ -283,6 +283,7 @@ discover every subcommand.
 
 | Command | Description |
 |---|---|
+| `attachment download FILE_ID --worksheet-id WS --row-id ROW --control-id FIELD [-o PATH]` | Download a worksheet-record attachment with the same record and field permission checks as the web app; existing local files are never overwritten |
 | `attachment share [ADDRESS]` | Create a link to a stored file that you can pass on (`--hours`, default 48; `--file-id` to share by attachment id, `--short` for a landing page instead of the storage address) |
 
 > ADDRESS is the file's link — one that has already stopped working is fine, paste it as-is — or just the path part of it. The file itself does not expire, only the link does, so a dead link can always be revived.

{hap_cli-0.9.0 → hap_cli-0.9.1}/hap_cli/README_CN.md

@@ -262,6 +262,7 @@ hap --json worksheet record list WORKSHEET_ID
 
 | 命令 | 说明 |
 |---|---|
+| `attachment download FILE_ID --worksheet-id WS --row-id ROW --control-id FIELD [-o PATH]` | 按网页端相同的记录和字段权限校验下载工作表记录附件；不会覆盖已有本地文件 |
 | `attachment share [ADDRESS]` | 为已存储的文件生成一条可以转给别人的链接（`--hours`，默认 48 小时；`--file-id` 按附件 ID 分享，`--short` 返回文件介绍页而非存储地址） |
 
 > ADDRESS 传文件的链接即可——**已经失效的链接照样能传，原样粘贴**——也可以只传路径部分。文件本身不会过期，过期的只是链接，所以失效链接随时可以重新生成。

{hap_cli-0.9.0 → hap_cli-0.9.1}/hap_cli/__init__.py

@@ -3,7 +3,7 @@
 import sys as _sys
 import types as _types
 
-__version__ = "0.9.0"
+__version__ = "0.9.1"
 
 # The command tree used to live in hap_cli/hap_cli.py. A module named
 # after the package it sits in shadows that package: run python with the

{hap_cli-0.9.0 → hap_cli-0.9.1}/hap_cli/commands/attachment_cmd.py

@@ -1,5 +1,7 @@
 """CLI commands for files stored as attachments."""
 
+from pathlib import Path
+
 import click
 
 from hap_cli.context import pass_context
@@ -55,7 +57,43 @@ def attachment_share(ctx, address, hours, file_id, short, display_name, size):
         ctx.handle_error(e)
 
 
+@attachment.command("download")
+@click.argument("file_id")
+@click.option("--worksheet-id", required=True, help="Worksheet containing the record.")
+@click.option("--row-id", required=True, help="Record containing the attachment.")
+@click.option("--control-id", required=True, help="Attachment field containing the file.")
+@click.option(
+    "--output", "-o", "output", type=click.Path(path_type=Path, dir_okay=False),
+    default=None, help="Save as this path. By default, uses the attachment name.",
+)
+@pass_context
+def attachment_download(ctx, file_id, worksheet_id, row_id, control_id, output):
+    """Download a file attached to a worksheet record.
+
+    FILE_ID is listed in an attachment field or a record operation log.
+    Existing local files are never overwritten.
+    """
+    try:
+        session = ctx.get_session()
+        data = attachment_mod.download_attachment(
+            session,
+            file_id,
+            worksheet_id=worksheet_id,
+            row_id=row_id,
+            control_id=control_id,
+            output=output,
+        )
+        ctx.output(data, _download_human)
+    except Exception as e:
+        ctx.handle_error(e)
+
+
 def _human(d):
     click.echo(d["url"])
     if d.get("expiresAt"):
         click.echo(f"Usable until {d['expiresAt']}")
+
+
+def _download_human(d):
+    click.echo(d["path"])
+    click.echo(f"{d['bytes']} bytes")

{hap_cli-0.9.0 → hap_cli-0.9.1}/hap_cli/commands/chat_cmd.py

@@ -246,6 +246,7 @@ def chat_messages(
                 page_index=page,
                 page_size=num,
                 category=category,
+                keyword=keyword,
             )
             if mark_read and category:
                 chat_mod.mark_inbox_read(session, category)

hap_cli-0.9.1/hap_cli/core/attachment.py

@@ -0,0 +1,388 @@
+"""Attachments in the file store: shareable links for stored files.
+
+The address handed out at upload time is a private-bucket signature that
+expires within the hour (``upload.url_expires_at``). The file behind it
+does not expire — the object path *is* the URL path — so a dead link is
+re-signable at any time.
+
+``Attachment/GetShareLocalAttachmentUrl`` is what the web UI's
+"分享附件" action calls: pd-openweb
+src/components/shareAttachment/toMobile.js:121 passes
+``{filePath: file.qiniuPath, hours: 48}``, where ``qiniuPath`` is built
+as ``window.config.FilePath + file.key``
+(src/pages/chat/components/Message/MessageToolbar/index.js:222).
+
+That prefix is not decorative. Verified live on 2026-08-31, the server
+accepts the ``config.FilePath`` form and nothing else — a bare key, a
+``documentHost``-prefixed URL, or the original signed URL with its query
+intact each come back as an empty string with no error state. So this
+module normalizes any address the user has to hand down to a key and
+rebuilds the one prefix that works.
+"""
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+import tempfile
+from typing import Any, Optional
+from urllib.parse import urlencode, urlparse, urlunparse
+
+import requests
+
+from hap_cli.core.session import APIError, Session, SessionError
+from hap_cli.utils.parameter_mapping import parameter_mapping
+
+logger = logging.getLogger("hap_cli.attachment")
+
+# What the web UI uses when it shares an attachment (toMobile.js:123).
+DEFAULT_SHARE_HOURS = 48
+
+
+def _same_server_download_headers(session: Session, url: str) -> dict[str, str]:
+    """Browser-equivalent auth for HAP-hosted downloads, never for a CDN."""
+    def _origin(address: str) -> Optional[tuple[str, str, int]]:
+        parsed = urlparse(address)
+        scheme = parsed.scheme.casefold()
+        if scheme not in {"http", "https"} or not parsed.hostname:
+            return None
+        port = parsed.port or (443 if scheme == "https" else 80)
+        return scheme, parsed.hostname.casefold(), port
+
+    target_origin = _origin(url)
+    matched_address = next(
+        (
+            candidate
+            for candidate in (session.login_url, session.server_url)
+            if candidate and _origin(candidate) == target_origin
+        ),
+        None,
+    )
+    if target_origin is None or matched_address is None:
+        return {}
+    origin_parsed = urlparse(matched_address)
+    origin = f"{origin_parsed.scheme}://{origin_parsed.netloc}"
+    headers = {
+        "Authorization": f"md_pss_id {session.auth_token}",
+        "Origin": origin,
+        "Referer": origin + "/",
+        "X-Requested-With": "XMLHttpRequest",
+    }
+    if session.account_id:
+        headers["AccountId"] = session.account_id
+    return headers
+
+
+def _download_name(detail: dict[str, Any], file_id: str) -> str:
+    """Choose a safe local filename from attachment metadata."""
+    def _without_controls(value: Any) -> str:
+        return "".join(
+            char for char in str(value)
+            if ord(char) >= 32 and not 127 <= ord(char) <= 159
+        )
+
+    fallback = Path(_without_controls(file_id).replace("\\", "/")).name
+    if fallback in {"", ".", ".."}:
+        fallback = "attachment"
+    raw_name = _without_controls(
+        detail.get("originalFilename")
+        or detail.get("originalFileName")
+        or detail.get("fileName")
+        or fallback
+    )
+    name = Path(raw_name.replace("\\", "/")).name
+    if name in {"", ".", ".."}:
+        name = fallback
+    raw_ext = _without_controls(detail.get("fileExt") or detail.get("ext") or "")
+    ext = Path(raw_ext.replace("\\", "/")).name
+    if ext in {"", ".", ".."}:
+        ext = ""
+    if ext and not ext.startswith("."):
+        ext = "." + ext
+    if ext and not name.lower().endswith(ext.lower()):
+        name += ext
+    safe_name = Path(name.replace("\\", "/")).name
+    return safe_name if safe_name not in {"", ".", ".."} else fallback
+
+
+@parameter_mapping("attachment.download.record-context")
+def download_attachment(
+    session: Session,
+    file_id: str,
+    *,
+    worksheet_id: str,
+    row_id: str,
+    control_id: str,
+    output: Optional[Path] = None,
+    output_dir: Optional[Path] = None,
+) -> dict[str, Any]:
+    """Download one worksheet-record attachment to a new local file.
+
+    The web UI first calls ``Attachment/GetAttachmentDetail`` with the full
+    record context, then downloads its signed ``downloadUrl`` (MDPublic
+    ``src/pages/worksheet/controllers/record.js``
+    ``downloadAttachmentById``). Keeping those identifiers in the request
+    preserves the same record/field permission check as the UI.
+    """
+    if not file_id:
+        raise ValueError("file_id is required")
+    if not worksheet_id or not row_id or not control_id:
+        raise ValueError(
+            "worksheet_id, row_id, and control_id are required for a record attachment"
+        )
+
+    # Refuse before any network request when the caller named an existing path.
+    target = Path(output).expanduser() if output is not None else None
+    if target is not None and target.exists():
+        raise FileExistsError(f"Refusing to overwrite existing file: {target}")
+
+    detail = session.api_call(
+        "Attachment",
+        "GetAttachmentDetail",
+        {
+            "fileId": file_id,
+            "worksheetId": worksheet_id,
+            "rowId": row_id,
+            "controlId": control_id,
+        },
+    )
+    if not isinstance(detail, dict) or not detail.get("downloadUrl"):
+        raise APIError(
+            "The attachment has no downloadable address. Check that it still "
+            "exists and that you can download files from this record."
+        )
+
+    if target is None:
+        directory = Path(output_dir or Path.cwd()).expanduser().resolve()
+        target = directory / _download_name(detail, file_id)
+    target = target.resolve()
+    if target.exists():
+        raise FileExistsError(f"Refusing to overwrite existing file: {target}")
+    if not target.parent.is_dir():
+        raise FileNotFoundError(f"Output directory does not exist: {target.parent}")
+
+    url = str(detail["downloadUrl"])
+    parsed_download = urlparse(url)
+    log_query = urlencode({"controlId": control_id, "rowId": row_id})
+    url = urlunparse(parsed_download._replace(
+        query="&".join(part for part in (parsed_download.query, log_query) if part)
+    ))
+    candidates = [url]
+    private_url = str(detail.get("privateDownloadUrl") or "")
+    if private_url and private_url != url:
+        candidates.append(private_url)
+
+    response = None
+    for index, candidate in enumerate(candidates):
+        parsed = urlparse(candidate)
+        safe_url = urlunparse(parsed._replace(query="", fragment=""))
+        logger.info("HAP GET %s stream=true", safe_url)
+        download_headers = (
+            _same_server_download_headers(session, candidate)
+            if index == 0 else {}
+        )
+        request_kwargs: dict[str, Any] = {"stream": True, "timeout": 60}
+        if download_headers:
+            request_kwargs["headers"] = download_headers
+        response = requests.get(candidate, **request_kwargs)
+        logger.info(
+            "HAP GET %s -> %s content-length=%s",
+            safe_url,
+            response.status_code,
+            response.headers.get("Content-Length", ""),
+        )
+        try:
+            response.raise_for_status()
+        except requests.HTTPError:
+            response.close()
+            if response.status_code == 403 and index + 1 < len(candidates):
+                logger.warning(
+                    "HAP download route refused the signed redirect; "
+                    "retrying the private attachment URL",
+                )
+                continue
+            raise
+        break
+
+    if response is None:  # pragma: no cover - candidates always has url
+        raise APIError("The attachment has no downloadable address.")
+
+    written = 0
+    temp_path: Optional[Path] = None
+    try:
+        fd, temp_name = tempfile.mkstemp(
+            dir=target.parent,
+            prefix=f".{target.name}.",
+            suffix=".part",
+        )
+        temp_path = Path(temp_name)
+        with os.fdopen(fd, "wb") as handle:
+            for chunk in response.iter_content(chunk_size=1024 * 1024):
+                if chunk:
+                    handle.write(chunk)
+                    written += len(chunk)
+            handle.flush()
+            os.fsync(handle.fileno())
+
+        # Hard-linking within the same directory publishes the fully-written
+        # file atomically and fails instead of replacing a path that appeared
+        # during the download.
+        os.link(temp_path, target)
+        temp_path.unlink()
+        temp_path = None
+    except BaseException:
+        if temp_path is not None and temp_path.exists():
+            temp_path.unlink()
+        raise
+    finally:
+        response.close()
+
+    return {
+        "fileId": file_id,
+        "name": target.name,
+        "path": str(target),
+        "bytes": written,
+    }
+
+
+def store_key(address: str) -> str:
+    """Reduce any form of a stored file's address to its store key.
+
+    Accepts a full URL on any of the store's hosts (with or without the
+    ``?e=…&token=…`` signature still attached — a dead link pasted out of
+    a chat message is the common case), a leading-slash path, or a bare
+    key.
+    """
+    if not address or not address.strip():
+        raise ValueError("a file address or key is required")
+    address = address.strip()
+    if "://" in address:
+        address = urlparse(address).path
+    else:
+        # A bare key may still carry a query if it came from a copied link.
+        address = address.split("?", 1)[0]
+    return address.lstrip("/")
+
+
+def _file_path_prefix(session: Session) -> str:
+    """The store prefix this endpoint requires in ``filePath``.
+
+    Bootstrap publishes it as ``config.FilePath`` — the same value chat
+    file addresses are built from (``chat.chat_file_host``).
+    """
+    meta = session.get_global_meta()
+    for scope in (meta.get("config"), meta):
+        if isinstance(scope, dict) and scope.get("FilePath"):
+            return scope["FilePath"]
+    raise SessionError(
+        "This server did not publish a file address, so a link cannot be "
+        "created. Check that you are signed in to the right server, then "
+        "try again."
+    )
+
+
+def share_url(
+    session: Session,
+    address: str = "",
+    *,
+    hours: int = DEFAULT_SHARE_HOURS,
+    file_id: str = "",
+    short: bool = False,
+    display_name: str = "",
+    size: Optional[int] = None,
+) -> dict[str, Any]:
+    """Create a fresh, time-limited link to a file already in the store.
+
+    ``address`` is anything that identifies the file: its current or
+    expired link, or its bare key. ``file_id`` is the other way to name
+    one — a knowledge-centre attachment is shared by its id and nothing
+    else, which is the shape the share dialog uses for that kind
+    (MDPublic src/components/shareAttachment/MobileShareDialog.jsx:64;
+    pd-openweb toMobile.js has the same branch).
+
+    With ``short``, the answer is a short link to a landing page instead
+    of the signed store address itself — what the product hands a person
+    (MobileShareDialog.jsx:37-59). ``display_name`` and ``size`` are what
+    the landing page shows; without them it falls back to the file's own
+    key and shows no size.
+
+    Returns ``{url, expiresAt, hours, key}``, plus ``storeUrl`` when the
+    link was shortened.
+    """
+    from hap_cli.core.upload import _iso, url_expires_at
+
+    if hours <= 0:
+        raise ValueError("hours must be a positive number")
+    if not address and not file_id:
+        raise ValueError("a file address, key, or file id is required")
+    key = store_key(address) if address else ""
+    if file_id:
+        args: dict[str, Any] = {"fileID": file_id}
+    else:
+        args = {"filePath": _file_path_prefix(session) + key, "hours": hours}
+    url = session.api_call("Attachment", "GetShareLocalAttachmentUrl", args)
+    if not url or not isinstance(url, str):
+        # An unknown or unreachable file is answered with an empty string
+        # and a success state, so there is nothing to detect but this.
+        logger.warning("GetShareLocalAttachmentUrl returned %r for key=%s",
+                       url, key or file_id)
+        raise APIError(
+            "Could not create a link for that file. Check the address is "
+            "complete and that the file still exists."
+        )
+    out = {
+        "url": url,
+        "expiresAt": _iso(url_expires_at(url)),
+        "hours": hours,
+        "key": key,
+    }
+    if short:
+        out["storeUrl"] = url
+        out["url"] = _short_landing_link(
+            session, url, display_name=display_name or key, size=size)
+    return out
+
+
+# Where the landing page lives, relative to the web host.
+_LANDING_PATH = "/apps/kc/shareLocalAttachment.aspx"
+
+
+def _short_landing_link(session: Session, signed_url: str, *,
+                        display_name: str, size: Optional[int]) -> str:
+    """Wrap a signed store address in the product's own landing page.
+
+    The product never hands out the store address directly: it splits the
+    signature off, rebuilds it as a landing-page URL carrying the file's
+    name, extension, size and the moment the link was made, and shortens
+    that (MDPublic src/components/shareAttachment/MobileShareDialog.jsx:
+    37-59; pd-openweb toMobile.js:120-145 identical). So the recipient
+    gets a page about the file rather than the bucket's own address.
+
+    Measured 2026-09-09: ``Attachment/GetShortUrl`` echoes the URL back
+    unchanged on Mingdao SaaS, so what this reliably buys is the landing
+    page; whether the link is also shortened is up to the environment.
+    """
+    import os
+    import time
+    from urllib.parse import parse_qs, quote, urlencode, urlparse
+
+    parsed = urlparse(signed_url)
+    query = parse_qs(parsed.query)
+    bare = signed_url.split("?", 1)[0]
+    stem, ext = os.path.splitext(display_name or parsed.path.rsplit("/", 1)[-1])
+    params = {
+        "qiniuPath": bare,
+        "qiniutoken": (query.get("token") or [""])[0],
+        "e": (query.get("e") or [""])[0],
+        "name": stem,
+        "ext": ext.lstrip("."),
+        "size": "" if size is None else str(size),
+        "genTime": str(int(time.time() * 1000)),
+    }
+    landing = (session.server_url.rstrip("/") + _LANDING_PATH + "?"
+               + urlencode(params))
+    result = session.api_call("Attachment", "GetShortUrl",
+                              {"url": quote(landing, safe="@*_+-./")})
+    if isinstance(result, dict):
+        return result.get("shortUrl") or signed_url
+    return result if isinstance(result, str) and result else signed_url

{hap_cli-0.9.0 → hap_cli-0.9.1}/hap_cli/core/chat.py

@@ -1,6 +1,7 @@
 """Chat and messaging management for Mingdao HAP."""
 
 import json
+import html
 import logging
 import re
 from typing import Any, Optional
@@ -1821,6 +1822,58 @@ def _simplify_inbox_response(
 _INBOX_SERVER_PAGE1_PAGE_SIZE = 10
 
 
+@parameter_mapping("chat.messages.inbox-query")
+def _inbox_query(
+    *,
+    page_index: int,
+    page_size: int,
+    inbox_favorite: int,
+    type_: str,
+    creator_id: Optional[str],
+    keyword: str,
+) -> dict[str, Any]:
+    """Translate the CLI inbox query to ``GetInboxMessage`` fields."""
+    return {
+        "pageIndex": page_index,
+        "pageSize": page_size,
+        "inboxFavorite": inbox_favorite,
+        "type": type_,
+        "loadType": 2,
+        "creatorId": creator_id,
+        "keywords": keyword,
+        "clearUnread": False,
+    }
+
+
+def _inbox_item_matches(item: dict[str, Any], keyword: str) -> bool:
+    """Case-insensitive inbox search over user-facing text, not ids/URLs."""
+    needle = keyword.casefold().strip()
+    if not needle:
+        return True
+
+    def _texts(value: Any, key: str = ""):
+        normalized_key = key.casefold()
+        if (
+            normalized_key.endswith("id")
+            or normalized_key.endswith("ids")
+            or "url" in normalized_key
+            or normalized_key in {"avatar", "createtime", "readtime"}
+        ):
+            return
+        if isinstance(value, dict):
+            for child_key, child_value in value.items():
+                yield from _texts(child_value, str(child_key))
+        elif isinstance(value, list):
+            for child in value:
+                yield from _texts(child, key)
+        elif isinstance(value, str):
+            # Message.content/rawContent may be server-rendered HTML. Search
+            # visible labels, not hidden hrefs or other tag attributes.
+            yield html.unescape(re.sub(r"<[^>]*>", "", value))
+
+    return any(needle in text.casefold() for text in _texts(item))
+
+
 def get_inbox_messages(
     session: Session,
     type_: str,
@@ -1829,6 +1882,7 @@ def get_inbox_messages(
     inbox_favorite: int = 0,
     creator_id: Optional[str] = None,
     category: Optional[str] = None,
+    keyword: str = "",
 ) -> dict[str, Any]:
     """Fetch inbox messages for system / app / workflow / etc categories.
 
@@ -1844,13 +1898,21 @@ def get_inbox_messages(
     ``_INBOX_SERVER_PAGE1_FIXED`` for why this differs from the raw
     server pagination.
 
-    Two parameters intentionally **not** exposed because the server
-    ignores them:
+    ``keyword`` maps to the API's plural ``keywords`` field. Unlike direct
+    and group chat history, inbox notifications use the main-site API and
+    therefore a different wire name. Current servers return unrelated rows
+    even when that field is present, so the CLI scans raw pages and builds
+    stable result pages by filtering locally over user-facing text.
+
+    One parameter intentionally **not** exposed because the server ignores it:
     - ``loadType`` — pd-openweb always sends 2 (ALL); 1 (UNREAD) is a
       no-op server-side, and the response items carry no per-item
       read/unread flag, so a client-side filter has nothing to key on.
-    - ``clearUnread`` — empirically does not affect the badge regardless
-      of true/false. Use ``mark_inbox_read()`` (socket emit) instead.
+
+    ``clearUnread`` must still be sent explicitly as false. Although an older
+    server build appeared to ignore it, omitting the field now clears the badge
+    in some environments. Actual mark-read behavior remains the separate
+    socket event in ``mark_inbox_read()``.
     """
     if page_index < 1:
         raise ValueError("page_index must be >= 1")
@@ -1860,14 +1922,14 @@ def get_inbox_messages(
     def _call(server_page: int, server_size: int) -> list[dict[str, Any]]:
         raw = session.api_call(
             "Inbox", "GetInboxMessage",
-            {
-                "pageIndex": server_page,
-                "pageSize": server_size,
-                "inboxFavorite": inbox_favorite,
-                "type": type_,
-                "loadType": 2,
-                "creatorId": creator_id,
-            },
+            _inbox_query(
+                page_index=server_page,
+                page_size=server_size,
+                inbox_favorite=inbox_favorite,
+                type_=type_,
+                creator_id=creator_id,
+                keyword=keyword,
+            ),
         )
         if not isinstance(raw, dict):
             return []
@@ -1875,6 +1937,33 @@ def get_inbox_messages(
 
     items: list[dict[str, Any]] = []
 
+    if keyword:
+        # The documented `keywords` field is ignored by current servers.
+        # Walk the raw 10-item segmentation from the beginning so CLI page N
+        # means page N of *matching* rows, rather than a sparse filtered view
+        # of raw page N.
+        match_start = (page_index - 1) * page_size
+        match_end = match_start + page_size
+        matches: list[dict[str, Any]] = []
+        server_page = 1
+        while len(matches) < match_end:
+            page_list = _call(server_page, _INBOX_SERVER_PAGE1_PAGE_SIZE)
+            if not page_list:
+                break
+            simplified_page = _simplify_inbox_response({"inboxList": page_list})
+            matches.extend(
+                item for item in simplified_page["list"]
+                if _inbox_item_matches(item, keyword)
+            )
+            if len(page_list) < _INBOX_SERVER_PAGE1_PAGE_SIZE:
+                break
+            server_page += 1
+        result = _simplify_inbox_response(
+            {"inboxList": []}, category=category, base_url=session.login_url
+        )
+        result["list"] = matches[match_start:match_end]
+        return result
+
     if page_index == 1:
         # Page 1 of the user's window: collect at 10-item boundaries (the
         # only segmentation upstream honors when pageIndex starts at 1)
@@ -1895,9 +1984,10 @@ def get_inbox_messages(
         items = _call(page_index, page_size)
 
     synthetic_raw = {"inboxList": items}
-    return _simplify_inbox_response(
+    result = _simplify_inbox_response(
         synthetic_raw, category=category, base_url=session.login_url
     )
+    return result
 
 
 def get_card_details(