From 2100e789b0ba227301faf59428c9b6bb49fe8f3c Mon Sep 17 00:00:00 2001 From: takker99 <37929109+takker99@users.noreply.github.com> Date: Tue, 15 Apr 2025 15:03:39 +0900 Subject: [PATCH] docs: Mark APIs in `/unstable-api` as experimental and unstable --- api/pages/project.ts | 17 +++++++++++++++-- api/pages/project/replace/links.ts | 4 ++++ api/pages/project/search/query.ts | 4 ++++ api/pages/project/search/titles.ts | 12 +++++++++++- api/pages/project/title.ts | 10 +++++++++- api/pages/project/title/icon.ts | 10 +++++++++- api/pages/project/title/text.ts | 10 +++++++++- api/projects/project.ts | 4 ++++ api/users/me.ts | 4 ++++ 9 files changed, 69 insertions(+), 6 deletions(-) diff --git a/api/pages/project.ts b/api/pages/project.ts index 1f9604b..55af0b2 100644 --- a/api/pages/project.ts +++ b/api/pages/project.ts @@ -21,7 +21,10 @@ import { pooledMap } from "@std/async/pool"; import { range } from "@core/iterutil/range"; import { flatten } from "@core/iterutil/async/flatten"; -/** Options for {@linkcode get} */ +/** Options for {@linkcode get} + * + * @experimental **UNSTABLE**: New API, yet to be vetted. + */ export interface ListPagesOption extends BaseOptions { /** the sort of page list to return @@ -57,6 +60,8 @@ export interface ListPagesOption } /** Constructs a request for the `/api/pages/:project` endpoint + * + * @experimental **UNSTABLE**: New API, yet to be vetted. * * @param project The project name to list pages from * @param options - Additional configuration options (sorting, pagination, etc.) @@ -85,6 +90,8 @@ export const makeGetRequest = ( }; /** Lists pages from a specified project + * + * @experimental **UNSTABLE**: New API, yet to be vetted. * * @param project The project name to list pages from * @param options Configuration options for pagination and sorting @@ -117,7 +124,11 @@ export const get = ( }, R> >; -/** Options for {@linkcode list} */ +/** + * Options for {@linkcode list} + * + * @experimental **UNSTABLE**: New API, yet to be vetted. + */ export interface ListPagesStreamOption extends ListPagesOption { /** The number of requests to make concurrently @@ -130,6 +141,8 @@ export interface ListPagesStreamOption /** * Lists pages from a given `project` with pagination * + * @experimental **UNSTABLE**: New API, yet to be vetted. + * * @param project The project name to list pages from * @param options Configuration options for pagination and sorting * @throws {HTTPError | TypedError<"NotLoggedInError" | "NotMemberError" | "NotFoundError">} If any requests in the pagination sequence fail diff --git a/api/pages/project/replace/links.ts b/api/pages/project/replace/links.ts index 4051f57..9503f23 100644 --- a/api/pages/project/replace/links.ts +++ b/api/pages/project/replace/links.ts @@ -9,6 +9,8 @@ import { cookie } from "../../../../rest/auth.ts"; import { get } from "../../../users/me.ts"; /** Constructs a request for the `/api/pages/:project/replace/links` endpoint + * + * @experimental **UNSTABLE**: New API, yet to be vetted. * * @param project - The project name where all links will be replaced * @param from - The original link text to be replaced @@ -39,6 +41,8 @@ export const makePostRequest = ( }; /** Retrieves JSON data for a specified page + * + * @experimental **UNSTABLE**: New API, yet to be vetted. * * @param project - The project name where all links will be replaced * @param from - The original link text to be replaced diff --git a/api/pages/project/search/query.ts b/api/pages/project/search/query.ts index aa3fd82..2ca88e2 100644 --- a/api/pages/project/search/query.ts +++ b/api/pages/project/search/query.ts @@ -9,6 +9,8 @@ import { type BaseOptions, setDefaults } from "../../../../util.ts"; import { cookie } from "../../../../rest/auth.ts"; /** Constructs a request for the `/api/pages/:project/search/query` endpoint + * + * @experimental **UNSTABLE**: New API, yet to be vetted. * * @param project The name of the project to search within * @param query The search query string to match against pages @@ -31,6 +33,8 @@ export const makeGetRequest = ( }; /** Search for pages within a specific project + * + * @experimental **UNSTABLE**: New API, yet to be vetted. * * @param project The name of the project to search within * @param query The search query string to match against pages diff --git a/api/pages/project/search/titles.ts b/api/pages/project/search/titles.ts index b767e55..c3cd1bf 100644 --- a/api/pages/project/search/titles.ts +++ b/api/pages/project/search/titles.ts @@ -14,7 +14,11 @@ import { type TypedError, } from "../../../../error.ts"; -/** Options for {@linkcode get} */ +/** + * Options for {@linkcode get} + * + * @experimental **UNSTABLE**: New API, yet to be vetted. + */ export interface GetLinksOptions extends BaseOptions { /** ID indicating the next list of links */ @@ -22,6 +26,8 @@ export interface GetLinksOptions } /** Create a request to `GET /api/pages/:project/search/titles` + * + * @experimental **UNSTABLE**: New API, yet to be vetted. * * @param project The project to get the links from * @param options - Additional configuration options @@ -42,6 +48,8 @@ export const makeGetRequest = ( }; /** Retrieve link data from a specified Scrapbox project + * + * @experimental **UNSTABLE**: New API, yet to be vetted. * * This function fetches link data from a project, supporting pagination through * the {@linkcode GetLinksOptions.followingId} parameter. It returns both the link data and the next @@ -76,6 +84,8 @@ export const get = ( >; /** Retrieve all link data from a specified project one by one + * + * @experimental **UNSTABLE**: New API, yet to be vetted. * * @param project The project name to list pages from * @param options Additional configuration options for the request diff --git a/api/pages/project/title.ts b/api/pages/project/title.ts index 87af2ff..9390cbb 100644 --- a/api/pages/project/title.ts +++ b/api/pages/project/title.ts @@ -9,7 +9,11 @@ import { type BaseOptions, setDefaults } from "../../../util.ts"; import { encodeTitleURI } from "../../../title.ts"; import { cookie } from "../../../rest/auth.ts"; -/** Options for {@linkcode getPage} */ +/** + * Options for {@linkcode getPage} + * + * @experimental **UNSTABLE**: New API, yet to be vetted. + */ export interface GetPageOption extends BaseOptions { /** use `followRename` */ @@ -20,6 +24,8 @@ export interface GetPageOption } /** Constructs a request for the `/api/pages/:project/:title` endpoint + * + * @experimental **UNSTABLE**: New API, yet to be vetted. * * @param project The project name containing the desired page * @param title The page title to retrieve (case insensitive) @@ -45,6 +51,8 @@ export const makeGetRequest = ( }; /** Retrieves JSON data for a specified page + * + * @experimental **UNSTABLE**: New API, yet to be vetted. * * @param project The project name containing the desired page * @param title The page title to retrieve (case insensitive) diff --git a/api/pages/project/title/icon.ts b/api/pages/project/title/icon.ts index 9e6ac36..00cab99 100644 --- a/api/pages/project/title/icon.ts +++ b/api/pages/project/title/icon.ts @@ -8,7 +8,11 @@ import { type BaseOptions, setDefaults } from "../../../../util.ts"; import { encodeTitleURI } from "../../../../title.ts"; import { cookie } from "../../../../rest/auth.ts"; -/** Options for {@linkcode get} */ +/** + * Options for {@linkcode get} + * + * @experimental **UNSTABLE**: New API, yet to be vetted. + */ export interface GetIconOption extends BaseOptions { /** use `followRename` */ @@ -16,6 +20,8 @@ export interface GetIconOption } /** Constructs a request for the `/api/pages/:project/:title/icon` endpoint + * + * @experimental **UNSTABLE**: New API, yet to be vetted. * * @param project The project name containing the desired page * @param title The page title to retrieve (case insensitive) @@ -38,6 +44,8 @@ export const makeGetRequest = ( }; /** Retrieves a specified page image + * + * @experimental **UNSTABLE**: New API, yet to be vetted. * * @param project The project name containing the desired page * @param title The page title to retrieve (case insensitive) diff --git a/api/pages/project/title/text.ts b/api/pages/project/title/text.ts index 10cd245..9235472 100644 --- a/api/pages/project/title/text.ts +++ b/api/pages/project/title/text.ts @@ -8,7 +8,11 @@ import { type BaseOptions, setDefaults } from "../../../../util.ts"; import { encodeTitleURI } from "../../../../title.ts"; import { cookie } from "../../../../rest/auth.ts"; -/** Options for {@linkcode get} */ +/** + * Options for {@linkcode get} + * + * @experimental **UNSTABLE**: New API, yet to be vetted. + */ export interface GetTextOption extends BaseOptions { /** use `followRename` */ @@ -16,6 +20,8 @@ export interface GetTextOption } /** Constructs a request for the `/api/pages/:project/:title/text` endpoint + * + * @experimental **UNSTABLE**: New API, yet to be vetted. * * @param project The project name containing the desired page * @param title The page title to retrieve (case insensitive) @@ -38,6 +44,8 @@ export const makeGetRequest = ( }; /** Retrieves a specified page text + * + * @experimental **UNSTABLE**: New API, yet to be vetted. * * @param project The project name containing the desired page * @param title The page title to retrieve (case insensitive) diff --git a/api/projects/project.ts b/api/projects/project.ts index e036961..90865e4 100644 --- a/api/projects/project.ts +++ b/api/projects/project.ts @@ -10,6 +10,8 @@ import { type BaseOptions, setDefaults } from "../../util.ts"; import { cookie } from "../../rest/auth.ts"; /** Create a request to `GET /api/projects/:project` + * + * @experimental **UNSTABLE**: New API, yet to be vetted. * * @param project - Project name to retrieve information for * @param options - Additional configuration options @@ -33,6 +35,8 @@ export const makeGetRequest = ( * access level, settings, and metadata. The returned data type depends on * whether the user has member access to the project. * + * @experimental **UNSTABLE**: New API, yet to be vetted. + * * @param project - Project name to retrieve information for * @param options Additional configuration options for the request * @returns A {@linkcode Response} object containing the project data diff --git a/api/users/me.ts b/api/users/me.ts index 158167c..8fb5616 100644 --- a/api/users/me.ts +++ b/api/users/me.ts @@ -8,6 +8,8 @@ import { cookie } from "../../rest/auth.ts"; * This endpoint retrieves the current user's profile information, * which can be either a {@linkcode MemberUser} or {@linkcode GuestUser} profile. * + * @experimental **UNSTABLE**: New API, yet to be vetted. + * * @param init - Options including `connect.sid` (session ID) and other configuration * @returns A {@linkcode Request} object for fetching user profile data */ @@ -22,6 +24,8 @@ export const makeGetRequest = ( }; /** get the user profile + * + * @experimental **UNSTABLE**: New API, yet to be vetted. * * @param init - Options including `connect.sid` (session ID) and other configuration * @returns A {@linkcode Response} object containing the user profile data