notion-agent-cli 0.1.1__py3-none-any.whl

notion_agent_cli/__init__.py

@@ -0,0 +1,28 @@
+"""notion-agent-cli — call Notion's ✦ AI endpoint from Python / the shell.
+
+Public API:
+
+- :class:`NotionAgentClient` — async client for one round-trip to
+  ``/api/v3/runInferenceTranscript``. Loads a credential file, builds
+  the chat-panel-equivalent payload, streams the NDJSON response.
+- :class:`ChatResponse` / :class:`TokenUsage` — response dataclasses.
+- :class:`NotionAgentError` — single error type for transport / auth /
+  Notion-side failures. CLI translates this to a non-zero exit code.
+
+Library callers will spend most of their time on those four names; the
+sub-modules (``transcript``, ``ndjson``, ``account``, ``models``) are
+useful for tests + bootstrap helpers and remain importable.
+"""
+from notion_agent_cli.exceptions import ErrorCode, NotionAgentError
+from notion_agent_cli.provider import NotionAgentClient
+from notion_agent_cli.types import ChatResponse, TokenUsage
+
+__all__ = [
+    "ChatResponse",
+    "ErrorCode",
+    "NotionAgentClient",
+    "NotionAgentError",
+    "TokenUsage",
+]
+
+__version__ = "0.1.0"

notion_agent_cli/account.py

@@ -0,0 +1,141 @@
+"""Account credentials + workspace metadata.
+
+The credential file (default ``~/.notionagents/notion_account.json``)
+holds a long-lived ``token_v2`` cookie + workspace UUIDs + an optional
+Custom Agent persona binding. Schema details + bootstrap walkthrough
+live in ``docs/01-notion-chat-protocol.md §4``.
+
+We prefer ``full_cookie`` (the raw ``document.cookie`` string copied
+from the browser) when present — that's the operator's escape hatch
+when individual-field extraction is too fiddly. Otherwise we stitch
+together the minimum set Notion's edge expects for a logged-in session.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from notion_agent_cli.exceptions import ErrorCode, NotionAgentError
+
+_REQUIRED_FIELDS: tuple[str, ...] = (
+    "token_v2",
+    "user_id",
+    "space_id",
+)
+
+
+@dataclass(slots=True, frozen=True)
+class NotionAccount:
+    # --- Credentials ---
+    token_v2: str
+    full_cookie: str = ""
+
+    # --- Identity ---
+    user_id: str = ""
+    user_name: str = ""
+    user_email: str = ""
+
+    # --- Workspace ---
+    space_id: str = ""
+    space_name: str = ""
+    space_view_id: str = ""
+
+    # --- Browser fingerprint ---
+    browser_id: str = ""
+    device_id: str = ""
+    client_version: str = "23.13.20260516.0113"
+    user_agent: str = (
+        "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 "
+        "(KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36"
+    )
+    timezone: str = "America/Los_Angeles"
+
+    # --- Custom agent persona (Jarvis-style binding) ---
+    # Setting these makes threads surface in Notion's ✦ AI chat panel
+    # under the named persona instead of the default chat.
+    agent_name: str = ""
+    agent_accessory: str = ""
+    agent_context_page_id: str = ""
+
+    # --- Default model alias ---
+    default_model: str = "opus-4.7"
+
+    # --- Forward-compat ---
+    extras: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def has_jarvis_binding(self) -> bool:
+        return bool(self.agent_name and self.agent_context_page_id)
+
+
+def load_notion_account(path: Path | str) -> NotionAccount:
+    """Read ``notion_account.json`` and return a validated NotionAccount.
+
+    Raises :class:`NotionAgentError` on missing file, malformed JSON, or
+    missing required fields so misconfiguration fails at startup rather
+    than mid-stream.
+    """
+    p = Path(path).expanduser()
+    if not p.exists():
+        raise NotionAgentError(
+            f"notion_account.json not found at {p}; run "
+            "`notion-agent init --cookie <value>` to bootstrap one.",
+            code=ErrorCode.ACCOUNT_MISSING,
+        )
+    try:
+        data: dict[str, Any] = json.loads(p.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as e:
+        raise NotionAgentError(
+            f"notion_account.json malformed: {e}",
+            code=ErrorCode.ACCOUNT_MALFORMED,
+        ) from e
+
+    missing = [f for f in _REQUIRED_FIELDS if not data.get(f)]
+    if missing:
+        raise NotionAgentError(
+            f"notion_account.json missing required fields: {missing}. "
+            "Run `notion-agent init` to regenerate.",
+            code=ErrorCode.ACCOUNT_INVALID,
+        )
+
+    known = {f.name for f in NotionAccount.__dataclass_fields__.values()} - {"extras"}
+    kwargs = {k: data[k] for k in known if k in data}
+    extras = {k: v for k, v in data.items() if k not in known}
+    return NotionAccount(**kwargs, extras=extras)
+
+
+def save_notion_account(acc: NotionAccount, path: Path | str) -> None:
+    """Serialize a NotionAccount to JSON. Used by the `init` subcommand."""
+    p = Path(path).expanduser()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    data: dict[str, Any] = {}
+    for f in NotionAccount.__dataclass_fields__.values():
+        if f.name == "extras":
+            continue
+        data[f.name] = getattr(acc, f.name)
+    data.update(acc.extras)  # extras round-trip
+    p.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+
+
+def build_cookie_header(acc: NotionAccount) -> str:
+    """Cookie header value — prefers full_cookie when set, else stitches
+    together the minimum logged-in subset."""
+    if acc.full_cookie:
+        return acc.full_cookie
+
+    user_id = acc.user_id
+    user_id_nodash = user_id.replace("-", "")
+    parts = [
+        f"notion_browser_id={acc.browser_id}",
+        f"device_id={acc.device_id}",
+        f"notion_user_id={user_id}",
+        f'notion_users=[%22{user_id}%22]',
+        "notion_check_cookie_consent=false",
+        "notion_locale=en-US/legacy",
+        "notion_cookie_sync_completed=%7B%22completed%22%3Atrue%2C%22version%22%3A4%7D",
+        f"_cioid={user_id_nodash}",
+        f"token_v2={acc.token_v2}",
+    ]
+    return "; ".join(parts)

notion_agent_cli/agents.py

@@ -0,0 +1,129 @@
+"""Parse ``/api/v3/getCustomAgents`` into agent + thread summaries.
+
+A single round-trip to ``getCustomAgents`` answers both "what custom
+agents do I have here?" and "what threads have I run recently?" —
+:func:`parse_custom_agents` splits the response into two ranked lists
+the ``agents list`` / ``threads list`` CLI subcommands print.
+
+The endpoint *does not* return agent display names — only their
+``persistent_instructions_page`` UUIDs. To find the human name of an
+agent you still need :func:`notion_agent_cli.bootstrap.fetch_user_content`
+or a page-chunk lookup; for the MVP we surface the page id + activity
+score + the title of the agent's most recent thread as a breadcrumb.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(slots=True, frozen=True)
+class ThreadSummary:
+    """One entry from ``mostRecentTranscripts``."""
+    thread_id:        str
+    title:            str | None
+    parent_agent_id:  str | None
+    created_at_ms:    int | None
+    updated_at_ms:    int | None
+    created_by_id:    str | None
+    created_source:   str | None
+
+
+@dataclass(slots=True, frozen=True)
+class AgentSummary:
+    """One custom agent + its most recent activity breadcrumb."""
+    agent_id:                  str
+    activity_score:            int | None  # epoch ms, None if no activity recorded
+    most_recent_thread_id:     str | None
+    most_recent_thread_title:  str | None
+
+
+def _to_int(value: Any) -> int | None:
+    if value is None:
+        return None
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def parse_threads(response: dict[str, Any]) -> list[ThreadSummary]:
+    """Pull ``mostRecentTranscripts`` into a list sorted updated→created→id desc.
+
+    Missing fields land as ``None`` rather than raising — Notion returns
+    nulls for transcripts that never got past creation.
+    """
+    out: list[ThreadSummary] = []
+    for entry in response.get("mostRecentTranscripts") or []:
+        if not isinstance(entry, dict):
+            continue
+        tid = entry.get("id")
+        if not isinstance(tid, str):
+            continue
+        out.append(ThreadSummary(
+            thread_id=       tid,
+            title=           entry.get("title") if isinstance(entry.get("title"), str) else None,
+            parent_agent_id= entry.get("parent_id") if isinstance(entry.get("parent_id"), str) else None,
+            created_at_ms=   _to_int(entry.get("created_time")),
+            updated_at_ms=   _to_int(entry.get("updated_time")),
+            created_by_id=   entry.get("created_by_id") if isinstance(entry.get("created_by_id"), str) else None,
+            created_source=  entry.get("created_source") if isinstance(entry.get("created_source"), str) else None,
+        ))
+    # Sort newest-first by max(updated, created) so transcripts that
+    # never got an updated_at still slot in chronologically by their
+    # creation time — matches what the CLI prints in the timestamp
+    # column. Tiebreak on thread_id for stable output.
+    def _sort_key(t: ThreadSummary) -> tuple[int, str]:
+        newest = max(t.updated_at_ms or 0, t.created_at_ms or 0)
+        return (-newest, t.thread_id)
+    out.sort(key=_sort_key)
+    return out
+
+
+def parse_agents(response: dict[str, Any]) -> list[AgentSummary]:
+    """Combine ``agentIds`` + ``activityScores`` + most-recent thread title.
+
+    Sorted by activity_score desc (most-recently-used first). Agents
+    with no recorded activity sink to the bottom with ``activity_score
+    = None``.
+    """
+    agent_ids: list[str] = [
+        x for x in (response.get("agentIds") or []) if isinstance(x, str)
+    ]
+
+    activity: dict[str, int] = {}
+    for entry in response.get("activityScores") or []:
+        if not isinstance(entry, dict):
+            continue
+        pid = entry.get("parent_id")
+        score = _to_int(entry.get("activity_score"))
+        if (
+            isinstance(pid, str)
+            and score is not None
+            and (pid not in activity or activity[pid] < score)
+        ):
+            # If duplicates, keep the highest score (= most recent activity).
+            activity[pid] = score
+
+    # Best-effort breadcrumb: agent's most recent thread (title + id).
+    threads = parse_threads(response)  # already sorted newest-first
+    recent_by_agent: dict[str, ThreadSummary] = {}
+    for t in threads:
+        if t.parent_agent_id and t.parent_agent_id not in recent_by_agent:
+            recent_by_agent[t.parent_agent_id] = t
+
+    out: list[AgentSummary] = []
+    for aid in agent_ids:
+        recent = recent_by_agent.get(aid)
+        out.append(AgentSummary(
+            agent_id=                aid,
+            activity_score=          activity.get(aid),
+            most_recent_thread_id=   recent.thread_id if recent else None,
+            most_recent_thread_title=recent.title if recent else None,
+        ))
+
+    def _sort_key(a: AgentSummary) -> tuple[int, str]:
+        # None scores sink to the bottom; tiebreak on agent_id for stable order.
+        return (-(a.activity_score or 0), a.agent_id)
+    out.sort(key=_sort_key)
+    return out

notion_agent_cli/bootstrap.py

@@ -0,0 +1,253 @@
+"""Workspace metadata bootstrap.
+
+Library function used by the ``notion-agent init`` CLI subcommand.
+Takes a ``token_v2`` cookie (the only thing the operator can copy from
+a browser in <30s) plus optional fingerprint UUIDs, then calls
+``/api/v3/loadUserContent`` to enumerate workspaces + extract user
+identity. Returns a populated :class:`NotionAccount` ready to save.
+
+If the user has multiple workspaces and the caller didn't pre-select
+one, :func:`bootstrap_account` raises :class:`AmbiguousWorkspaceError`
+carrying the available choices so the CLI can prompt.
+"""
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from notion_agent_cli.account import NotionAccount
+from notion_agent_cli.exceptions import ErrorCode, NotionAgentError
+
+BASE_URL = "https://www.notion.so/api/v3"
+DEFAULT_UA = (
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 "
+    "(KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36"
+)
+
+
+@dataclass(slots=True, frozen=True)
+class Workspace:
+    space_id: str
+    space_view_id: str
+    space_name: str
+    domain: str
+
+
+@dataclass(slots=True, frozen=True)
+class UserInfo:
+    user_id: str
+    user_name: str
+    user_email: str
+
+
+class AmbiguousWorkspaceError(NotionAgentError):
+    """Raised when bootstrap finds >1 workspace and caller didn't pick one."""
+
+    def __init__(self, workspaces: list[Workspace]):
+        super().__init__(
+            f"{len(workspaces)} workspaces available — caller must specify which: "
+            + ", ".join(f"{w.space_name!r}" for w in workspaces),
+            code=ErrorCode.WORKSPACE_AMBIGUOUS,
+        )
+        self.workspaces = workspaces
+
+
+def parse_browser_cookie(cookie: str) -> dict[str, str]:
+    """Parse a ``document.cookie`` string into ``{name: value}`` pairs.
+
+    Values are kept verbatim — ``token_v2`` in particular is left in its
+    URL-encoded form (``v03%3A...``), which is what Notion's edge accepts
+    in subsequent requests. Whitespace around names and values is trimmed.
+    Entries without ``=`` are dropped silently.
+    """
+    out: dict[str, str] = {}
+    for part in cookie.split(";"):
+        part = part.strip()
+        if not part or "=" not in part:
+            continue
+        name, _, value = part.partition("=")
+        out[name.strip()] = value.strip()
+    return out
+
+
+def _build_cookie(token_v2: str, browser_id: str, user_id: str) -> str:
+    return "; ".join([
+        f"notion_browser_id={browser_id}",
+        f"notion_user_id={user_id}",
+        f'notion_users=[%22{user_id}%22]',
+        "notion_check_cookie_consent=false",
+        "notion_locale=en-US/legacy",
+        f"token_v2={token_v2}",
+    ])
+
+
+def _bootstrap_headers(token_v2: str, browser_id: str, user_id: str) -> dict[str, str]:
+    return {
+        "accept":                       "application/json",
+        "accept-language":              "en-US,en;q=0.9",
+        "content-type":                 "application/json",
+        "notion-audit-log-platform":    "web",
+        "notion-client-version":        "23.13.20260516.0113",
+        "origin":                       "https://www.notion.so",
+        "referer":                      "https://www.notion.so/",
+        "user-agent":                   DEFAULT_UA,
+        "x-notion-active-user-header":  user_id,
+        "sec-ch-ua":                    '"Not-A.Brand";v="24", "Chromium";v="146"',
+        "sec-ch-ua-mobile":             "?0",
+        "sec-ch-ua-platform":           '"macOS"',
+        "sec-fetch-dest":               "empty",
+        "sec-fetch-mode":               "cors",
+        "sec-fetch-site":               "same-origin",
+        "cookie":                       _build_cookie(token_v2, browser_id, user_id),
+    }
+
+
+def _walk_record(record: dict[str, Any]) -> dict[str, Any]:
+    """Unwrap Notion's ``{'role': '...', 'value': {...}}`` records."""
+    if not isinstance(record, dict):
+        return {}
+    val = record.get("value")
+    if isinstance(val, dict):
+        inner = val.get("value")
+        if isinstance(inner, dict):
+            return inner
+        return val
+    return record
+
+
+def _extract_workspaces(load_data: dict[str, Any]) -> list[Workspace]:
+    rm = load_data.get("recordMap") or {}
+    spaces_raw = rm.get("space") or {}
+    space_views_raw = rm.get("space_view") or {}
+
+    sv_by_space: dict[str, str] = {}
+    for sv_id, sv_rec in space_views_raw.items():
+        sv = _walk_record(sv_rec)
+        sp = sv.get("space_id")
+        if isinstance(sp, str) and sp not in sv_by_space:
+            sv_by_space[sp] = sv_id
+
+    out: list[Workspace] = []
+    for space_id, space_rec in spaces_raw.items():
+        sp = _walk_record(space_rec)
+        out.append(Workspace(
+            space_id=space_id,
+            space_view_id=sv_by_space.get(space_id, ""),
+            space_name=sp.get("name") or "",
+            domain=sp.get("domain") or "",
+        ))
+    return out
+
+
+def _extract_user(load_data: dict[str, Any], user_id: str) -> UserInfo:
+    rm = load_data.get("recordMap") or {}
+    users_raw = rm.get("notion_user") or {}
+    rec = users_raw.get(user_id)
+    if not rec:
+        return UserInfo(user_id=user_id, user_name="", user_email="")
+    u = _walk_record(rec)
+    name_parts = [u.get("given_name") or "", u.get("family_name") or ""]
+    name = " ".join(p for p in name_parts if p).strip() or u.get("name") or ""
+    return UserInfo(user_id=user_id, user_name=name, user_email=u.get("email") or "")
+
+
+async def fetch_user_content(
+    *, token_v2: str, user_id: str, browser_id: str,
+    http_client: httpx.AsyncClient | None = None,
+) -> dict[str, Any]:
+    """Call /api/v3/loadUserContent and return the parsed response."""
+    headers = _bootstrap_headers(token_v2, browser_id, user_id)
+    owns_client = http_client is None
+    client = http_client or httpx.AsyncClient(timeout=30.0)
+    try:
+        resp = await client.post(f"{BASE_URL}/loadUserContent", json={}, headers=headers)
+        if resp.status_code != 200:
+            code = (
+                ErrorCode.AUTH_INVALID
+                if resp.status_code in (401, 403)
+                else ErrorCode.HTTP_ERROR
+            )
+            raise NotionAgentError(
+                f"loadUserContent failed: HTTP {resp.status_code} body={resp.text[:500]!r}",
+                code=code,
+            )
+        return resp.json()
+    finally:
+        if owns_client:
+            await client.aclose()
+
+
+def _ensure_uuid(value: str | None) -> str:
+    return value or str(uuid.uuid4())
+
+
+async def bootstrap_account(
+    *,
+    token_v2: str,
+    user_id: str,
+    browser_id: str | None = None,
+    space_name: str | None = None,
+    space_domain: str | None = None,
+    agent_name: str = "",
+    agent_accessory: str = "",
+    agent_context_page_id: str = "",
+    default_model: str = "opus-4.7",
+    timezone: str = "America/Los_Angeles",
+    http_client: httpx.AsyncClient | None = None,
+) -> NotionAccount:
+    """Probe ``/api/v3/loadUserContent`` and return a populated NotionAccount.
+
+    Raises :class:`AmbiguousWorkspaceError` when multiple workspaces are
+    available and ``space_name`` / ``space_domain`` didn't disambiguate.
+    """
+    browser_id = _ensure_uuid(browser_id)
+    data = await fetch_user_content(
+        token_v2=token_v2, user_id=user_id, browser_id=browser_id,
+        http_client=http_client,
+    )
+    workspaces = _extract_workspaces(data)
+    if not workspaces:
+        raise NotionAgentError(
+            "loadUserContent returned no workspaces — token invalid?",
+            code=ErrorCode.WORKSPACE_EMPTY,
+        )
+
+    if len(workspaces) == 1:
+        chosen = workspaces[0]
+    elif space_domain:
+        match = next((w for w in workspaces if w.domain == space_domain), None)
+        if match is None:
+            raise AmbiguousWorkspaceError(workspaces)
+        chosen = match
+    elif space_name:
+        match = next(
+            (w for w in workspaces if w.space_name.lower() == space_name.lower()),
+            None,
+        )
+        if match is None:
+            raise AmbiguousWorkspaceError(workspaces)
+        chosen = match
+    else:
+        raise AmbiguousWorkspaceError(workspaces)
+
+    user = _extract_user(data, user_id)
+
+    return NotionAccount(
+        token_v2=token_v2,
+        user_id=user_id,
+        user_name=user.user_name,
+        user_email=user.user_email,
+        space_id=chosen.space_id,
+        space_view_id=chosen.space_view_id,
+        space_name=chosen.space_name,
+        browser_id=browser_id,
+        device_id=_ensure_uuid(None),
+        timezone=timezone,
+        agent_name=agent_name,
+        agent_accessory=agent_accessory,
+        agent_context_page_id=agent_context_page_id,
+        default_model=default_model,
+    )

notion_agent_cli/cli/__init__.py

@@ -0,0 +1,6 @@
+"""CLI surface — entry point is :mod:`notion_agent_cli.cli.__main__`.
+
+The package exposes a single ``notion-agent`` console-script registered
+in pyproject.toml. Subcommands live in this module; for now everything
+fits in ``__main__.py``, but we'll split per-command files as they grow.
+"""