substack-api-mcp 1.0.2__py3-none-any.whl

substack_api_mcp/runner.py

@@ -0,0 +1,106 @@
+"""All tools of the app in one registry, and the one way to call them: validate, run, map errors.
+
+The REST API, the MCP server, the CLI and `substack_api_mcp.call()` all go through `Runner.run`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import importlib
+import pkgutil
+from typing import Any
+
+import jsonschema
+
+from substack_api_mcp import app
+from substack_api_mcp import session as sessions
+from substack_api_mcp.core.context import ToolContext
+from substack_api_mcp.core.errors import ErrorCode, ToolError
+from substack_api_mcp.core.tools import ToolSpec
+from substack_api_mcp.substack import tools as tools_package
+
+_TOOLS: dict[str, ToolSpec] | None = None
+
+
+def all_tools() -> dict[str, ToolSpec]:
+    """Every tool in the app's tools/ package, by name, in file order."""
+    global _TOOLS
+    if _TOOLS is None:
+        found: dict[str, ToolSpec] = {}
+        for module_info in sorted(pkgutil.iter_modules(tools_package.__path__), key=lambda m: m.name):
+            module = importlib.import_module(f"{tools_package.__name__}.{module_info.name}")
+            for value in vars(module).values():
+                if isinstance(value, ToolSpec) and value.route:
+                    found[value.name] = value
+        _TOOLS = found
+    return _TOOLS
+
+
+def tools(read_only: bool = False) -> list[ToolSpec]:
+    return [spec for spec in all_tools().values() if not read_only or spec.access == "read"]
+
+
+def description(spec: ToolSpec) -> str:
+    """What an agent reads: the one-liner, then the details."""
+    return f"{spec.description}\n\n{spec.details}" if spec.details else spec.description
+
+
+class Runner:
+    """One session for the life of the process; reconnects to Chrome once when the app signs it out."""
+
+    def __init__(self, read_only: bool = False) -> None:
+        self.read_only = read_only
+        self._ctx: ToolContext | None = None
+        self._lock = asyncio.Lock()
+
+    def _context(self) -> ToolContext:
+        if self._ctx is None:
+            session = sessions.load()
+            if not session.signed_in:
+                raise ToolError(
+                    f"No {app.NAME} session yet. Sign in to {app.NAME} in Chrome, then run: {app.CLI} connect",
+                    ErrorCode.AUTH_REQUIRED,
+                )
+            self._ctx = ToolContext(session=session)
+        return self._ctx
+
+    async def run(self, name: str, args: dict[str, Any] | None = None) -> Any:
+        spec = all_tools().get(name)
+        if spec is None:
+            raise ToolError(f"No tool '{name}'. List them with: {app.CLI} tools", ErrorCode.UNKNOWN_TOOL)
+        if self.read_only and spec.access != "read":
+            raise ToolError(f"{name} changes {app.NAME} and this server runs read-only.", ErrorCode.SCOPE_DENIED)
+        args = {k: v for k, v in (args or {}).items() if v is not None}
+        try:
+            jsonschema.validate(args, spec.input_schema)
+        except jsonschema.ValidationError as exc:
+            where = ".".join(str(p) for p in exc.absolute_path)
+            raise ToolError(f"{where + ': ' if where else ''}{exc.message}", ErrorCode.INVALID_INPUT) from None
+        ctx = self._context()
+        try:
+            return await asyncio.wait_for(spec.handler(ctx, args), timeout=spec.timeout_s or 120)
+        except TimeoutError:
+            raise ToolError(f"{app.NAME} took too long to answer.", ErrorCode.TIMEOUT) from None
+        except ToolError as exc:
+            if exc.code is not ErrorCode.AUTH_EXPIRED or not await self._reconnect():
+                raise
+            # The app signed the old cookies out: read them again from Chrome and try once more.
+            return await spec.handler(self._context(), args)
+
+    async def _reconnect(self) -> bool:
+        async with self._lock:
+            old = self._context()
+            try:
+                fresh = await asyncio.to_thread(sessions.refresh, old.session)
+            except ToolError:
+                return False
+            if fresh is None or fresh.cookies == old.session.cookies:
+                return False
+            await old.close()
+            self._ctx = ToolContext(session=fresh)
+            return True
+
+    async def close(self) -> None:
+        if self._ctx is not None:
+            await self._ctx.close()
+            self._ctx = None

substack_api_mcp/scripting.py

@@ -0,0 +1,73 @@
+"""Helpers for scripts: call a tool, follow pages, save CSV or JSON. The scripts in examples/ use them.
+
+from substack_api_mcp.scripting import call, paginate
+
+for member in paginate("list_members", {"group": "yourgroup"}, "members"):
+    print(member["name"], member["level"])
+"""
+
+from __future__ import annotations
+
+import csv
+import json
+import sys
+from collections.abc import Callable, Iterator
+from pathlib import Path
+from typing import Any
+
+from substack_api_mcp import call as _call
+from substack_api_mcp.core.errors import ToolError
+
+
+def call(tool: str, params: dict[str, Any] | None = None) -> Any:
+    """Run one tool; arguments set to None are left out."""
+    return _call(tool, {k: v for k, v in (params or {}).items() if v is not None})
+
+
+def paginate(tool: str, params: dict[str, Any], key: str, max_items: int | None = None) -> Iterator[dict[str, Any]]:
+    """Yield every item of a list tool, following next_cursor."""
+    params = dict(params)
+    seen = 0
+    while True:
+        page = call(tool, params)
+        for item in page.get(key, []):
+            yield item
+            seen += 1
+            if max_items and seen >= max_items:
+                return
+        cursor = page.get("next_cursor")
+        if not cursor:
+            return
+        params["cursor"] = cursor
+
+
+def write_rows(rows: list[dict[str, Any]], out: str | None) -> None:
+    """Print JSON to stdout, or save .csv / .json when a path is given."""
+    if not out:
+        print(json.dumps(rows, indent=2, ensure_ascii=False))
+        return
+    path = Path(out)
+    if path.suffix.lower() == ".csv":
+        fields: list[str] = []
+        for row in rows:
+            fields += [k for k in row if k not in fields]
+        with path.open("w", newline="", encoding="utf-8") as fh:
+            writer = csv.DictWriter(fh, fieldnames=fields)
+            writer.writeheader()
+            for row in rows:
+                writer.writerow(
+                    {k: json.dumps(v, ensure_ascii=False) if isinstance(v, (dict, list)) else v for k, v in row.items()}
+                )
+    else:
+        path.write_text(json.dumps(rows, indent=2, ensure_ascii=False), encoding="utf-8")
+    print(f"Saved {len(rows)} rows to {path}", file=sys.stderr)
+
+
+def run(main: Callable[[], None]) -> None:
+    """Run a script's main() and turn tool errors into a readable message."""
+    try:
+        main()
+    except ToolError as err:
+        sys.exit(f"{err.code}: {err}")
+    except KeyboardInterrupt:
+        sys.exit(130)

substack_api_mcp/session.py

@@ -0,0 +1,197 @@
+"""Your session of the app: its cookies from your own Chrome, saved on this machine.
+
+`<cli> connect` reads them from Chrome over the Chrome DevTools Protocol, in one of two ways:
+
+- Chrome 144+ with remote debugging switched on at chrome://inspect/#remote-debugging. Chrome writes
+  the port to `DevToolsActivePort` in its profile folder and asks you to allow each connection.
+- Any Chrome started with `--remote-debugging-port=9222 --user-data-dir=<folder>`: pass `--cdp http://127.0.0.1:9222`.
+
+The session file holds cookies only, never your password, and is readable by your user alone (0600).
+Names, domains and the session cookie come from `app.py`.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import platform
+import re
+import stat
+import urllib.request
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlsplit
+
+from substack_api_mcp import app
+from substack_api_mcp.core.errors import ErrorCode, ToolError
+
+SESSION_COOKIE = app.SESSION_COOKIES[0]
+
+
+def home() -> Path:
+    """Where the session is kept: $<ENV>_MCP_HOME, or ~/.config/<slug>-api-mcp."""
+    return Path(os.environ.get(f"{app.ENV}_MCP_HOME") or Path.home() / ".config" / f"{app.SLUG}-api-mcp")
+
+
+def session_path() -> Path:
+    return home() / "session.json"
+
+
+@dataclass
+class Session:
+    cookies: list[dict[str, Any]] = field(default_factory=list)
+    user_agent: str | None = None
+    chrome_major: int | None = None
+    locale: str | None = None
+    # Where the cookies came from, so a signed-out session can be read again: "auto", a CDP URL, or "token".
+    source: str | None = None
+    proxy: str | None = None
+
+    @property
+    def signed_in(self) -> bool:
+        return all(any(c["name"] == name and c.get("value") for c in self.cookies) for name in app.SESSION_COOKIES)
+
+
+def load() -> Session:
+    """The saved session, with <ENV>_AUTH_TOKEN and <ENV>_PROXY from the environment on top."""
+    session = Session()
+    path = session_path()
+    if path.exists():
+        data = json.loads(path.read_text(encoding="utf-8"))
+        session = Session(**{k: v for k, v in data.items() if k in Session.__dataclass_fields__})
+    if token := os.environ.get(f"{app.ENV}_AUTH_TOKEN", "").strip():
+        session.cookies = [c for c in session.cookies if c["name"] != SESSION_COOKIE]
+        session.cookies.append({"name": SESSION_COOKIE, "value": token, "domain": app.COOKIE_DOMAIN, "path": "/"})
+        session.source = session.source or "token"
+    if proxy := os.environ.get(f"{app.ENV}_PROXY", "").strip():
+        session.proxy = proxy
+    return session
+
+
+def save(session: Session) -> Path:
+    path = session_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, stat.S_IRUSR | stat.S_IWUSR)
+    with os.fdopen(fd, "w", encoding="utf-8") as fh:
+        json.dump(asdict(session), fh, indent=2)
+    os.chmod(path, stat.S_IRUSR | stat.S_IWUSR)
+    return path
+
+
+def from_token(token: str) -> Session:
+    """A session from the auth_token value copied by hand (Chrome DevTools > Application > Cookies)."""
+    token = token.strip()
+    if not token:
+        raise ToolError("The token is empty.", ErrorCode.INVALID_INPUT)
+    cookie = {"name": SESSION_COOKIE, "value": token, "domain": app.COOKIE_DOMAIN, "path": "/"}
+    return Session(cookies=[cookie], source="token")
+
+
+def chrome_profile_dirs() -> list[Path]:
+    """Default Chrome profile folders of this OS, stable channel first."""
+    system = platform.system()
+    if system == "Darwin":
+        base = Path.home() / "Library" / "Application Support" / "Google"
+        return [base / "Chrome", base / "Chrome Beta", base / "Chrome Canary"]
+    if system == "Windows":
+        base = Path(os.environ.get("LOCALAPPDATA", "")) / "Google"
+        return [base / "Chrome" / "User Data", base / "Chrome Beta" / "User Data", base / "Chrome SxS" / "User Data"]
+    base = Path.home() / ".config"
+    return [base / "google-chrome", base / "google-chrome-beta", base / "chromium"]
+
+
+def auto_endpoint(profile_dir: str | None = None) -> str:
+    """The browser WebSocket URL from DevToolsActivePort, written while remote debugging is on."""
+    dirs = [Path(profile_dir).expanduser()] if profile_dir else chrome_profile_dirs()
+    for folder in dirs:
+        port_file = folder / "DevToolsActivePort"
+        if port_file.exists():
+            lines = port_file.read_text(encoding="utf-8").split()
+            if len(lines) >= 2 and lines[0].isdigit():
+                return f"ws://127.0.0.1:{lines[0]}{lines[1]}"
+    raise ToolError(
+        "Chrome remote debugging is off. Open chrome://inspect/#remote-debugging in Chrome, switch it on, "
+        "and run this again. Or start Chrome with --remote-debugging-port=9222 and pass --cdp http://127.0.0.1:9222.",
+        ErrorCode.AUTH_REQUIRED,
+    )
+
+
+def _endpoint(cdp: str) -> str:
+    """A ws:// URL as given, or the browser WebSocket URL behind an http:// DevTools address."""
+    if cdp.startswith(("ws://", "wss://")):
+        return cdp
+    with urllib.request.urlopen(cdp.rstrip("/") + "/json/version", timeout=10) as resp:
+        return json.loads(resp.read())["webSocketDebuggerUrl"]
+
+
+class _Cdp:
+    """A tiny synchronous CDP client: one WebSocket to the browser target."""
+
+    def __init__(self, url: str) -> None:
+        from websockets.sync.client import connect
+
+        # Chrome shows "Allow remote debugging?" for this connection; give the user time to click it.
+        self._ws = connect(url, open_timeout=60, max_size=64 * 1024 * 1024)
+        self._id = 0
+
+    def send(self, method: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        self._id += 1
+        self._ws.send(json.dumps({"id": self._id, "method": method, "params": params or {}}))
+        while True:
+            message = json.loads(self._ws.recv(timeout=60))
+            if message.get("id") != self._id:
+                continue
+            if "error" in message:
+                raise ToolError(f"Chrome refused {method}: {message['error'].get('message')}", ErrorCode.INTERNAL_ERROR)
+            return message.get("result") or {}
+
+    def close(self) -> None:
+        self._ws.close()
+
+
+def from_chrome(cdp: str | None = None, profile_dir: str | None = None) -> Session:
+    """Read the app's cookies of a running Chrome. Nothing is changed in the browser."""
+    url = _endpoint(cdp) if cdp else auto_endpoint(profile_dir)
+    try:
+        client = _Cdp(url)
+    except Exception as exc:
+        raise ToolError(
+            f"Could not connect to Chrome at {urlsplit(url).netloc} ({type(exc).__name__}). "
+            "Is Chrome open, and did you click Allow in its remote debugging prompt?",
+            ErrorCode.AUTH_REQUIRED,
+        ) from exc
+    try:
+        version = client.send("Browser.getVersion")
+        cookies = client.send("Storage.getCookies").get("cookies") or []
+    finally:
+        client.close()
+    mine = [
+        {"name": c["name"], "value": c["value"], "domain": c["domain"], "path": c.get("path") or "/"}
+        for c in cookies
+        if any(c.get("domain", "").lstrip(".").endswith(domain) for domain in app.DOMAINS)
+    ]
+    user_agent = version.get("userAgent")
+    match = re.search(r"Chrome/(\d+)", user_agent or "") or re.search(r"/(\d+)\.", version.get("product", ""))
+    session = Session(
+        cookies=mine,
+        user_agent=user_agent,
+        chrome_major=int(match.group(1)) if match else None,
+        source=cdp or "auto",
+    )
+    if not session.signed_in:
+        raise ToolError(
+            f"This Chrome is not signed in to {app.NAME}. Sign in at {app.LOGIN_URL}, then run this again.",
+            ErrorCode.AUTH_REQUIRED,
+        )
+    return session
+
+
+def refresh(session: Session) -> Session | None:
+    """Read the cookies again from where they came from; None when the source is a hand-copied token."""
+    if not session.source or session.source == "token":
+        return None
+    fresh = from_chrome(None if session.source == "auto" else session.source)
+    fresh.proxy = session.proxy
+    save(fresh)
+    return fresh

substack_api_mcp/substack/auth.py

@@ -0,0 +1,26 @@
+"""Who is signed in: Substack's own answer for the account (substack.com/api/v1/user/profile/self)."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from substack_api_mcp.core.errors import AuthExpiredError
+from substack_api_mcp.substack.client import WEB
+
+if TYPE_CHECKING:
+    from substack_api_mcp.core.context import ToolContext
+
+
+async def whoami(ctx: ToolContext) -> str | None:
+    """None only when Substack says signed out; any other failure raises (detection tries again later)."""
+    try:
+        response = await ctx.call("GET", f"{WEB}/api/v1/user/profile/self", headers={"accept": "application/json"})
+    except AuthExpiredError:
+        return None
+    if response.status != 200:
+        return None
+    me = response.json()
+    if not me.get("id"):
+        return None
+    name, handle = me.get("name") or "", me.get("handle") or ""
+    return f"{name} (@{handle})" if name and handle else name or (f"@{handle}" if handle else None)

substack_api_mcp/substack/client.py

@@ -0,0 +1,172 @@
+"""Substack web requests recorded on a test publication (17.10.2026).
+
+Two hosts, both with the account's own cookies (`substack.sid` on .substack.com):
+- `substack.com/api/v1`: the reader app (who am I, Notes, comment lookup).
+- `{subdomain}.substack.com/api/v1`: the publisher dashboard of one publication (posts, drafts, stats,
+  subscribers, comments). Requests go to the subdomain even when the publication has a custom domain:
+  the custom domain is outside the manifest's domains, and Substack answers the same on both.
+The tools work on the account's own publication: the first one it administers, as the dashboard opens it.
+Answers keep Substack's ids as strings; times are ISO 8601 as Substack sends them. Cursors are offsets.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING, Any
+
+from substack_api_mcp.core.errors import ErrorCode, TargetBlockedError, ToolError
+from substack_api_mcp.core.helpers import json_field, page_cursor
+
+if TYPE_CHECKING:
+    from substack_api_mcp.core.context import ToolContext
+
+WEB = "https://substack.com"
+_PUBLISHER_ROLES = ("admin", "owner", "editor", "contributor")
+# The preloads are a JSON string inside the page, so the quotes may come escaped.
+_BANNED = re.compile(r'is_globally_banned\\*"\s*:\s*true')
+
+
+async def me(ctx: ToolContext) -> dict[str, Any]:
+    """The signed-in user's profile with their publications (`publicationUsers`)."""
+    return await call(ctx, "GET", f"{WEB}/api/v1/user/profile/self")
+
+
+async def publication(ctx: ToolContext) -> dict[str, Any]:
+    """The account's own publication: ids, base URL of its dashboard API and the author's byline id."""
+    profile = await me(ctx)
+    for row in profile.get("publicationUsers") or []:
+        pub = row.get("publication") or {}
+        if row.get("role") in _PUBLISHER_ROLES and pub.get("subdomain"):
+            return {
+                "id": pub.get("id"),
+                "name": pub.get("name"),
+                "subdomain": pub["subdomain"],
+                "base": f"https://{pub['subdomain']}.substack.com",
+                "user_id": profile.get("id"),
+                "handle": profile.get("handle"),
+                "role": row.get("role"),
+            }
+    if await _suspended(ctx):
+        raise TargetBlockedError(
+            "Substack suspended this account and hid its publication. The notice and the appeal link are on "
+            "substack.com in your Cloud Browser."
+        )
+    raise ToolError("This Substack account has no publication it can publish to.", ErrorCode.APP_PERMISSION_DENIED)
+
+
+async def _suspended(ctx: ToolContext) -> bool:
+    """A suspended account still signs in, but its profile lists no publications (18.10.2026).
+
+    Only the page's preloaded user says why (`is_globally_banned`); no JSON endpoint carries it.
+    """
+    response = await ctx.call("GET", f"{WEB}/", headers={"accept": "text/html"})
+    return bool(_BANNED.search(response.text))
+
+
+async def call(
+    ctx: ToolContext, method: str, url: str, *, params: dict[str, Any] | None = None, body: Any = None
+) -> Any:
+    """One Substack API request; errors become messages for the agent."""
+    host = url.split("/api/")[0]
+    headers = {"referer": f"{host}/", "origin": host, "accept": "application/json"}
+    response = await ctx.call(method, url, params=params, json=body, headers=headers)
+    if response.status == 404:
+        raise ToolError("Substack has no such item, or this account cannot see it.", ErrorCode.TARGET_ERROR)
+    if response.status == 429:
+        raise ToolError("Substack is limiting this account; try again in a few minutes.", ErrorCode.RATE_LIMITED)
+    if response.status >= 400:
+        raise ToolError(f"Substack refused the request ({response.status}).", ErrorCode.TARGET_ERROR)
+    if not response.text.strip():
+        return {}
+    try:
+        return response.json()
+    except ValueError as exc:
+        raise ToolError("Substack answered with a page instead of data.", ErrorCode.TARGET_ERROR) from exc
+
+
+def offset_cursor(cursor: str | None) -> int:
+    """Offsets as cursors: none is the first page, anything else is a next_cursor we handed out."""
+    return page_cursor(cursor) if cursor else 0
+
+
+def next_cursor(offset: int, got: int, wanted: int) -> str | None:
+    return str(offset + got) if got >= wanted else None
+
+
+def comment_id(value: Any, source: str = "list_comments") -> int:
+    """Comments and Notes share one ID space; Note URLs prefix it with c-."""
+    text = str(value or "").strip().removeprefix("c-")
+    if not text.isdigit():
+        raise ToolError(f"comment_id must be the numeric ID from {source}.", ErrorCode.INVALID_INPUT)
+    return int(text)
+
+
+async def user_ref(ctx: ToolContext, value: Any) -> dict[str, Any]:
+    """A Substack user by numeric ID or handle (with or without @): id, name and handle."""
+    text = str(value or "").strip().removeprefix("@")
+    if not re.fullmatch(r"[A-Za-z0-9_]{1,80}", text):
+        raise ToolError("user must be a Substack handle or a numeric user ID.", ErrorCode.INVALID_INPUT)
+    if text.isdigit():
+        # Profiles are looked up by handle only; a numeric ID goes straight to the request.
+        return {"id": int(text), "name": "", "handle": ""}
+    found = await call(ctx, "GET", f"{WEB}/api/v1/user/{text}/public_profile")
+    return {"id": int(found["id"]), "name": found.get("name") or "", "handle": found.get("handle") or ""}
+
+
+def person(user: dict[str, Any] | None) -> dict[str, Any]:
+    """Who someone is in our answers: never their email."""
+    user = user or {}
+    return {
+        "user_id": str(user.get("id") or user.get("user_id") or ""),
+        "name": user.get("name") or "",
+        "handle": user.get("handle") or "",
+    }
+
+
+def post_id(value: Any) -> int:
+    text = str(value or "").strip()
+    if not text.isdigit():
+        raise ToolError("post_id must be the numeric ID from list_posts.", ErrorCode.INVALID_INPUT)
+    return int(text)
+
+
+def post_status(post: dict[str, Any]) -> str:
+    if post.get("is_published"):
+        return "published"
+    if post.get("trigger_at") or post.get("postSchedules"):
+        return "scheduled"
+    return "draft"
+
+
+def post_url(pub: dict[str, Any], post: dict[str, Any]) -> str | None:
+    if not post.get("is_published") or not post.get("slug"):
+        return None
+    return post.get("canonical_url") or f"{pub['base']}/p/{post['slug']}"
+
+
+def scheduled_at(post: dict[str, Any]) -> str | None:
+    if post.get("trigger_at"):
+        return post["trigger_at"]
+    schedules = post.get("postSchedules") or []
+    return schedules[0].get("trigger_at") if schedules else None
+
+
+async def draft(ctx: ToolContext, pub: dict[str, Any], pid: int) -> dict[str, Any]:
+    """The editor's copy of a post: drafts, scheduled and published posts alike (body in `body`/`draft_body`)."""
+    return await call(ctx, "GET", f"{pub['base']}/api/v1/drafts/{pid}")
+
+
+def require_draft(post: dict[str, Any]) -> None:
+    if post.get("is_published"):
+        raise ToolError("This post is already published; only drafts can be changed here.", ErrorCode.INVALID_INPUT)
+
+
+def body_doc(post: dict[str, Any]) -> dict[str, Any]:
+    """The post's ProseMirror document: the published body, else the draft's."""
+    raw = post.get("body") if post.get("is_published") and post.get("body") else post.get("draft_body")
+    doc = json_field(raw)
+    return doc if isinstance(doc, dict) else {"type": "doc", "content": []}
+
+
+def byline(pub: dict[str, Any]) -> list[dict[str, Any]]:
+    return [{"id": pub["user_id"], "is_guest": False}]

substack_api_mcp/substack/feed.py

@@ -0,0 +1,31 @@
+"""Items of Substack's reader feeds (search, home feed): posts and Notes in one shape for our answers."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from substack_api_mcp.substack.client import person
+
+
+def post_item(item: dict[str, Any]) -> dict[str, Any]:
+    post, pub = item["post"], item.get("publication") or {}
+    return {
+        "post_id": str(post["id"]),
+        "title": post.get("title") or "",
+        "publication": pub.get("name") or "",
+        "publication_id": str(post.get("publication_id") or pub.get("id") or ""),
+        "published_at": post.get("post_date"),
+        "likes": int(post.get("reaction_count") or 0),
+        "url": post.get("canonical_url"),
+    }
+
+
+def note_item(item: dict[str, Any]) -> dict[str, Any]:
+    note = item["comment"]
+    return {
+        "note_id": str(note["id"]),
+        "author": person({"id": note.get("user_id"), "name": note.get("name"), "handle": note.get("handle")}),
+        "body": note.get("body") or "",
+        "published_at": note.get("date"),
+        "likes": int(note.get("reaction_count") or 0),
+    }