API

Waline 官方提供 @waline/api 包，以供官方客户端、第三方客户端开发者和用户调用 Waline 后端接口。

API

//#region src/utils.d.ts
interface BaseAPIOptions {
  /**
   * Waline 服务端地址
   *
   * Waline serverURL
   */
  serverURL: string;
  /**
   * 错误信息所使用的语言
   *
   * Language used in error text
   */
  lang: string;
}
interface ErrorStatusResponse {
  /**
   * 错误代码
   *
   * Error number
   */
  errno: number;
  /**
   * 错误消息
   *
   * Error msg
   */
  errmsg: string;
}
//#endregion
//#region src/articleCounter.d.ts
export interface GetArticleCounterOptions extends BaseAPIOptions {
  /**
   * 待获取计数器的 path
   *
   * Path of counters
   */
  paths: string[];
  /**
   * 待获取计数器的类型
   *
   * Counter type to be fetched
   */
  type: string[];
  /**
   * 取消请求的信号
   *
   * AbortSignal to cancel request
   */
  signal?: AbortSignal;
}
export interface CounterFields {
  time?: number;
  reaction0?: number;
  reaction1?: number;
  reaction2?: number;
  reaction3?: number;
  reaction4?: number;
  reaction5?: number;
  reaction6?: number;
  reaction7?: number;
  reaction8?: number;
}
export type GetArticleCounterResponseItem = Record<string, number> & CounterFields;
export type GetArticleCounterResponse = GetArticleCounterResponseItem[];
export declare const getArticleCounter: ({ serverURL, lang, paths, type, signal }: GetArticleCounterOptions) => Promise<GetArticleCounterResponse>;
export interface UpdateArticleCounterOptions extends BaseAPIOptions {
  /**
   * 待更新计数器的 path
   *
   * Path of counter to be updated
   */
  path: string;
  /**
   * 待更新计数器的类型
   *
   * Counter type to be updated
   */
  type: string;
  /**
   * 更新操作
   *
   * Update operation
   *
   * @default 'inc'
   */
  action?: 'inc' | 'desc';
}
export declare const updateArticleCounter: ({ serverURL, lang, path, type, action }: UpdateArticleCounterOptions) => Promise<GetArticleCounterResponse>;
//#endregion
//#region src/typings.d.ts
type WalineCommentStatus = 'approved' | 'waiting' | 'spam';
type WalineUserType = 'administrator' | 'guest';
interface WalineCommentData {
  /** User Nickname */
  nick: string;
  /** User email */
  mail?: string;
  /** User link */
  link?: string;
  /** Content of comment */
  comment: string;
  /** User Agent */
  ua: string;
  /** Comment page path */
  url: string;
  /**
   * Parent comment id
   *
   * Only available when replying comment
   */
  pid?: number;
  /**
   * Root comment id
   *
   * Only available when replying comment
   */
  rid?: number;
  /**
   * User id being at
   *
   * Only available when replying comment
   */
  at?: string;
  /** Recaptcha Token */
  recaptchaV3?: string;
  /** Turnstile Token */
  turnstile?: string;
}
interface BaseWalineResponseComment {
  /** Comment object ID */
  objectId: number;
  /** Timestamp of the comment */
  time: number;
  /** Content of comment */
  comment: string;
  /**
   * Original comment content
   *
   * 原始评论内容
   */
  orig: string;
  /**
   * Comment like number
   *
   * 评论喜欢数
   */
  like: number;
  /** User Nickname */
  nick: string;
  /** User link */
  link: string;
  /** User avatar */
  avatar: string;
  /**
   * User type
   *
   * Only available with logged in user 用户类型
   *
   * 仅在登录用户时可用
   */
  type?: WalineUserType;
  /**
   * User ID
   *
   * Only available with logged in user 用户 ID
   *
   * 仅在登录用户时可用
   */
  user_id?: number;
  /**
   * User location
   *
   * Not available with `DISABLE_REGION=true` 用户位置
   *
   * `DISABLE_REGION=true` 时不可用
   */
  addr?: string;
  /**
   * User browser
   *
   * Not available with `DISABLE_USERAGENT=true` 用户浏览器
   *
   * `DISABLE_USERAGENT=true` 时不可用
   */
  browser?: string;
  /**
   * User location
   *
   * Not available with `DISABLE_USERAGENT=true` 用户位置
   *
   * `DISABLE_USERAGENT=true` 时不可用
   */
  os?: string;
  /**
   * User level
   *
   * Only available when `LEVELS` is set 用户等级
   *
   * 仅在 `LEVELS` 设置时可用
   */
  level?: number;
  /**
   * User label
   *
   * 用户标签
   */
  label?: string;
  /**
   * Comment status
   *
   * For administrators, `approved` `spam` `waiting` can be get, for others, the only value is
   * `approved` 评论状态
   *
   * 管理员可获得 `approved`、`spam` 和 `waiting`，其他用户只能获得 `approved`
   */
  status?: WalineCommentStatus;
}
interface WalineChildComment extends BaseWalineResponseComment {
  /** Parent comment id */
  pid: number;
  /** Root comment id */
  rid: number;
  /** User id being at */
  at?: string;
  /** Reply user information */
  reply_user?: {
    nick: string;
    link: string;
    avatar: string;
  };
}
interface WalineRootComment extends BaseWalineResponseComment {
  /**
   * Whether the comment is sticky
   *
   * 是否置顶
   */
  sticky: boolean;
  /**
   * Child comments
   *
   * 子评论
   */
  children: WalineChildComment[];
}
type WalineComment = WalineRootComment | WalineChildComment;
//#endregion
//#region src/comment.d.ts
export interface GetCommentOptions extends BaseAPIOptions {
  /**
   * 待获取评论列表的 path
   *
   * Path of comment list
   */
  path: string;
  /**
   * 评论分页数
   *
   * Comment pagination number
   */
  page: number;
  /**
   * 每页评论个数
   *
   * Comment number per page
   */
  pageSize: number;
  /**
   * 排序方式
   *
   * Sort method
   */
  sortBy: string;
  /**
   * 用户令牌
   *
   * User token
   */
  token?: string;
  /**
   * 取消请求的信号
   *
   * AbortSignal to cancel request
   */
  signal?: AbortSignal;
}
export interface GetCommentResponse {
  /**
   * 评论数量
   *
   * Comment number
   */
  count: number;
  /**
   * 评论分页数
   *
   * Comment pagination number
   */
  page: number;
  /**
   * 每页评论个数
   *
   * Comment number per page
   */
  pageSize: number;
  /**
   * 评论数据
   *
   * Comment Data
   */
  data: WalineRootComment[];
  /**
   * 页面总数
   *
   * Page number
   */
  totalPages: number;
}
export declare const getComment: ({ serverURL, lang, path, page, pageSize, sortBy, signal, token }: GetCommentOptions) => Promise<GetCommentResponse>;
export interface AddCommentOptions extends BaseAPIOptions {
  /**
   * 用户令牌
   *
   * User token
   */
  token?: string;
  /**
   * 用户待提交的评论数据
   *
   * Comment data being submitted by user
   */
  comment: WalineCommentData;
}
export interface AddCommentResponse extends ErrorStatusResponse {
  /**
   * 渲染好的评论数据
   *
   * Comment data rendered
   */
  data?: WalineComment;
}
export declare const addComment: ({ serverURL, lang, token, comment }: AddCommentOptions) => Promise<AddCommentResponse>;
export interface DeleteCommentOptions extends BaseAPIOptions {
  /**
   * Auth token
   *
   * 认证令牌
   */
  token: string;
  /**
   * Comment objectId to be deleted
   *
   * 待删除的评论对象 ID
   */
  objectId: number;
}
export interface DeleteCommentResponse extends ErrorStatusResponse {
  data: '';
}
export declare const deleteComment: ({ serverURL, lang, token, objectId }: DeleteCommentOptions) => Promise<DeleteCommentResponse>;
interface UpdateWalineCommentData extends Partial<WalineCommentData> {
  /**
   * 点赞还是取消点赞
   *
   * Like or dislike
   */
  like?: boolean;
  /**
   * 评论的状态
   *
   * Comment status
   */
  status?: 'approved' | 'waiting' | 'spam';
  /**
   * 评论指定状态
   *
   * Comment sticky status
   *
   * 0 means not sticky and 1 means sticky
   */
  sticky?: 0 | 1;
}
export interface UpdateCommentOptions extends BaseAPIOptions {
  /**
   * 用户令牌
   *
   * User token
   */
  token: string;
  /**
   * 评论的 ID
   *
   * Comment ID
   */
  objectId: number;
  /**
   * 评论数据
   *
   * Comment data
   */
  comment?: UpdateWalineCommentData;
}
export interface UpdateCommentResponse extends ErrorStatusResponse {
  /**
   * 更新后的评论数据
   *
   * Comment data rendered
   */
  data: WalineComment;
}
export declare const updateComment: ({ serverURL, lang, token, objectId, comment }: UpdateCommentOptions) => Promise<UpdateCommentResponse>;
//#endregion
//#region src/commentCount.d.ts
export interface GetCommentCountOptions extends BaseAPIOptions {
  /**
   * 待获取评论数的 path
   *
   * Path of pages to be fetched
   */
  paths: string[];
  /**
   * 取消请求的信号
   *
   * AbortSignal to cancel request
   */
  signal?: AbortSignal;
}
export declare const fetchCommentCount: ({ serverURL, lang, paths, signal }: GetCommentCountOptions) => Promise<number[]>;
//#endregion
//#region src/login.d.ts
export interface UserInfo {
  /**
   * 显示姓名
   *
   * User name displayed
   */
  display_name: string;
  /**
   * 用户电子邮件地址
   *
   * User email
   */
  email: string;
  /**
   * 用户网站地址
   *
   * User website
   */
  url: string;
  /**
   * 用户令牌
   *
   * User token
   */
  token: string;
  /**
   * 用户头像
   *
   * User avatar
   */
  avatar: string;
  /**
   * 用户对象 ID
   *
   * User object ID
   */
  objectId: number;
  /**
   * 用户身份
   *
   * User role
   */
  type: 'administrator' | 'guest';
}
export declare const login: ({ lang, serverURL }: BaseAPIOptions) => Promise<UserInfo & {
  remember: boolean;
}>;
//#endregion
//#region src/pageview.d.ts
interface GetPageviewOptions extends BaseAPIOptions {
  /**
   * 待获取页面的 path
   *
   * Path of pages
   */
  paths: string[];
  /**
   * 取消请求的信号
   *
   * AbortSignal to cancel request
   */
  signal?: AbortSignal;
}
export declare const getPageview: ({ serverURL, lang, paths, signal }: GetPageviewOptions) => Promise<GetArticleCounterResponse>;
export interface UpdatePageviewOptions extends BaseAPIOptions {
  /**
   * 待更新页面的 path
   *
   * Path of pages
   */
  path: string;
}
export declare const updatePageview: (options: UpdatePageviewOptions) => Promise<GetArticleCounterResponse>;
//#endregion
//#region src/recentComment.d.ts
export interface GetRecentCommentOptions extends BaseAPIOptions {
  /**
   * 获取评论的数量
   *
   * Comment number to be fetched
   */
  count: number;
  /**
   * 取消请求的信号
   *
   * AbortSignal to cancel request
   */
  signal?: AbortSignal;
  /**
   * 用户令牌
   *
   * User token
   */
  token?: string;
}
export interface RecentCommentData extends BaseWalineResponseComment {
  /**
   * Page url where comment locales
   *
   * 评论所在页面地址
   */
  url: string;
}
export declare const getRecentComment: ({ serverURL, lang, count, signal, token }: GetRecentCommentOptions) => Promise<RecentCommentData[]>;
//#endregion
//#region src/user.d.ts
export interface GetUserListOptions extends BaseAPIOptions {
  /**
   * 每页个数
   *
   * Number per page
   */
  pageSize: number;
  /**
   * 取消请求的信号
   *
   * AbortSignal to cancel request
   */
  signal?: AbortSignal;
}
export interface WalineUser extends Pick<WalineComment, 'nick' | 'link' | 'avatar' | 'label' | 'level'> {
  count: number;
}
export interface GetUserListResponse extends ErrorStatusResponse {
  data: WalineUser[];
}
export declare const getUserList: ({ serverURL, signal, pageSize, lang }: GetUserListOptions) => Promise<WalineUser[]>;
//#endregion
export type { BaseWalineResponseComment, WalineChildComment, WalineComment, WalineCommentData, WalineCommentStatus, WalineRootComment, WalineUserType };