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)

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