ctfy.sdk.resources.changelog

 1"""``client.changelog`` — the public "What's New" feed."""
 2
 3from __future__ import annotations
 4
 5from ctfy.sdk._helpers import _raise_for_status
 6from ctfy.sdk.base import BaseHttpClient
 7from ctfy.server.models import (
 8    ChangelogLatestResponse,
 9    ChangelogListResponse,
10    ChangelogSeenResponse,
11)
12
13
14class ChangelogResource:
15    """Read what shipped, and clear your own "What's New" marker.
16
17    The list needs no bearer — a changelog is read by people deciding
18    whether to run the platform — but ``latest`` answers a *per-caller*
19    question, so an authenticated client gets ``unseen`` and an anonymous
20    one gets ``False``.
21    """
22
23    def __init__(self, http: BaseHttpClient) -> None:
24        self._http = http
25
26    def list(self, page: int = 1, page_size: int = 20) -> ChangelogListResponse:
27        """Published entries, newest first. Drafts are never returned."""
28        resp = self._http.request(
29            "GET", "/changelog", params={"page": page, "page_size": page_size}
30        )
31        _raise_for_status(resp)
32        return ChangelogListResponse.model_validate(resp.json())
33
34    def latest(self) -> ChangelogLatestResponse:
35        """The newest publish time, plus whether it post-dates this
36        caller's last visit. Cheap enough to poll for a nav badge."""
37        resp = self._http.request("GET", "/changelog/latest")
38        _raise_for_status(resp)
39        return ChangelogLatestResponse.model_validate(resp.json())
40
41    def mark_seen(self) -> ChangelogSeenResponse:
42        """Stamp "read up to now" — clears the badge for this account."""
43        resp = self._http.request("POST", "/changelog/mark-seen")
44        _raise_for_status(resp)
45        return ChangelogSeenResponse.model_validate(resp.json())