parro-api-client 0.5.0__py3-none-any.whl

parro/__init__.py

@@ -0,0 +1,17 @@
+"""Read-only client for the Parro REST API (talk.parro.com), shared by the CLI and the MCP server.
+
+Everything that talks to Parro or to the ParnasSys login server lives in this package. The two entry
+points only translate between their own interface (command line, MCP JSON-RPC) and this core.
+
+This package must never:
+  * send anything other than GET to the Parro API (POST goes only to the IdP's token, revoke and
+    login-form endpoints);
+  * write tokens, passwords or full attachment URLs to a log;
+  * start a password login on its own after a password was rejected (see authenticator.py).
+
+Inspired by fobatai/parro-mcp; independent implementation based on openapi/parro.openapi.json.
+"""
+
+# The one place the version lives. pyproject.toml repeats it; a test keeps the two equal, and the
+# release workflow checks that the git tag matches.
+__version__ = "0.5.0"

parro/api_client.py

@@ -0,0 +1,413 @@
+"""ParroClient: read-only access to the Parro REST API (https://rest-v2.parro.com/rest/v2).
+
+get() is the one low-level call; every endpoint in the spec has a small method on top of it
+(get_account, list_groups, list_events, get_event, ...). They return the API's own JSON, untouched;
+summaries.py shapes it for people.
+
+Rules for this module:
+  * Only GET. There is no method that could change anything at Parro.
+  * Requests only go to the configured API host, so a token can never be sent elsewhere.
+  * A 401 leads to one refresh and one retry, never to a password login (PLAN-api-client §4, fix 3).
+    A second 401 raises TokenRejected, which explains the `dtype` pitfall of GET /event/{id}.
+"""
+
+import logging
+import urllib.parse
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from .authenticator import Authenticator
+from .cache import Cache
+from .errors import ApiError, ConfigurationError, TokenRejected
+from .geon import (
+    build_range_header,
+    get_collection_items,
+    get_object_id,
+    parse_total_from_content_range,
+)
+from .http import HttpRequest, HttpResponse, HttpTransport, UrllibTransport, add_query_parameters
+from .settings import Settings
+from .token_store import TokenStore
+
+log = logging.getLogger(__name__)
+
+# dtype values that select what an endpoint returns (spec: GET /event, GET /event/{id}, GET /group).
+ANNOUNCEMENT_LIST_DTYPE = "event.RAnnouncementEventPrimer"
+CALENDAR_LIST_DTYPE = "event.RCalendarItemEventPrimer"
+# RAnnouncementEvent answers 401 (not 406) on GET /event/{id}; the Primer type works (fix 2).
+ANNOUNCEMENT_DTYPE = "event.RAnnouncementEventPrimer"
+CALENDAR_ITEM_DTYPE = "event.RCalendarItemEvent"
+CURRENT_GROUPS_DTYPE = "identity.RHomeGroup"
+PREVIOUS_GROUPS_SCOPE = "PREVIOUS_ACTIVE"
+# The groups request of the official client asks for 50; enough for any family.
+GROUPS_PAGE_SIZE = 50
+PRIVACY_CHILD_DTYPE = "identity.RPrivacySettingChild"
+
+EventKind = Literal["announcement", "calendar"]
+
+
+@dataclass(frozen=True)
+class ApiResponse:
+    """A parsed answer: the JSON payload and, for collections, the Content-Range header."""
+
+    payload: Any
+    content_range: str | None
+
+    @property
+    def items(self) -> list[Any]:
+        return get_collection_items(self.payload)
+
+    @property
+    def total(self) -> int | None:
+        return parse_total_from_content_range(self.content_range)
+
+
+@dataclass(frozen=True)
+class FeedEvent:
+    """One event from a group's feed, with the name of the group it was listed under."""
+
+    event: dict[str, Any]
+    group_name: str | None
+
+
+class ParroClient:
+    """Talks to the Parro API on behalf of one logged-in account."""
+
+    def __init__(
+        self,
+        settings: Settings,
+        transport: HttpTransport | None = None,
+        token_store: TokenStore | None = None,
+        authenticator: Authenticator | None = None,
+    ) -> None:
+        self.settings = settings
+        self.transport = transport or UrllibTransport(settings.http_timeout_seconds)
+        self.token_store = token_store or TokenStore(
+            settings.token_file, bootstrap_access_token=settings.bootstrap_access_token
+        )
+        self.authenticator = authenticator or Authenticator(
+            settings, self.transport, self.token_store
+        )
+        # Attachments and calendar details only (PLAN-readable-output §3b); lists never.
+        self.cache = Cache(
+            settings.data_dir / "cache", settings.cache_max_bytes, enabled=settings.cache_enabled
+        )
+        self._account: dict[str, Any] | None = None
+        self._role_header: str | None = None
+
+    @classmethod
+    def from_environment(cls) -> "ParroClient":
+        return cls(Settings.from_environment())
+
+    # ------------------------------------------------------------------------- low level
+
+    def get(
+        self,
+        path: str,
+        params: dict[str, Any] | None = None,
+        limit: int | None = None,
+        offset: int = 0,
+        count_total: bool = False,
+        send_role: bool = True,
+        allow_password_login: bool = True,
+        refresh_on_unauthorized: bool = True,
+    ) -> ApiResponse:
+        """GET an API path such as '/child' or '/event?dtype=...&group=1'.
+
+        `limit` sends a Range header (and `count_total` asks for an exact total). `send_role`
+        False leaves out parro-authorization-role, which GET /account/me must be called without.
+        `refresh_on_unauthorized` False reports a 401 at once (for probing a dtype).
+        """
+        url = add_query_parameters(self.build_api_url(path), params or {})
+        label = f"GET {urllib.parse.urlsplit(url).path}"
+        headers = self._build_headers(limit, offset, count_total, send_role, allow_password_login)
+        response = self._send_with_one_refresh(url, headers, label, refresh_on_unauthorized)
+        if response.status not in (200, 206):
+            raise _api_error(label, response)
+        return ApiResponse(response.json(), response.header("Content-Range"))
+
+    def download_from_api_host(self, url: str) -> HttpResponse:
+        """GET a file that lives on the API host itself (not the CDN), with the Parro headers."""
+        if not url.startswith(self.settings.api_base_uri + "/"):
+            raise ConfigurationError("Only URLs on the configured Parro API host get a token.")
+        headers = self._build_headers(None, 0, False, True, True)
+        headers["Accept"] = "*/*"
+        response = self._send_with_one_refresh(url, headers, "GET file on the API host", True)
+        if response.status not in (200, 206):
+            raise _api_error("GET file on the API host", response)
+        return response
+
+    def _send_with_one_refresh(
+        self, url: str, headers: dict[str, str], label: str, refresh_on_unauthorized: bool
+    ) -> HttpResponse:
+        """Send; on a 401 refresh once and resend once (fix 3). A 401 never leads to a login."""
+        response = self._send(url, headers, label)
+        if response.status == 401 and refresh_on_unauthorized:
+            new_access_token = self.authenticator.refresh_after_unauthorized()
+            if new_access_token is not None:
+                headers["Authorization"] = f"Bearer {new_access_token}"
+                response = self._send(url, headers, label)
+        if response.status == 401:
+            raise TokenRejected(
+                f"{label} answered 401 Unauthorized. Either the login is no longer valid (log "
+                "in again), or this endpoint refuses the requested `dtype` (GET /event/{id} "
+                "answers 401 for dtype=event.RAnnouncementEvent).",
+                status=401,
+            )
+        return response
+
+    def build_api_url(self, path: str) -> str:
+        """Turn '/child' (or '/rest/v2/child') into a full URL on the configured API host."""
+        cleaned = path.strip()
+        if "://" in cleaned or cleaned.startswith("//"):
+            raise ConfigurationError(
+                "Give an API path such as /accountsettings, not a full URL: the token is only "
+                "ever sent to the configured Parro API host."
+            )
+        if not cleaned.startswith("/"):
+            cleaned = "/" + cleaned
+        if cleaned.startswith("/rest/"):
+            return self.settings.api_base_uri + cleaned
+        return self.settings.api_root + cleaned
+
+    def _build_headers(
+        self,
+        limit: int | None,
+        offset: int,
+        count_total: bool,
+        send_role: bool,
+        allow_password_login: bool,
+    ) -> dict[str, str]:
+        access_token = self.authenticator.get_access_token(allow_password_login)
+        # The web client sends the geon media type as Accept *and* Content-Type, even on GET.
+        headers = {
+            "Authorization": f"Bearer {access_token}",
+            "Accept": self.settings.geon_media_type,
+            "Content-Type": self.settings.geon_media_type,
+            "parro-app-version": self.settings.app_version,
+        }
+        if send_role:
+            role = self.get_role_header(allow_password_login)
+            if role:
+                headers["parro-authorization-role"] = role
+        if limit is not None:
+            headers["Range"] = build_range_header(offset, limit)
+            if count_total:
+                headers["topicus-Range-Count"] = "Exact"
+        return headers
+
+    def _send(self, url: str, headers: dict[str, str], label: str) -> HttpResponse:
+        return self.transport.send(HttpRequest("GET", url, dict(headers), log_label=label))
+
+    # ---------------------------------------------------------------------- account and role
+
+    def get_account(self, allow_password_login: bool = True) -> dict[str, Any]:
+        """GET /account/me (cached). Called without the role header, which is derived from it."""
+        if self._account is None:
+            response = self.get(
+                "/account/me", send_role=False, allow_password_login=allow_password_login
+            )
+            self._account = response.payload if isinstance(response.payload, dict) else {}
+        return self._account
+
+    def get_role_header(self, allow_password_login: bool = True) -> str | None:
+        """'GUARDIAN:<id>' for parro-authorization-role: PARRO_ROLE, else derived and cached.
+
+        The id is that of the first guardian (or teacher, or child) identity of the account
+        (spec: Conventions → Client headers).
+        """
+        if self.settings.role_override:
+            return self.settings.role_override
+        if self._role_header is None:
+            self._role_header = derive_role_header(self.get_account(allow_password_login))
+        return self._role_header
+
+    # -------------------------------------------------------------------- simple endpoints
+
+    def get_account_settings(self) -> ApiResponse:
+        return self.get("/accountsettings")
+
+    def get_organisation(self, organisation_id: int) -> ApiResponse:
+        return self.get(f"/organisation/{int(organisation_id)}")
+
+    def list_children(self, limit: int = 20) -> ApiResponse:
+        return self.get("/child", limit=limit, count_total=True)
+
+    def get_unread_counts(self) -> ApiResponse:
+        return self.get("/identity/unreadcounts")
+
+    def list_groups(
+        self, previous_year: bool = False, limit: int = GROUPS_PAGE_SIZE
+    ) -> ApiResponse:
+        """Current groups (dtype=identity.RHomeGroup) or last year's (scope=PREVIOUS_ACTIVE)."""
+        params = (
+            {"scope": PREVIOUS_GROUPS_SCOPE} if previous_year else {"dtype": CURRENT_GROUPS_DTYPE}
+        )
+        return self.get("/group", params, limit=limit, count_total=True)
+
+    def list_system_news(self, limit: int = 20) -> ApiResponse:
+        return self.get("/systemnews", limit=limit, count_total=True)
+
+    def get_calendar_link(self) -> str | None:
+        """GET /calendar/sync: the personal iCalendar subscription link, or None if there is none.
+
+        The link is a secret (anyone holding it can read the calendar), so it is never logged.
+        """
+        payload = self.get("/calendar/sync").payload
+        strings = payload.get("strings") if isinstance(payload, dict) else None
+        links = [
+            link for link in strings or [] if isinstance(link, str) and link.startswith("http")
+        ]
+        return links[0] if links else None
+
+    def list_children_privacy(self) -> ApiResponse:
+        """GET /child, privacy variant: per child, the state of the privacy choices (spec)."""
+        params = {"currentSchoolYear": "true", "dtype": PRIVACY_CHILD_DTYPE}
+        return self.get("/child", params, count_total=True)
+
+    def get_privacy_link(self, child_id: int) -> str | None:
+        """GET /child/{id}/privacy: the signed link to the page where the choices are set.
+
+        Like the calendar link it is a secret (it opens the page without a login), so it is never
+        logged, cached or archived.
+        """
+        payload = self.get(f"/child/{int(child_id)}/privacy").payload
+        link = payload.get("url") if isinstance(payload, dict) else None
+        return link if isinstance(link, str) and link.startswith("https://") else None
+
+    def get_absence_settings(self) -> ApiResponse:
+        return self.get("/absence/setting")
+
+    def list_chatrooms(self, limit: int = 25, offset: int = 0) -> ApiResponse:
+        return self.get("/chatroom", limit=limit, offset=offset, count_total=True)
+
+    def list_chat_messages(self, chatroom_id: int, limit: int = 30, offset: int = 0) -> ApiResponse:
+        """Messages of one chat, newest first (spec)."""
+        return self.get(
+            f"/chatroom/{int(chatroom_id)}/chatmessage",
+            limit=limit,
+            offset=offset,
+            count_total=True,
+        )
+
+    # ---------------------------------------------------------------------------- events
+
+    def list_events(
+        self,
+        group_id: int,
+        event_dtype: str,
+        limit: int = 20,
+        offset: int = 0,
+        count_total: bool = False,
+    ) -> ApiResponse:
+        """GET /event for one group. `event_dtype` picks announcements or calendar items.
+
+        Both come newest first. For calendar items that means the furthest future first: the
+        coming weeks can be several pages in (see operations.collect_calendar).
+        """
+        return self.get(
+            "/event",
+            {"dtype": event_dtype, "group": int(group_id)},
+            limit=limit,
+            offset=offset,
+            count_total=count_total,
+        )
+
+    def get_event(self, event_id: int, event_dtype: str) -> dict[str, Any]:
+        """GET /event/{id}. The dtype is required: without it the API answers 406."""
+        payload = self.get(f"/event/{int(event_id)}", {"dtype": event_dtype}).payload
+        return payload if isinstance(payload, dict) else {}
+
+    def get_announcement(self, announcement_id: int) -> dict[str, Any]:
+        return self.get_event(announcement_id, ANNOUNCEMENT_DTYPE)
+
+    def get_calendar_item(self, event_id: int) -> dict[str, Any]:
+        return self.get_event(event_id, CALENDAR_ITEM_DTYPE)
+
+    def get_announcement_or_calendar_item(self, event_id: int) -> dict[str, Any]:
+        """The event behind an id when the caller does not know its type (e.g. `attachment`).
+
+        Tries the announcement type first without the usual refresh-on-401, because the API may
+        answer a wrong dtype with 401 (spec) and that is not a reason to touch the tokens. Then
+        tries the calendar-item type the normal way.
+        """
+        try:
+            payload = self.get(
+                f"/event/{int(event_id)}",
+                {"dtype": ANNOUNCEMENT_DTYPE},
+                refresh_on_unauthorized=False,
+            ).payload
+        except ApiError as first_failure:
+            log.info(
+                "event is not an announcement (%s); trying calendar item", first_failure.status
+            )
+            return self.get_calendar_item(event_id)
+        return payload if isinstance(payload, dict) else {}
+
+    def list_current_group_names(self) -> dict[int, str | None]:
+        """{group id: group name} for this school year's groups, in the API's order."""
+        names: dict[int, str | None] = {}
+        for group in self.get(
+            "/group", {"dtype": CURRENT_GROUPS_DTYPE}, limit=GROUPS_PAGE_SIZE
+        ).items:
+            group_id = get_object_id(group)
+            if group_id is not None:
+                names[group_id] = group.get("name")
+        return names
+
+    def collect_feed(
+        self,
+        event_dtype: str,
+        group_id: int | None = None,
+        limit_per_group: int = 20,
+        groups: dict[int, str | None] | None = None,
+    ) -> list[FeedEvent]:
+        """Events of one group, or of every current group (the spec: query each group separately).
+
+        Events carry the group's name only when several groups were merged. Not sorted: the caller
+        decides the order. `groups` ({id: name}) saves the group request when the caller already
+        has them, e.g. the overview, which reads two feeds.
+        """
+        if group_id is not None:
+            chosen: dict[int, str | None] = {int(group_id): None}
+        else:
+            chosen = groups if groups is not None else self.list_current_group_names()
+        collected: list[FeedEvent] = []
+        for one_group_id, group_name in chosen.items():
+            page = self.list_events(one_group_id, event_dtype, limit=limit_per_group)
+            collected.extend(FeedEvent(event, group_name) for event in page.items)
+        return collected
+
+
+def derive_role_header(account: dict[str, Any]) -> str | None:
+    """'<ACCOUNTTYPE>:<id>' from GET /account/me, or None when the account has no identities."""
+    identity = account.get("identity") or {}
+    account_type = str(account.get("accountType") or identity.get("role") or "GUARDIAN").upper()
+    for identity_list in ("guardians", "teachers", "children"):
+        for linked_identity in identity.get(identity_list) or []:
+            identity_id = get_object_id(linked_identity)
+            if identity_id is not None:
+                return f"{account_type}:{identity_id}"
+    log.warning("could not derive the role header from /account/me")
+    return None
+
+
+def _api_error(label: str, response: HttpResponse) -> ApiError:
+    """An ApiError with the geon error details (applicationError, message) when there are any."""
+    try:
+        body = response.json()
+    except ValueError:
+        body = None
+    application_error = None
+    detail = ""
+    if isinstance(body, dict):
+        application_error = body.get("applicationError")
+        parts = [str(part) for part in (application_error, body.get("message")) if part]
+        detail = f": {' - '.join(parts)}" if parts else ""
+    elif response.body:
+        detail = f": {response.text()[:200]}"
+    return ApiError(
+        f"{label} answered HTTP {response.status}{detail}",
+        status=response.status,
+        application_error=application_error,
+    )

parro/archive.py

@@ -0,0 +1,235 @@
+"""The local archive written by the `sync` command (PLAN-readable-output §3b, release 0.3.0).
+
+    <archive>/
+      announcements/2026-10-22-nieuwsbrief-nr-3-5000000101.md   (+ .json)
+      announcements/attachments/5000000101-6000000101-Nieuwsbrief-3.pdf
+      calendar/2026-11-11-sint-maartenviering-7000000101.md     (+ .json, + attachments/)
+      chats/rijden-naar-het-natuurmuseum-8000000001.md          (+ .json)
+      index.md                                                  (everything, newest first)
+      .sync-state.json                                          (what is archived, for the next run)
+
+This module only writes files; operations.sync_archive() decides what to fetch.
+
+Rules:
+  * Incremental: an item whose version (its `lastModifiedAt`) is unchanged is not rewritten, and
+    a saved attachment is never downloaded again.
+  * File names: date + slug of the title + id. When a title changes, the files are renamed, so
+    there is never a stale copy next to the new one.
+  * Nothing is ever deleted. An item that is no longer in Parro stays, and index.md marks it.
+  * Folders 0700, files 0600 (children's names, photos and school mail); no download links in
+    any file.
+"""
+
+import json
+import re
+import unicodedata
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from .cache import remove_urls, write_private_file
+
+STATE_FILE = ".sync-state.json"
+INDEX_FILE = "index.md"
+SECTIONS = {"announcement": "announcements", "calendar": "calendar", "chat": "chats"}
+SECTION_TITLES = {"announcement": "Announcements", "calendar": "Calendar", "chat": "Chats"}
+MAX_SLUG_LENGTH = 50
+
+
+@dataclass
+class SyncCounts:
+    """What one run did, per kind of item."""
+
+    written: int = 0
+    unchanged: int = 0
+    renamed: int = 0
+    no_longer_in_parro: int = 0
+
+
+@dataclass
+class ArchiveEntry:
+    """One archived item, as remembered in the state file."""
+
+    kind: str
+    item_id: int
+    version: str
+    title: str
+    date: str
+    path: str  # relative to the archive root, e.g. "announcements/2026-...-5000000101.md"
+    scope: str  # "current", "previous" or "chats": which run is responsible for it
+    present: bool = True
+    groups: list[str] = field(default_factory=list)
+
+
+class Archive:
+    """The archive folder: its files and its memory of what was written before."""
+
+    def __init__(self, root: Path) -> None:
+        self.root = root
+        self.entries: dict[str, ArchiveEntry] = load_state(root / STATE_FILE)
+        self.counts: dict[str, SyncCounts] = {kind: SyncCounts() for kind in SECTIONS}
+        self._seen: set[str] = set()
+
+    # ------------------------------------------------------------------------ items
+
+    def is_current(self, kind: str, item_id: int, version: str) -> bool:
+        """True when this version is already archived (and its file still exists)."""
+        entry = self.entries.get(entry_key(kind, item_id))
+        return entry is not None and entry.version == version and (self.root / entry.path).exists()
+
+    def keep(self, kind: str, item_id: int) -> None:
+        """Note an unchanged item as still present in Parro."""
+        key = entry_key(kind, item_id)
+        self._seen.add(key)
+        self.entries[key].present = True
+        self.counts[kind].unchanged += 1
+
+    def save(self, entry: ArchiveEntry, markdown: str, summary: Any) -> None:
+        """Write (or rewrite) one item: its .md with a header, and its .json without links."""
+        key = entry_key(entry.kind, entry.item_id)
+        self._seen.add(key)
+        previous = self.entries.get(key)
+        name_date = "" if entry.kind == "chat" else entry.date  # chats: no date in the name
+        stem = file_stem(name_date, entry.title, entry.item_id)
+        entry.path = f"{SECTIONS[entry.kind]}/{stem}.md"
+        if previous is not None and previous.path != entry.path:
+            self._rename(previous.path, entry.path)
+            self.counts[entry.kind].renamed += 1
+        header = front_matter(entry)
+        self._write(entry.path, (header + markdown).encode("utf-8"))
+        self._write(json_path(entry.path), json_text(remove_urls(summary)).encode("utf-8"))
+        self.entries[key] = entry
+        self.counts[entry.kind].written += 1
+
+    # ------------------------------------------------------------------ attachments
+
+    def has_file(self, relative_path: str) -> bool:
+        """True when the file is saved. Files are written in one step, so it is complete."""
+        return (self.root / relative_path).exists()
+
+    def save_file(self, relative_path: str, data: bytes) -> None:
+        self._write(relative_path, data)
+
+    # ----------------------------------------------------------------------- finish
+
+    def finish(self, scopes: set[str], synced_at: datetime) -> None:
+        """Mark what the synced scopes no longer contain, then write index.md and the state."""
+        for key, entry in self.entries.items():
+            if entry.scope in scopes and key not in self._seen and entry.present:
+                entry.present = False
+                self.counts[entry.kind].no_longer_in_parro += 1
+        self._write(INDEX_FILE, build_index(list(self.entries.values()), synced_at).encode("utf-8"))
+        self._write(STATE_FILE, json_text(save_state(self.entries)).encode("utf-8"))
+
+    # ---------------------------------------------------------------------- helpers
+
+    def _write(self, relative_path: str, data: bytes) -> None:
+        write_private_file(self.root / relative_path, data)
+
+    def _rename(self, old: str, new: str) -> None:
+        for source, target in ((old, new), (json_path(old), json_path(new))):
+            old_file, new_file = self.root / source, self.root / target
+            if old_file.exists():
+                new_file.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+                old_file.replace(new_file)
+
+
+# ----------------------------------------------------------------------- names and text
+
+
+def entry_key(kind: str, item_id: int) -> str:
+    return f"{kind}:{item_id}"
+
+
+def slugify(title: str) -> str:
+    """'Foto's herfstwandeling!' → 'fotos-herfstwandeling' (ASCII, lowercase, at most 50)."""
+    ascii_title = unicodedata.normalize("NFKD", title).encode("ascii", "ignore").decode("ascii")
+    words = re.sub(r"[^a-z0-9]+", "-", ascii_title.lower().replace("'", "")).strip("-")
+    return words[:MAX_SLUG_LENGTH].rstrip("-") or "untitled"
+
+
+def file_stem(date: str, title: str, item_id: int) -> str:
+    """'2026-10-22-nieuwsbrief-nr-3-5000000101'; chats have no date prefix."""
+    prefix = f"{date[:10]}-" if re.match(r"^\d{4}-\d{2}-\d{2}", date or "") else ""
+    return f"{prefix}{slugify(title)}-{item_id}"
+
+
+def attachment_path(kind: str, item_id: int, attachment_id: Any, filename: str | None) -> str:
+    """'announcements/attachments/5000000101-6000000101-Nieuwsbrief-3.pdf' (a safe file name).
+
+    Attachments live next to their item's section, so the link from the item's .md file is
+    simply 'attachments/<name>'.
+    """
+    name = Path(filename or "attachment").name
+    safe = re.sub(r"[^A-Za-z0-9._-]+", "-", name).strip("-.") or "attachment"
+    return f"{SECTIONS[kind]}/attachments/{item_id}-{attachment_id}-{safe}"
+
+
+def json_path(markdown_path: str) -> str:
+    return markdown_path[: -len(".md")] + ".json"
+
+
+def json_text(value: Any) -> str:
+    return json.dumps(value, ensure_ascii=False, indent=2, default=str) + "\n"
+
+
+def front_matter(entry: ArchiveEntry) -> str:
+    """A YAML header (strings written as JSON strings, which YAML reads as they are)."""
+    lines = [
+        "---",
+        f"id: {entry.item_id}",
+        f"type: {entry.kind}",
+        f"title: {json.dumps(entry.title, ensure_ascii=False)}",
+        f"date: {json.dumps(entry.date)}",
+        f"groups: {json.dumps(entry.groups, ensure_ascii=False)}",
+        f"version: {json.dumps(entry.version)}",
+        "source: Parro, archived with parro-api-client (sync)",
+        "---",
+        "",
+    ]
+    return "\n".join(lines) + "\n"
+
+
+def build_index(entries: list[ArchiveEntry], synced_at: datetime) -> str:
+    """index.md: every archived item per kind, newest first, with a mark for removed ones."""
+    blocks = [
+        "# Parro archive",
+        f"Last sync: {synced_at.strftime('%Y-%m-%d %H:%M %Z').strip()}. Items no longer in Parro "
+        "stay here and are marked *(no longer in Parro)*.",
+    ]
+    for kind, title in SECTION_TITLES.items():
+        items = sorted((e for e in entries if e.kind == kind), key=lambda e: e.date, reverse=True)
+        lines = [index_line(entry) for entry in items]
+        blocks.append(f"## {title} ({len(items)})\n" + ("\n".join(lines) if lines else "None yet."))
+    return "\n\n".join(blocks) + "\n"
+
+
+def index_line(entry: ArchiveEntry) -> str:
+    when = f"{entry.date[:10]} " if entry.date[:4].isdigit() else ""
+    groups = f" · {', '.join(entry.groups)}" if entry.groups else ""
+    gone = " *(no longer in Parro)*" if not entry.present else ""
+    link_text = entry.title.replace("[", "(").replace("]", ")") or "(no title)"
+    return f"- {when}[{link_text}]({entry.path}){groups}{gone}"
+
+
+# ------------------------------------------------------------------------- state file
+
+
+def load_state(path: Path) -> dict[str, ArchiveEntry]:
+    """The entries of the previous run; an unreadable state file starts a fresh archive."""
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+    entries = {}
+    for key, value in (raw.get("entries") or {}).items():
+        try:
+            entries[key] = ArchiveEntry(**value)
+        except TypeError:
+            continue
+    return entries
+
+
+def save_state(entries: dict[str, ArchiveEntry]) -> dict[str, Any]:
+    return {"format": 1, "entries": {key: vars(entry) for key, entry in sorted(entries.items())}}