Merge pull request #233 from takker99:experimental-tag

docs: Mark APIs in `/unstable-api` as experimental and unstable

Author: takker99

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<R extends Response | undefined>
   extends BaseOptions<R> {
   /** the sort of page list to return
@@ -57,6 +60,8 @@ export interface ListPagesOption<R extends Response | undefined>
 }
 
 /** 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 = <R extends Response | undefined>(
 };
 
 /** 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 extends Response | undefined = Response>(
     }, R>
   >;
 
-/** Options for {@linkcode list} */
+/**
+ * Options for {@linkcode list}
+ *
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
+ */
 export interface ListPagesStreamOption<R extends Response | undefined>
   extends ListPagesOption<R> {
   /** The number of requests to make concurrently
@@ -130,6 +141,8 @@ export interface ListPagesStreamOption<R extends Response | undefined>
 /**
  * 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

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 = <R extends Response | undefined>(
 };
 
 /** 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

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 = <R extends Response | undefined>(
 };
 
 /** 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

api/pages/project/search/titles.ts

@@ -14,14 +14,20 @@ 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<R extends Response | undefined>
   extends BaseOptions<R> {
   /** ID indicating the next list of links */
   followingId?: string;
 }
 
 /** 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 = <R extends Response | undefined>(
 };
 
 /** 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 = <R extends Response | undefined = Response>(
   >;
 
 /** 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

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<R extends Response | undefined>
   extends BaseOptions<R> {
   /** use `followRename` */
@@ -20,6 +24,8 @@ export interface GetPageOption<R extends Response | undefined>
 }
 
 /** 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 = <R extends Response | undefined>(
 };
 
 /** 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)

api/pages/project/title/icon.ts

@@ -8,14 +8,20 @@ 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<R extends Response | undefined>
   extends BaseOptions<R> {
   /** use `followRename` */
   followRename?: boolean;
 }
 
 /** 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 = <R extends Response | undefined>(
 };
 
 /** 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)

api/pages/project/title/text.ts

@@ -8,14 +8,20 @@ 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<R extends Response | undefined>
   extends BaseOptions<R> {
   /** use `followRename` */
   followRename?: boolean;
 }
 
 /** 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 = <R extends Response | undefined>(
 };
 
 /** 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)

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 = <R extends Response | undefined>(
  * 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

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 = <R extends Response | undefined>(
 };
 
 /** 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