kokkoro-plugin-og 0.0.0 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Yuki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1 +1,31 @@
 # kokkoro-plugin-og
+
+解析消息中的网页链接，并发送页面声明的 Open Graph 预览图片。
+
+## 安装
+
+```shell
+bun add kokkoro-plugin-og
+```
+
+使用 `/og <url>` 主动解析网页。单独发送一个 HTTP 或 HTTPS 链接时，快捷方式也会自动解析该链接，链接两侧可以留有空白。
+
+要让普通群消息触发自动预览，需要开启「获取群内全部消息」权限。
+
+完整使用说明见 [Open Graph 预览图](https://kokkoro.js.org/plugin/og)。
+
+## API
+
+其他插件可以从 `service` 入口导入 `fetchImageUrl()`，获取网页声明的 Open Graph 预览图片地址：
+
+```typescript
+import { fetchImageUrl } from 'kokkoro-plugin-og/service';
+
+const imageUrl = await fetchImageUrl('https://ogp.me/');
+```
+
+参数、解析规则和错误行为见 [插件 API 文档](https://kokkoro.js.org/plugin/og#api)。
+
+## 配置
+
+`OG_TIMEOUT` 设置请求超时时间，单位为毫秒。`OG_MAX_HTML_BYTES` 设置 HTML 内容上限，单位为字节。默认值和配置示例见 [插件配置](https://kokkoro.js.org/plugin/og#configuration)。

package/package.json

@@ -1,15 +1,35 @@
 {
   "name": "kokkoro-plugin-og",
-  "version": "0.0.0",
-  "exports": "./src/index.ts",
+  "version": "1.0.0",
+  "description": "Open Graph 图片预览，解析网页链接并发送 og:image 声明的图片。",
+  "keywords": [
+    "bot",
+    "kokkoro",
+    "og",
+    "open graph",
+    "qq"
+  ],
+  "bugs": "https://github.com/kokkorojs/kokkoro/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kokkorojs/kokkoro.git",
+    "directory": "plugins/og"
+  },
+  "license": "MIT",
+  "author": "Yuki <admin@yuki.sh>",
   "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./service": "./src/service.ts"
+  },
   "files": [
     "src"
   ],
-  "devDependencies": {
-    "@types/bun": "latest"
+  "dependencies": {
+    "entities": "^7.0.1"
   },
   "peerDependencies": {
-    "typescript": "^7"
+    "@kokkoro/core": "^3.1.4",
+    "typescript": "^6.0.3"
   }
 }

package/src/index.ts

@@ -1 +1,35 @@
-console.log('Ciallo～(∠·ω< )⌒★');
+import { type Bot, useCommand, useLogger } from '@kokkoro/core';
+
+import { fetchImageUrl } from './service';
+
+const logger = useLogger();
+
+export default (bot: Bot) => {
+  useCommand('/og <url>', async context => {
+    const { url } = context.args;
+
+    try {
+      logger.debug('发送网页请求', { method: 'GET', url });
+
+      const imageUrl = await fetchImageUrl(url);
+
+      if (!imageUrl) {
+        throw new Error('未能获取 Open Graph 预览图片');
+      }
+      logger.debug('已解析 Open Graph 预览图片地址', { url, imageUrl });
+
+      const payload = { msg_id: context.id };
+
+      if ('group_openid' in context) {
+        await bot.sendGroupImage(context.group_openid, imageUrl, payload);
+      } else {
+        await bot.sendUserImage(context.author.user_openid, imageUrl, payload);
+      }
+      logger.info('已发送 Open Graph 预览图片', { url, imageUrl });
+    } catch (error) {
+      if (context.trigger === 'command') {
+        throw error;
+      }
+    }
+  }).shortcut(/^(?<url>https?:\/\/\S+)\s*$/iu);
+};

package/src/service.ts

@@ -0,0 +1,60 @@
+import { decodeHTMLAttribute } from 'entities/decode';
+
+import { formatBytes, parseUrl } from './util';
+
+const { OG_TIMEOUT: TIMEOUT = 10000, OG_MAX_HTML_BYTES: MAX_HTML_BYTES = 1024 * 1024 } = import.meta.env;
+const maxHtmlBytes = Number(MAX_HTML_BYTES);
+
+if (!Number.isSafeInteger(maxHtmlBytes) || maxHtmlBytes <= 0) {
+  throw new RangeError('OG_MAX_HTML_BYTES 必须是正的安全整数');
+}
+
+/** 请求网页并返回首个有效的 Open Graph 图片地址，没有预览图时返回 `undefined`，请求失败时抛错。 */
+export async function fetchImageUrl(url: string): Promise<string | undefined> {
+  const pageUrl = parseUrl(url);
+
+  if (!pageUrl) {
+    throw new Error('链接格式无效');
+  }
+  const response = await fetch(pageUrl, {
+    headers: { accept: 'text/html, application/xhtml+xml' },
+    signal: AbortSignal.timeout(Number(TIMEOUT)),
+  });
+
+  if (!response.ok) {
+    await response.body?.cancel();
+    throw new Error(`网页请求失败，状态码 ${response.status}`);
+  }
+  const contentType = response.headers.get('content-type')?.trim() ?? '';
+
+  if (!/^(?:text\/html|application\/xhtml\+xml)(?:\s*;|$)/i.test(contentType) || !response.body) {
+    await response.body?.cancel();
+    return undefined;
+  }
+  let byteLength = 0;
+  const body = response.body.pipeThrough(
+    new TransformStream<Uint8Array, Uint8Array>({
+      transform(chunk, controller) {
+        byteLength += chunk.byteLength;
+
+        if (byteLength > maxHtmlBytes) {
+          throw new RangeError(`网页内容超过 ${formatBytes(maxHtmlBytes)}`);
+        }
+        controller.enqueue(chunk);
+      },
+    }),
+  );
+  const base = new URL(response.url);
+  let imageUrl: URL | undefined;
+  const rewriter = new HTMLRewriter().on(
+    'meta[property="og:image" i], meta[property="og:image:url" i], meta[property="og:image:secure_url" i]',
+    {
+      element(element) {
+        imageUrl ??= parseUrl(decodeHTMLAttribute(element.getAttribute('content') ?? ''), base);
+      },
+    },
+  );
+
+  await rewriter.transform(new Response(body, { headers: { 'content-type': contentType } })).arrayBuffer();
+  return imageUrl?.href;
+}

package/src/util.ts

@@ -0,0 +1,27 @@
+/** 将字节数转换为二进制单位字符串，最多保留两位小数。 */
+export function formatBytes(bytes: number): string {
+  let value = bytes;
+  let unit = 'B';
+
+  for (const next of ['KiB', 'MiB', 'GiB', 'TiB', 'PiB', 'EiB']) {
+    if (value < 1024) {
+      break;
+    }
+    value /= 1024;
+    unit = next;
+  }
+  return `${Number(value.toFixed(2))} ${unit}`;
+}
+
+/** 解析不含用户凭据的 HTTP 或 HTTPS 地址，空值和无效地址返回 `undefined`。 */
+export function parseUrl(source: string, base?: URL): URL | undefined {
+  if (!source.trim()) {
+    return undefined;
+  }
+  const url = URL.parse(source, base?.href);
+
+  if (!url || (url.protocol !== 'http:' && url.protocol !== 'https:') || url.username || url.password) {
+    return undefined;
+  }
+  return url;
+}