kokkoro-plugin-hitokoto 3.0.0 → 3.0.2

package/README.md

@@ -1,27 +1,67 @@
 # kokkoro-plugin-hitokoto
 
-ヒトコト
+Hitokoto 一言，随机获取动漫、小说、诗词等类型的语句。
 
 ## 安装
 
+在 Kokkoro 项目目录运行：
+
 ```shell
 bun add kokkoro-plugin-hitokoto
 ```
 
 ## 指令
 
-发送「/一言」，插件默认会从一言接口随机返回一条动画或漫画语句。
+```text
+/一言 [types]...
+```
+
+`[types]...` 表示可选的类型参数，可以填写一个或多个中文类型名称。多个名称使用空格分隔。支持动画、漫画、游戏、文学、原创、来自网络、其他、影视、诗词、网易云、哲学和抖机灵。
+
+不填写类型时，插件随机返回一条语句。
+
+```text
+/一言
+/一言 动画 漫画 游戏
+```
 
 ## 快捷方式
 
-也可以发送「来点骚话」触发，群聊需要开启「获取群内全部消息」权限。
+快捷方式匹配以下正则表达式：
+
+```regexp
+/^来点(?<types>.+)?骚话$/
+```
+
+其中的 `types` 表示「来点」和「骚话」之间可选的类型名称。以下消息都能触发快捷方式：
+
+```text
+来点骚话
+来点诗词骚话
+```
+
+要让普通群消息触发快捷方式，需要在对应群聊中开启「获取群内全部消息」权限。未开启时，插件只能处理 @ 机器人的群消息。
+
+## API
+
+其他插件可以从 `service` 入口导入 `fetchSentence()` 使用，该函数返回一言接口的完整语句对象：
+
+```typescript
+import { fetchSentence } from 'kokkoro-plugin-hitokoto/service';
+
+const sentence = await fetchSentence('i');
+```
+
+`fetchSentence()` 接收一言接口的类型代码或代码数组。`'i'` 表示诗词，`['a', 'b']` 表示动画和漫画。传入空数组时，函数不限制语句类型。
+
+请求失败时，`fetchSentence()` 会抛出 `Error`。一言错误响应使用上游的 `message`，其他请求错误使用 HTTP 状态码。包同时导出 `Sentence`、`SentenceType` 和 `ErrorResponse` 类型，以及 `isErrorResponse()` 类型守卫。
 
 ## 环境变量
 
-如需修改语句类型，请在项目根目录创建 `.env` 文件，并通过 `HITOKOTO_TYPES` 设置一言接口的 `c` 参数。多个类型使用逗号分隔，默认值为 `a,b`。
+调用 `fetchSentence()` 时省略类型参数，函数会读取环境变量 `HITOKOTO_TYPES`。如需设置该变量，请在项目根目录创建 `.env` 文件。多个类型代码使用逗号分隔。未设置时，函数不限制语句类型。
 
 ```ini
-HITOKOTO_TYPES=c,d
+HITOKOTO_TYPES=a,b,c
 ```
 
-类型取值参阅[一言接口文档](https://developer.hitokoto.cn/sentence/#请求参数)。修改 `.env` 后需要重新启动项目。
+示例中的 `a`、`b` 和 `c` 分别表示动画、漫画和游戏。其他类型代码参阅 [一言接口文档](https://developer.hitokoto.cn/sentence/#请求参数)。修改 `.env` 后需要重新启动项目。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kokkoro-plugin-hitokoto",
-  "version": "3.0.0",
-  "description": "ヒトコト",
+  "version": "3.0.2",
+  "description": "Hitokoto 一言，随机获取动漫、小说、诗词等类型的语句。",
   "keywords": [
     "bot",
     "kokkoro",
@@ -17,12 +17,15 @@
   "license": "MIT",
   "author": "Yuki <admin@yuki.sh>",
   "type": "module",
-  "exports": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./service": "./src/service.ts"
+  },
   "files": [
     "src"
   ],
   "peerDependencies": {
-    "@kokkoro/core": "^3.1.3",
+    "@kokkoro/core": "^3.1.4",
     "typescript": "^6.0.3"
   }
 }

package/src/index.ts

@@ -1,62 +1,25 @@
-import { useCommand } from '@kokkoro/core';
+import { useCommand, useLogger } from '@kokkoro/core';
 
-type SentenceType =
-  | 'a' // 动画
-  | 'b' // 漫画
-  | 'c' // 游戏
-  | 'd' // 文学
-  | 'e' // 原创
-  | 'f' // 来自网络
-  | 'g' // 其他
-  | 'h' // 影视
-  | 'i' // 诗词
-  | 'j' // 网易云
-  | 'k' // 哲学
-  | 'l'; // 抖机灵
+import { fetchSentence, HITOKOTO_API, resolveTypeCodes } from './service';
 
-interface Sentence {
-  /** 一言标识 */
-  readonly id: number;
-  /** 一言正文。编码方式 unicode。使用 utf-8。 */
-  readonly hitokoto: string;
-  /** 类型。请参考第三节参数的表格 */
-  readonly type: SentenceType;
-  /** 一言的出处 */
-  readonly from: string;
-  /** 一言的作者 */
-  readonly from_who: string | null;
-  /** 添加者 */
-  readonly creator: string;
-  /** 添加者用户标识 */
-  readonly creator_uid: number;
-  /** 审核员标识 */
-  readonly reviewer: number;
-  /** 一言唯一标识，可以链接到 https://hitokoto.cn?uuid=[uuid] 查看这个一言的完整信息 */
-  readonly uuid: string;
-  /** 提交方式 */
-  readonly commit_from: string;
-  /** 添加时间 */
-  readonly created_at: string;
-  /** 句子长度 */
-  readonly length: number;
-}
+const logger = useLogger();
 
-const { HITOKOTO_TYPES = 'a,b' } = import.meta.env;
-const HITOKOTO_API = new URL('https://v1.hitokoto.cn');
+export default () => {
+  useCommand('/一言 [types]...', async context => {
+    const payload = { c: resolveTypeCodes(context.args.types) };
 
-for (const type of HITOKOTO_TYPES.split(',')) {
-  HITOKOTO_API.searchParams.append('c', type);
-}
+    logger.debug('发送 Hitokoto 请求', {
+      method: 'GET',
+      url: HITOKOTO_API,
+      payload,
+    });
 
-export default () => {
-  useCommand('/一言', async () => {
-    const response = await fetch(HITOKOTO_API);
+    const sentence = await fetchSentence(payload.c);
+    const { from, hitokoto, id, type } = sentence;
 
-    if (!response.ok) {
-      throw new Error(`接口请求失败，状态码 ${response.status}`);
-    }
-    const { hitokoto, from } = <Sentence>await response.json();
+    logger.debug('收到 Hitokoto 响应', sentence);
+    logger.info('已获取一言', { id, type });
 
     return `『${hitokoto}』——「${from}」`;
-  }).shortcut('来点骚话');
+  }).shortcut(/^来点(?<types>.+)?骚话$/);
 };

package/src/service.ts

@@ -0,0 +1,184 @@
+/** 一言 v1 语句接口的请求地址。 */
+export const HITOKOTO_API = 'https://v1.hitokoto.cn';
+
+/**
+ * 中文句子类型名称与一言接口 `c` 参数值的对应表。
+ *
+ * @see {@link https://developer.hitokoto.cn/sentence/#请求参数 | 一言语句接口请求参数}
+ */
+export const TYPE_CODES = {
+  动画: 'a',
+  漫画: 'b',
+  游戏: 'c',
+  文学: 'd',
+  原创: 'e',
+  来自网络: 'f',
+  其他: 'g',
+  影视: 'h',
+  诗词: 'i',
+  网易云: 'j',
+  哲学: 'k',
+  抖机灵: 'l',
+} as const;
+
+/** {@link TYPE_CODES} 中的全部中文类型名称，以顿号分隔。 */
+export const TYPE_NAMES = Object.keys(TYPE_CODES).join('、');
+
+/** 一言接口 `c` 参数接受的句子类型代码。 */
+export type SentenceType = (typeof TYPE_CODES)[keyof typeof TYPE_CODES];
+
+/**
+ * 将中文句子类型名称转换为一言接口的类型代码。
+ *
+ * @remarks
+ * 返回的代码数组可以直接传给 {@link fetchSentence}。
+ *
+ * @param names - 要转换的类型名称数组。每个元素都必须是 {@link TYPE_CODES} 的键。
+ * @returns 与 `names` 顺序一致的类型代码数组。
+ * @throws `names` 包含不支持的类型名称时抛出 `Error`。
+ *
+ * @example
+ * ```ts
+ * resolveTypeCodes(['动画', '诗词']);
+ * // => ['a', 'i']
+ * ```
+ *
+ * @see {@link https://developer.hitokoto.cn/sentence/#请求参数 | 一言语句接口请求参数}
+ */
+export function resolveTypeCodes(names: string[]): SentenceType[] {
+  return names.map(name => {
+    const code: SentenceType = TYPE_CODES[<keyof typeof TYPE_CODES>name];
+
+    if (!code) {
+      throw new Error(`类型「${name}」不是有效值，支持的句子类型有：${TYPE_NAMES}`);
+    }
+    return code;
+  });
+}
+
+/** 一言 v1 语句接口成功响应的完整返回信息。 */
+export interface Sentence {
+  /** 一言标识 */
+  readonly id: number;
+  /** 一言正文。编码方式 unicode。使用 utf-8。 */
+  readonly hitokoto: string;
+  /** 类型。请参考第三节参数的表格 */
+  readonly type: SentenceType;
+  /** 一言的出处 */
+  readonly from: string;
+  /** 一言的作者 */
+  readonly from_who: string | null;
+  /** 添加者 */
+  readonly creator: string;
+  /** 添加者用户标识 */
+  readonly creator_uid: number;
+  /** 审核员标识 */
+  readonly reviewer: number;
+  /** 一言唯一标识，可以链接到 https://hitokoto.cn?uuid=[uuid] 查看这个一言的完整信息 */
+  readonly uuid: string;
+  /** 提交方式 */
+  readonly commit_from: string;
+  /** 添加时间 */
+  readonly created_at: string;
+  /** 句子长度 */
+  readonly length: number;
+}
+
+/**
+ * 一言 v1 语句接口的错误响应体。
+ *
+ * @see {@link https://github.com/hitokoto-osc/hitokoto-api/blob/master/src/controllers/hitokoto/_utils.js#L119-L127 | 一言接口错误响应源码}
+ */
+export interface ErrorResponse {
+  /** HTTP 状态码。 */
+  readonly status: number;
+  /** 错误信息。 */
+  readonly message: string;
+  /** 错误响应的数据，接口当前返回空数组。 */
+  readonly data: unknown[];
+  /** 生成响应时的 Unix 时间戳，单位为毫秒。 */
+  readonly ts: number;
+}
+
+/**
+ * 将单个句子类型代码规范化为代码数组。
+ *
+ * @remarks
+ * 未提供 `types` 时，函数读取以逗号分隔的 `HITOKOTO_TYPES`。环境变量未设置时返回空数组。
+ * 显式传入空数组会跳过环境变量，表示不限制句子类型。
+ *
+ * @param types - 单个句子类型代码或句子类型代码数组。
+ * @returns 用于生成一言接口 `c` 查询参数的类型代码数组。
+ */
+export function resolveTypes(types: string | string[] = import.meta.env.HITOKOTO_TYPES?.split(',') ?? []): string[] {
+  return typeof types === 'string' ? [types] : types;
+}
+
+/**
+ * 判断一个值是否符合一言接口的错误响应结构。
+ *
+ * @remarks
+ * 该类型守卫只检查响应体字段，不读取或判断 HTTP 响应状态。
+ *
+ * @param value - 要检查的值，通常是解析后的非 2xx 响应体。
+ * @returns 如果 `value` 符合 {@link ErrorResponse} 结构则返回 `true`，否则返回 `false`。
+ * @see {@link https://github.com/hitokoto-osc/hitokoto-api/blob/master/src/controllers/hitokoto/_utils.js#L119-L127 | 一言接口错误响应源码}
+ */
+export function isErrorResponse(value: unknown): value is ErrorResponse {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'status' in value &&
+    typeof value.status === 'number' &&
+    'message' in value &&
+    typeof value.message === 'string' &&
+    'data' in value &&
+    Array.isArray(value.data) &&
+    'ts' in value &&
+    typeof value.ts === 'number'
+  );
+}
+
+/**
+ * 请求一言 v1 语句接口，并返回随机语句的完整信息。
+ *
+ * @remarks
+ * `types` 接收接口类型代码，不接收中文类型名称。中文名称可以先通过 {@link resolveTypeCodes} 转换。
+ * 每个类型代码会作为独立的 `c` 查询参数发送，对应官网「可选择多个分类」的用法。
+ *
+ * 未提供 `types` 时，函数读取以逗号分隔的 `HITOKOTO_TYPES`。环境变量未设置时不限制句子类型。
+ * 显式传入空数组时，不会读取环境变量，也不会发送 `c` 查询参数。
+ *
+ * @param types - 单个句子类型代码或句子类型代码数组。
+ * @returns 一个 Promise，成功时返回完整的 {@link Sentence}。
+ * @throws 收到非 2xx 响应时抛出 `Error`。如果响应体符合 {@link ErrorResponse}，错误信息使用其 `message`，
+ * 否则错误信息包含 HTTP 状态码。
+ * @throws 网络请求失败或成功响应无法解析为 JSON 时，传播底层错误。
+ *
+ * @example
+ * ```ts
+ * const types = resolveTypeCodes(['动画', '诗词']);
+ * const sentence = await fetchSentence(types);
+ * console.log(sentence.hitokoto);
+ * ```
+ *
+ * @see {@link https://developer.hitokoto.cn/sentence/ | 一言语句接口}
+ */
+export async function fetchSentence(types?: SentenceType | SentenceType[]): Promise<Sentence> {
+  const url = new URL(HITOKOTO_API);
+
+  for (const type of resolveTypes(types)) {
+    url.searchParams.append('c', type);
+  }
+  const response = await fetch(url);
+
+  if (response.ok) {
+    return <Sentence>await response.json();
+  }
+  const body = await response.json().catch(() => null);
+
+  if (isErrorResponse(body)) {
+    throw new Error(body.message);
+  }
+  throw new Error(`Hitokoto 请求失败，状态码 ${response.status}`);
+}