455class Commit(ScrapboxModel):
456    """A commit in the history of a page."""
457
458    id: str
459    kind: str | None = None
460    changes: list[PageChange] = Field(default_factory=list)
461    parent_id: str | None = None
462    page_id: str | None = None
463    user_id: str | None = None
464    created: int | None = None

467class CommitsResponse(ScrapboxModel):
468    """Response from the commit history API."""
469
470    commits: list[Commit] = Field(default_factory=list)

503class EditPreviewResponse(ScrapboxModel):
504    """Response from the page edit preview API.
505
506    The preview is a dry run: nothing is written until `preview_id` is submitted,
507    and it expires a few minutes after it is issued.
508    """
509
510    preview_id: str
511    expire_at: str | None = None
512    page_preview: PagePreview | None = None

538class EditSubmitResponse(ScrapboxModel):
539    """Response from the page edit submit API."""
540
541    commit_id: str
542    page: SubmittedPage | None = None

473class FileInfo(ScrapboxModel):
474    """Metadata of a file uploaded to a project."""
475
476    id: str
477    project_name: str | None = None
478    text: str | None = None
479    """Text extracted from the file (OCR of an image, body of a PDF), truncated by the API."""
480    originalname: str | None = None
481    content_type: str | None = None
482    size: int | None = None

600class GyazoOEmbedResponse(RootModel[GyazoOEmbedResponsePhoto | GyazoOEmbedResponseVideo]):
601    """Response from the Gyazo oEmbed API.
602
603    See: https://gyazo.com/api/docs/image#oembed
604    """
605
606    model_config = ConfigDict(alias_generator=to_camel, from_attributes=True, populate_by_name=True)

181class Line(ScrapboxModel):
182    """Line data in a page."""
183
184    id: str
185    text: str
186    user_id: str = Field(alias="userId")
187    created: int
188    updated: int

191class LinkPage(ScrapboxModel):
192    """A page in the 1-hop or 2-hop neighbourhood of another page.
193
194    Which fields the API fills in varies between entries, so nearly everything is
195    optional here.
196    """
197
198    id: str
199    title: str
200    title_lc: str | None = None
201    image: str | None = None
202    descriptions: list[str] = Field(default_factory=list)
203    links_lc: list[str] = Field(default_factory=list)
204    linked: int | None = None
205    page_rank: float | None = None
206    views: int | None = None
207    lines_count: int | None = None
208    chars_count: int | None = None
209    created: int | None = None
210    updated: int | None = None
211    accessed: int | None = None
212    last_accessed: int | None = None
213    user: User | None = None
214    last_update_user: User | None = None
215    users: list[User] = Field(default_factory=list)
216    infobox_definition: list[str] | None = None
217    infobox_disable_links: list[str] | None = None
218    infobox_result: list[InfoboxResult] | None = None
219    search: Any = None
220    """Search highlight information, present only when the request carried a query."""

237class Links1hopResponse(ScrapboxModel):
238    """Response from the 1-hop related pages API."""
239
240    links1hop: list[LinkPage] = Field(default_factory=list, alias="links1hop")
241    chars_count: int | None = None
242    has_back_links_or_icons: bool | None = None
243    kcs_control_tags_lc: list[str] = Field(default_factory=list)
244    synonyms: list[Any] = Field(default_factory=list)
245    search_backend: str | None = None
246    pagination: Pagination | None = None

249class Links2hopResponse(ScrapboxModel):
250    """Response from the 2-hop related pages API.
251
252    The direct 1-hop neighbourhood is not included.
253    """
254
255    links2hop: list[LinkPage] = Field(default_factory=list, alias="links2hop")
256    hidden_headwords_lc: list[str] = Field(default_factory=list)
257    synonyms: list[Any] = Field(default_factory=list)
258    search_backend: str | None = None
259    pagination: Pagination | None = None

48class Me(User):
49    """The authenticated user, as returned by the `users/me` endpoint."""
50
51    provider: str | None = None
52    page_filters: list[PageFilter] = Field(default_factory=list)
53    created: int | None = None
54    updated: int | None = None
55    is_guest: bool | None = None
56    config: dict[str, Any] = Field(default_factory=dict)

31class NotAuthenticatedError(ScrapboxError):
32    """Raised when an endpoint answers as if no one is logged in.
33
34    `users/me` does not answer 401 without a credential: it answers 200 with
35    `{"isGuest": true}` and nothing else, so the absence of a credential has to be
36    read out of the body rather than the status code.
37    """
38
39    def __init__(self) -> None:
40        """Initialize the error."""
41        super().__init__(
42            "Not authenticated. Pass pat= or connect_sid= to ScrapboxClient.",
43        )

324class PageDetail(PageBase):
325    """Detailed information about a page, from the v1 endpoint."""
326
327    related_pages: RelatedPages | None = None

330class PageDetailV2(PageBase):
331    """Detailed information about a page, from the v2 endpoint.
332
333    Compared with `PageDetail` this carries the normalized `*_lc` variants but no
334    embedded related pages.
335    """
336
337    links_lc: list[str] = Field(default_factory=list)
338    icons_lc: list[str] = Field(default_factory=list)
339    project_links_lc: list[str] = Field(default_factory=list)

151class PageListItem(ScrapboxModel):
152    """An item in the page list."""
153
154    id: str
155    title: str
156    image: str | None = None
157    descriptions: list[str]
158    user: User
159    last_update_user: User | None = None
160    pin: int
161    views: int
162    linked: int
163    created: int
164    updated: int
165    accessed: int
166    lines_count: int = Field(alias="linesCount")
167    chars_count: int = Field(alias="charsCount")
168    helpfeels: list[str]

171class PageListResponse(ScrapboxModel):
172    """Response from the page list API."""
173
174    project_name: str = Field(alias="projectName")
175    skip: int
176    limit: int
177    count: int
178    pages: list[PageListItem]

 9class PersonalAccessTokenRequiredError(ScrapboxError):
10    """Raised when a write endpoint is called without a credential it accepts.
11
12    The page editing endpoints (`page-edit-for-ai/preview` and
13    `page-edit-for-ai/submit`) reject `connect.sid` cookie authentication with
14    HTTP 403, so the client refuses to send the request in the first place. They do
15    accept a service account access key, which writes as the service account.
16    """
17
18    def __init__(self, endpoint: str) -> None:
19        """Initialize the error.
20
21        Args:
22            endpoint: Path of the endpoint that needs a header credential.
23        """
24        super().__init__(
25            f"{endpoint} needs a personal access token or a service account access key. "
26            f"Pass pat= or service_account_key= to ScrapboxClient."
27        )
28        self.endpoint = endpoint

 93class Project(ScrapboxModel):
 94    """A project the authenticated user belongs to."""
 95
 96    id: str
 97    name: str
 98    display_name: str | None = None
 99    public_visible: bool | None = None
100    login_strategies: list[str] = Field(default_factory=list)
101    plan: str | None = None
102    additional_plans: dict[str, bool] = Field(default_factory=dict)
103    alert: dict[str, Any] | None = None
104    users_count: int | None = None
105    is_member: bool | None = None
106    billing_id: str | None = None
107    created: int | None = None
108    updated: int | None = None
109    is_owner: bool | None = None
110    is_admin: bool | None = None
111    admins_count: int | None = None

120class ProjectDetail(Project):
121    """A single project, as returned by the project detail API.
122
123    Compared with the entries of the project list, this carries the project's own
124    settings and its member list, but not the counters (`users_count`,
125    `admins_count`) that only the list fills in.
126    """
127
128    theme: str | None = None
129    image: str | None = None
130    gyazo_teams_name: str | None = None
131    translation: bool | None = None
132    infobox: bool | None = None
133    disable_realtime_collaboration: bool | None = None
134    users: list[User] = Field(default_factory=list)
135    """Members of the project. A public project answers with `id` and `name` alone."""

80class ProjectUsersResponse(ScrapboxModel):
81    """Response from the project members API.
82
83    A page or line author may be a current member, a departed one or a service
84    account, so all four lists are needed to resolve an author id to a name.
85    """
86
87    users: list[ProjectMember] = Field(default_factory=list)
88    member_snapshots: list[MemberSnapshot] = Field(default_factory=list)
89    service_accounts: list[ServiceAccount] = Field(default_factory=list)
90    service_account_snapshots: list[ServiceAccount] = Field(default_factory=list)

114class ProjectsResponse(ScrapboxModel):
115    """Response from the project list API."""
116
117    projects: list[Project] = Field(default_factory=list)

141class ScrapboxClient:
142    """Scrapbox API client.
143
144    This client provides methods to interact with the Scrapbox API,
145    including retrieving page lists, page details, page text, and files.
146    """
147
148    """Base URL for the Scrapbox API."""
149    BASE_URL = f"{SCRAPBOX_ORIGIN}/api"
150
151    def __init__(
152        self,
153        connect_sid: str | None = None,
154        pat: str | None = None,
155        service_account_key: str | None = None,
156        transport: httpx.BaseTransport | None = None,
157    ) -> None:
158        """Initialize the Scrapbox API client.
159
160        Authentication is optional for public projects. Only one credential is ever
161        sent: given more than one, a personal access token wins over a service
162        account key, which in turn wins over a cookie.
163
164        Args:
165            connect_sid: Scrapbox authentication cookie (connect.sid).
166            pat: Scrapbox personal access token, sent as the `x-personal-access-token`
167                header.
168            service_account_key: Access key of a service account, sent as the
169                `x-service-account-access-key` header. A service account is registered
170                on one project of a Business plan and can read and write only that
171                one: any other project, even a public one, answers 400. It stands for
172                no user, so `get_me` and `get_projects` are out of its reach, and
173                `get_project` refuses it as well.
174            transport: Transport used by the underlying HTTP client. Intended for
175                tests, which pass an `httpx.MockTransport` so that header handling
176                is still exercised.
177        """
178        self.pat = pat
179        self.service_account_key = None if pat else service_account_key
180        self.connect_sid = None if pat or service_account_key else connect_sid
181        self.client = httpx.Client(
182            cookies={"connect.sid": self.connect_sid} if self.connect_sid else None,
183            follow_redirects=True,
184            transport=transport,
185        )
186        if self.pat or self.service_account_key:
187            # Attach the credential per request instead of as a default header:
188            # get_file() follows redirects to third-party hosts (Gyazo), which must
189            # not receive it.
190            self.client.event_hooks["request"].append(self._attach_credential)
191
192    def _attach_credential(self, request: httpx.Request) -> None:
193        """Attach the header credential to requests sent to Scrapbox.
194
195        Args:
196            request: The outgoing request.
197        """
198        if request.url.host != SCRAPBOX_HOST:
199            return
200        if self.pat:
201            request.headers[PAT_HEADER] = self.pat
202        elif self.service_account_key:
203            request.headers[SERVICE_ACCOUNT_HEADER] = self.service_account_key
204
205    def __enter__(self: Self) -> Self:
206        """Enter the runtime context related to this object."""
207        return self
208
209    def __exit__(self, typ: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None, /) -> None:
210        """Exit the runtime context related to this object."""
211        self.client.close()
212
213    def close(self) -> None:
214        """Close the HTTP client."""
215        self.client.close()
216
217    @staticmethod
218    def _raise_for_status(response: httpx.Response) -> None:
219        """Turn an error response into an exception.
220
221        The status code alone rarely says what went wrong -- a service account asked
222        for the wrong project gets a bare 400 -- so the API's own explanation is
223        carried into the error message.
224
225        Args:
226            response: The response to inspect.
227
228        Raises:
229            SearchServerUpdatingError: If the search backend is being updated.
230            httpx.HTTPStatusError: If the response carries any other error status.
231        """
232        if response.status_code == SearchServerUpdatingError.STATUS_CODE:
233            # The name adds nothing here: the exception class already carries it.
234            try:
235                message = response.json().get("message")
236            except ValueError:
237                message = None
238            raise SearchServerUpdatingError(message)
239        try:
240            response.raise_for_status()
241        except httpx.HTTPStatusError as e:
242            detail = error_detail(response)
243            if detail is None:
244                raise
245            msg = f"{e}\n{detail}"
246            raise httpx.HTTPStatusError(msg, request=e.request, response=e.response) from None
247
248    def _get(self, path: str, params: Mapping[str, Any] | None = None) -> httpx.Response:
249        """Send a GET request to a path under `BASE_URL`.
250
251        Args:
252            path: Path below `BASE_URL`, starting with a slash.
253            params: Query parameters. Entries are sent as given.
254
255        Returns:
256            The successful response.
257        """
258        response = self.client.get(f"{self.BASE_URL}{path}", params=params)
259        self._raise_for_status(response)
260        return response
261
262    def _get_json(self, path: str, params: Mapping[str, Any] | None = None) -> Any:  # noqa: ANN401
263        """Send a GET request and decode the JSON body.
264
265        Args:
266            path: Path below `BASE_URL`, starting with a slash.
267            params: Query parameters. Entries are sent as given.
268
269        Returns:
270            The decoded JSON body.
271        """
272        return self._get(path, params).json()
273
274    def _post_json(self, path: str, payload: Mapping[str, Any]) -> Any:  # noqa: ANN401
275        """Send a POST request and decode the JSON body.
276
277        Write endpoints take a header credential -- a personal access token or a
278        service account access key -- and refuse a cookie with HTTP 403, so the
279        request is not even sent without one.
280
281        Args:
282            path: Path below `BASE_URL`, starting with a slash.
283            payload: JSON body to send.
284
285        Returns:
286            The decoded JSON body.
287
288        Raises:
289            PersonalAccessTokenRequiredError: If neither a personal access token nor a
290                service account access key is set.
291        """
292        if not (self.pat or self.service_account_key):
293            raise PersonalAccessTokenRequiredError(path)
294        response = self.client.post(f"{self.BASE_URL}{path}", json=dict(payload))
295        self._raise_for_status(response)
296        return response.json()
297
298    def get_pages(
299        self,
300        project_name: str,
301        skip: int = 0,
302        limit: int = 100,
303        sort: PageSort | None = None,
304        filter_value: str | None = None,
305    ) -> PageListResponse:
306        """Get a list of pages from a project.
307
308        The page bodies are not included. At most 1000 pages come back per request,
309        so `skip` is how a whole project is walked.
310
311        Args:
312            project_name: The name of the project.
313            skip: Number of pages to skip (default: 0).
314            limit: Number of pages to retrieve (default: 100, max: 1000).
315            sort: Order of the returned pages (default: the API's own, `updated`).
316            filter_value: Keep only the pages carrying a `[<value>.icon]` reference,
317                plus the pages that user has edited. Use the login name, not the
318                display name.
319
320        Returns:
321            PageListResponse: The response containing the page list.
322
323        Raises:
324            ValueError: If `limit` is outside 1 to `MAX_PAGE_SIZE`.
325        """
326        check_page_size(limit, "limit")
327        params: dict[str, Any] = {"skip": skip, "limit": limit}
328        if sort is not None:
329            params["sort"] = sort
330        if filter_value is not None:
331            params["filterType"] = "icon"
332            params["filterValue"] = filter_value
333        return PageListResponse.model_validate(self._get_json(f"/pages/{project_name}", params))
334
335    def get_page(self, project_name: str, page_title: str) -> PageDetail:
336        """Get detailed information about a specific page.
337
338        Args:
339            project_name: The name of the project.
340            page_title: The title of the page.
341
342        Returns:
343            PageDetail: The detailed information about the page.
344        """
345        encoded_title = quote(page_title, safe="")
346        return PageDetail.model_validate(self._get_json(f"/pages/{project_name}/{encoded_title}"))
347
348    def get_page_v2(self, project_name: str, page_title: str) -> PageDetailV2:
349        """Get detailed information about a page from the v2 endpoint.
350
351        Compared with `get_page`, this carries the normalized `links_lc` /`icons_lc` /
352        `project_links_lc` fields but no embedded related pages; use `get_links_1hop`
353        and `get_links_2hop` for those.
354
355        Args:
356            project_name: The name of the project.
357            page_title: The title of the page.
358
359        Returns:
360            PageDetailV2: The detailed information about the page.
361        """
362        encoded_title = quote(page_title, safe="")
363        return PageDetailV2.model_validate(self._get_json(f"/pages/v2/{project_name}/{encoded_title}"))
364
365    def get_links_1hop(  # noqa: PLR0913 - one parameter per query parameter the endpoint takes
366        self,
367        project_name: str,
368        page_title: str,
369        search: str | None = None,
370        *,
371        match_any: bool = False,
372        per_page: int | None = None,
373        next_id: str | None = None,
374    ) -> Links1hopResponse:
375        """Get one page of the 1-hop neighbourhood of a page.
376
377        Use `iter_links_1hop` to walk a neighbourhood larger than one page.
378
379        Args:
380            project_name: The name of the project.
381            page_title: The title of the page.
382            search: Keep only the neighbours whose body matches this query.
383            match_any: Match pages containing any of the words in `search` instead of
384                all of them.
385            per_page: Number of neighbours per page (default: the API's own, 1000).
386                Must be between 1 and `MAX_PAGE_SIZE`.
387            next_id: Continue after this entry, as reported by `pagination.next_id`
388                of the previous page.
389
390        Returns:
391            Links1hopResponse: The neighbouring pages.
392
393        Raises:
394            ValueError: If `per_page` is outside 1 to `MAX_PAGE_SIZE`.
395        """
396        encoded_title = quote(page_title, safe="")
397        return Links1hopResponse.model_validate(
398            self._get_json(
399                f"/pages/v2/{project_name}/{encoded_title}/links1hop",
400                self._related_params(search, match_any=match_any, per_page=per_page, next_id=next_id),
401            )
402        )
403
404    def get_links_2hop(  # noqa: PLR0913 - one parameter per query parameter the endpoint takes
405        self,
406        project_name: str,
407        page_title: str,
408        search: str | None = None,
409        *,
410        match_any: bool = False,
411        per_page: int | None = None,
412        next_id: str | None = None,
413    ) -> Links2hopResponse:
414        """Get one page of the 2-hop neighbourhood of a page.
415
416        The direct 1-hop neighbours are not included. Use `iter_links_2hop` to walk a
417        neighbourhood larger than one page.
418
419        Args:
420            project_name: The name of the project.
421            page_title: The title of the page.
422            search: Keep only the neighbours whose body matches this query.
423            match_any: Match pages containing any of the words in `search` instead of
424                all of them.
425            per_page: Number of neighbours per page (default: the API's own, 1000).
426                Must be between 1 and `MAX_PAGE_SIZE`.
427            next_id: Continue after this entry, as reported by `pagination.next_id`
428                of the previous page.
429
430        Returns:
431            Links2hopResponse: The neighbouring pages.
432
433        Raises:
434            ValueError: If `per_page` is outside 1 to `MAX_PAGE_SIZE`.
435        """
436        encoded_title = quote(page_title, safe="")
437        return Links2hopResponse.model_validate(
438            self._get_json(
439                f"/pages/v2/{project_name}/{encoded_title}/links2hop",
440                self._related_params(search, match_any=match_any, per_page=per_page, next_id=next_id),
441            )
442        )
443
444    def iter_links_1hop(
445        self,
446        project_name: str,
447        page_title: str,
448        search: str | None = None,
449        *,
450        match_any: bool = False,
451        per_page: int | None = None,
452    ) -> Iterator[LinkPage]:
453        """Iterate over the whole 1-hop neighbourhood of a page.
454
455        A single response holds at most 1000 neighbours, so a larger neighbourhood is
456        walked with the cursor the API reports. Pages are fetched as they are consumed.
457
458        Args:
459            project_name: The name of the project.
460            page_title: The title of the page.
461            search: Keep only the neighbours whose body matches this query.
462            match_any: Match pages containing any of the words in `search` instead of
463                all of them.
464            per_page: Number of neighbours fetched per request (default: the API's
465                own, 1000). Must be between 1 and `MAX_PAGE_SIZE`.
466
467        Returns:
468            An iterator over each neighbouring page, in the order the API returns
469            them.
470
471        Raises:
472            ValueError: If `per_page` is outside 1 to `MAX_PAGE_SIZE`.
473        """
474        if per_page is not None:
475            check_page_size(per_page, "per_page")
476        return self._iter_links(
477            lambda next_id: self.get_links_1hop(
478                project_name, page_title, search, match_any=match_any, per_page=per_page, next_id=next_id
479            ),
480            lambda response: response.links1hop,
481        )
482
483    def iter_links_2hop(
484        self,
485        project_name: str,
486        page_title: str,
487        search: str | None = None,
488        *,
489        match_any: bool = False,
490        per_page: int | None = None,
491    ) -> Iterator[LinkPage]:
492        """Iterate over the whole 2-hop neighbourhood of a page.
493
494        The direct 1-hop neighbours are not included.
495
496        Args:
497            project_name: The name of the project.
498            page_title: The title of the page.
499            search: Keep only the neighbours whose body matches this query.
500            match_any: Match pages containing any of the words in `search` instead of
501                all of them.
502            per_page: Number of neighbours fetched per request (default: the API's
503                own, 1000). Must be between 1 and `MAX_PAGE_SIZE`.
504
505        Returns:
506            An iterator over each neighbouring page, in the order the API returns
507            them.
508
509        Raises:
510            ValueError: If `per_page` is outside 1 to `MAX_PAGE_SIZE`.
511        """
512        if per_page is not None:
513            check_page_size(per_page, "per_page")
514        return self._iter_links(
515            lambda next_id: self.get_links_2hop(
516                project_name, page_title, search, match_any=match_any, per_page=per_page, next_id=next_id
517            ),
518            lambda response: response.links2hop,
519        )
520
521    @staticmethod
522    def _iter_links[T: Links1hopResponse | Links2hopResponse](
523        fetch: Callable[[str | None], T],
524        entries: Callable[[T], list[LinkPage]],
525    ) -> Iterator[LinkPage]:
526        """Walk a related pages endpoint until its cursor runs out.
527
528        A page narrowed by `search` can come back with fewer entries than asked for,
529        or none at all, while the cursor still points further on: the filter applies
530        within a page rather than to the whole neighbourhood. Only `has_next` decides
531        whether to stop.
532
533        Args:
534            fetch: Fetches one page, given the cursor to continue from.
535            entries: Reads the neighbours out of a fetched page.
536
537        Yields:
538            LinkPage: Each neighbouring page.
539        """
540        next_id: str | None = None
541        while True:
542            response = fetch(next_id)
543            yield from entries(response)
544            pagination = response.pagination
545            if pagination is None or not pagination.has_next or pagination.next_id is None:
546                return
547            if pagination.next_id == next_id:
548                # The cursor has stopped advancing; continuing would loop forever.
549                return
550            next_id = pagination.next_id
551
552    @staticmethod
553    def _related_params(
554        search: str | None,
555        *,
556        match_any: bool,
557        per_page: int | None = None,
558        next_id: str | None = None,
559    ) -> dict[str, Any]:
560        """Build the query parameters shared by the related pages endpoints.
561
562        Args:
563            search: Full-text query to filter the neighbours with.
564            match_any: Whether to match any word instead of all of them.
565            per_page: Number of neighbours per page.
566            next_id: Cursor to continue from.
567
568        Returns:
569            The query parameters to send.
570
571        Raises:
572            ValueError: If `per_page` is outside 1 to `MAX_PAGE_SIZE`.
573        """
574        params: dict[str, Any] = {}
575        if search is not None:
576            params["search"] = search
577        if match_any:
578            params["op"] = "or"
579        if per_page is not None:
580            params["perPage"] = check_page_size(per_page, "per_page")
581        if next_id is not None:
582            params["nextId"] = next_id
583        return params
584
585    def search_pages(
586        self,
587        project_name: str,
588        query: str,
589        *,
590        match_any: bool = False,
591        sort: SearchSort | None = None,
592    ) -> SearchResponse:
593        """Search the full text of the pages in a project.
594
595        Args:
596            project_name: The name of the project.
597            query: The search query.
598            match_any: Match pages containing any of the words instead of all of them.
599            sort: Order of the results (default: the API's own, `pageRank`).
600
601        Returns:
602            SearchResponse: The matching pages.
603        """
604        params: dict[str, Any] = {"q": query}
605        if match_any:
606            params["op"] = "or"
607        if sort is not None:
608            params["sort"] = sort
609        return SearchResponse.model_validate(self._get_json(f"/pages/{project_name}/search/query", params))
610
611    def search_titles_by_vector(self, project_name: str, query: str) -> VectorSearchResponse:
612        """Search pages by vector similarity.
613
614        Only page titles and the link notations in page bodies are searched; ordinary
615        body text is not.
616
617        Args:
618            project_name: The name of the project.
619            query: The search query.
620
621        Returns:
622            VectorSearchResponse: The matching pages, most similar first.
623
624        Raises:
625            SearchServerUpdatingError: If the search backend is temporarily updating.
626                Retrying later usually succeeds.
627        """
628        return VectorSearchResponse.model_validate(
629            self._get_json(f"/pages/{project_name}/search/vector/titles", {"q": query})
630        )
631
632    def get_commits(self, project_name: str, page_id: str, since: str | None = None) -> CommitsResponse:
633        """Get the edit history of a page.
634
635        The history is keyed by page id rather than title, so it can be followed
636        across renames.
637
638        Args:
639            project_name: The name of the project.
640            page_id: The immutable id of the page.
641            since: Return only the commits after this commit id. Omit for the whole
642                history.
643
644        Returns:
645            CommitsResponse: The commits, oldest first.
646        """
647        params = {"head": since} if since is not None else None
648        return CommitsResponse.model_validate(self._get_json(f"/commits/{project_name}/{page_id}", params))
649
650    def get_project_users(self, project_name: str) -> ProjectUsersResponse:
651        """Get the members of a project.
652
653        Args:
654            project_name: The name of the project.
655
656        Returns:
657            ProjectUsersResponse: Current members, departed members and service accounts.
658        """
659        return ProjectUsersResponse.model_validate(self._get_json(f"/projects/{project_name}/users"))
660
661    def get_projects(self) -> ProjectsResponse:
662        """Get the projects the authenticated user belongs to.
663
664        Requires authentication.
665
666        Returns:
667            ProjectsResponse: The projects.
668        """
669        return ProjectsResponse.model_validate(self._get_json("/projects"))
670
671    def get_project(self, project_name: str) -> ProjectDetail:
672        """Get a single project by name.
673
674        Unlike `get_projects`, this needs no authentication for a public project, and
675        carries the project's settings and member list rather than the counters.
676
677        A service account is refused here with HTTP 401, even for the project it
678        belongs to, though `get_project_users` on that same project works.
679
680        Args:
681            project_name: The name of the project.
682
683        Returns:
684            ProjectDetail: The project.
685        """
686        return ProjectDetail.model_validate(self._get_json(f"/projects/{project_name}"))
687
688    def get_me(self) -> Me:
689        """Get the authenticated user.
690
691        Requires authentication. The `name` shown here, not `display_name`, is what
692        `get_pages(filter_value=...)` expects.
693
694        Returns:
695            Me: The authenticated user.
696
697        Raises:
698            NotAuthenticatedError: If no credential was accepted. This endpoint does
699                not answer 401: without one it answers 200 with `{"isGuest": true}`,
700                which carries no user to return.
701        """
702        payload = self._get_json("/users/me")
703        if "id" not in payload:
704            raise NotAuthenticatedError
705        return Me.model_validate(payload)
706
707    def get_file_info(self, file_id: str) -> FileInfo:
708        """Get the metadata of a file uploaded to a project.
709
710        Args:
711            file_id: The file id, optionally with an extension, or the full file URL.
712
713        Returns:
714            FileInfo: The metadata, including any text extracted from the file.
715        """
716        return FileInfo.model_validate(self._get_json(f"/gcs/{bare_file_id(file_id)}/info"))
717
718    def preview_page_edit(
719        self,
720        project_name: str,
721        changes: Sequence[PageChange],
722        page_id: str | None = None,
723    ) -> EditPreviewResponse:
724        """Dry-run an edit and get a preview id for it.
725
726        Nothing is written until the returned preview id is passed to
727        `submit_page_edit`, and the preview expires a few minutes after it is issued.
728        Use `scrapbox.edits.changes_from_ops` to build `changes`.
729
730        Args:
731            project_name: The name of the project.
732            changes: The changes to apply, in order.
733            page_id: The id of the page to edit. Omit to create a new page.
734
735        Returns:
736            EditPreviewResponse: The preview id and the resulting page.
737
738        Raises:
739            PersonalAccessTokenRequiredError: If neither a personal access token nor a
740                service account access key is set.
741        """
742        payload: dict[str, Any] = {
743            "changes": [
744                change if isinstance(change, dict) else change.model_dump(by_alias=True, exclude_none=True)
745                for change in changes
746            ]
747        }
748        if page_id is not None:
749            payload["pageId"] = page_id
750        return EditPreviewResponse.model_validate(
751            self._post_json(f"/pages/v2/{project_name}/page-edit-for-ai/preview", payload)
752        )
753
754    def submit_page_edit(self, project_name: str, preview_id: str) -> EditSubmitResponse:
755        """Commit an edit that was previewed earlier.
756
757        A preview id can only be submitted once, and the project must be the one the
758        preview was created for.
759
760        Args:
761            project_name: The name of the project.
762            preview_id: The preview id returned by `preview_page_edit`.
763
764        Returns:
765            EditSubmitResponse: The created commit and the page written to.
766
767        Raises:
768            PersonalAccessTokenRequiredError: If neither a personal access token nor a
769                service account access key is set.
770        """
771        return EditSubmitResponse.model_validate(
772            self._post_json(f"/pages/v2/{project_name}/page-edit-for-ai/submit", {"previewId": preview_id})
773        )
774
775    def get_page_text(self, project_name: str, page_title: str) -> str:
776        """Get the text content of a page.
777
778        Args:
779            project_name: The name of the project.
780            page_title: The title of the page.
781
782        Returns:
783            str: The text content of the page.
784        """
785        encoded_title = quote(page_title, safe="")
786        return self._get(f"/pages/{project_name}/{encoded_title}/text").text
787
788    def get_page_icon_url(self, project_name: str, page_title: str) -> str:
789        """Get the icon image URL for a page.
790
791        This method returns the redirect destination URL of the page icon.
792
793        Args:
794            project_name: The name of the project.
795            page_title: The title of the page.
796
797        Returns:
798            str: The URL of the icon image.
799        """
800        encoded_title = quote(page_title, safe="")
801        url = f"{self.BASE_URL}/pages/{project_name}/{encoded_title}/icon"
802
803        response = self.client.get(url, follow_redirects=False)
804
805        if response.status_code == httpx.codes.FOUND:
806            return response.headers.get("location", "")
807        if response.status_code == httpx.codes.OK:
808            return url
809        response.raise_for_status()
810        return url
811
812    def get_file(self, file_id: str, *, thumbnail: bool = False) -> bytes:
813        """Get a file uploaded to Scrapbox.
814
815        Args:
816            file_id: The file ID (e.g., "1a2b3c4d5e6f7g8h9i0j.JPG")
817                or full URL (e.g., "https://scrapbox.io/files/1a2b3c4d5e6f7g8h9i0j.JPG"
818                or "https://gyazo.com/1a2b3c4d5e6f7g8h9i0j1a2b3c4d5e6f").
819            thumbnail: Fetch the scaled down version. Files that have no thumbnail
820                (anything but JPEG and PNG) come back at full size. Ignored for Gyazo
821                URLs, which are resolved through oEmbed instead.
822
823        Returns:
824            bytes: The binary data of the file.
825        """
826        url = file_id if file_id.startswith(("http://", "https://")) else f"https://scrapbox.io/files/{file_id}"
827
828        parsed_url = urlparse(url)
829        is_gyazo = "gyazo.com" in (parsed_url.hostname or "")
830        params = {"type": "thumbnail"} if thumbnail and not is_gyazo else None
831        if is_gyazo:
832            # If URL already has a file extension (e.g., .mp4, .jpg), directly convert to i.gyazo.com
833            path = parsed_url.path.strip("/")
834            if "." in path.split("/")[-1]:  # Check if last path segment has extension
835                url = f"https://i.gyazo.com/{path}"
836            else:
837                # Use oEmbed API to get the actual file URL
838                json = self._get_json("/oembed-proxy/gyazo", {"url": url})
839                if (oembed_type := json.get("type")) not in ("photo", "video"):
840                    msg = f"Unsupported Gyazo oEmbed type: {oembed_type}"
841                    raise ValueError(msg)
842                oembed_data = GyazoOEmbedResponse.model_validate(json)
843                if isinstance(oembed_data.root, GyazoOEmbedResponsePhoto):
844                    url = oembed_data.root.url
845                else:  # video
846                    # Extract Gyazo ID from the original URL and construct direct video URL
847                    gyazo_id = parsed_url.path.strip("/")
848                    url = f"https://i.gyazo.com/{gyazo_id}.mp4"
849        response = self.client.get(url, params=params)
850        response.raise_for_status()
851
852        return response.content