@zhin.js/adapter-line 0.1.0

package/README.md

@@ -0,0 +1,76 @@
+# @zhin.js/adapter-line
+
+Zhin.js 适配器 — LINE Messaging API (Webhook 模式)
+
+## 功能
+
+- 接收并解析 LINE Webhook 事件（text、image、video、audio、file、location、sticker）
+- 支持私聊、群组、多人聊天（room）三种场景
+- Reply API / Push API 发送消息
+- HMAC-SHA256 签名验证
+
+## 前置条件
+
+1. 在 [LINE Developers Console](https://developers.line.biz/) 创建 Messaging API Channel
+2. 获取 **Channel Secret** 和 **Channel Access Token**
+3. 设置 Webhook URL 为 `https://your-domain/line/webhook`
+4. 在 Console 中启用 **Use webhooks** 并关闭 **Auto-reply messages**
+
+## 最小配置
+
+```yaml
+# zhin.config.yml
+adapters:
+  - context: line
+    name: my-line-bot
+    channelSecret: ${LINE_CHANNEL_SECRET}
+    channelAccessToken: ${LINE_CHANNEL_ACCESS_TOKEN}
+    webhookPath: /line/webhook       # 可选，默认 /line/webhook
+    apiBaseUrl: https://api.line.me   # 可选，调试时可改为 LINE API 沙盒地址
+```
+
+## 环境变量
+
+| 变量 | 说明 |
+|------|------|
+| `LINE_CHANNEL_SECRET` | Channel Secret（签名验证用） |
+| `LINE_CHANNEL_ACCESS_TOKEN` | Long-lived Channel Access Token（API 调用用） |
+
+## Webhook URL 配置
+
+LINE 要求 Webhook URL 以 HTTPS 开头。常见方案：
+
+- **反向代理**：Nginx/Caddy 将 `https://your-domain/line/webhook` 转发到本地 zhIn 端口
+- **Cloudflare Tunnel**：`cloudflared tunnel --url http://localhost:端口`
+- **ngrok**：调试用 `ngrok http 端口`
+
+设置完成后在 LINE Developers Console 点击 **Verify** 验证连通性。
+
+## 消息类型映射
+
+| LINE 类型 | Zhin.js Segment | 说明 |
+|-----------|----------------|------|
+| text | text | 纯文本 |
+| image | image | 图片（暂不支持二次获取） |
+| video | video | 视频 |
+| audio | audio | 音频 |
+| file | file | 文件 |
+| location | location | 位置信息 |
+| sticker | sticker | 贴纸 |
+
+## 已知限制
+
+- **不支持消息撤回**：LINE Messaging API 不提供撤回已发送消息的接口
+- **图片/视频/音频**：收到的媒体消息仅包含 message_id，需通过 Content API 下载（未实装）
+- **单次最多 5 条消息**：LINE 限制单次 Reply/Push 最多 5 条
+- **文本长度限制**：单条文本消息最多 5000 字符
+
+## 故障排查
+
+| 问题 | 排查方法 |
+|------|---------|
+| Webhook Verify 失败 | 检查 HTTPS 证书、域名解析、端口是否可达 |
+| 签名验证 403 | 确认 Channel Secret 与 Console 一致 |
+| 发送 401 | 确认 Channel Access Token 未过期 |
+| 发送 400 | 检查消息格式是否符合 LINE API 规范 |
+| 事件未到达 | Console 中 Webhook 是否已启用、是否关闭 Auto-reply |

package/lib/adapter.d.ts

@@ -0,0 +1,15 @@
+/**
+ * LINE 适配器
+ */
+import { Adapter, Plugin } from "zhin.js";
+import { LineEndpoint } from "./endpoint.js";
+import type { LineEndpointConfig } from "./types.js";
+import type { Router } from "@zhin.js/host-router/router";
+export declare class LineAdapter extends Adapter<LineEndpoint> {
+    #private;
+    static readonly capabilities: readonly ["inbound", "outbound"];
+    constructor(plugin: Plugin, router: Router);
+    createEndpoint(config: LineEndpointConfig): LineEndpoint;
+    start(): Promise<void>;
+}
+//# sourceMappingURL=adapter.d.ts.map

package/lib/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EACL,OAAO,EACP,MAAM,EACP,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AAE1D,qBAAa,WAAY,SAAQ,OAAO,CAAC,YAAY,CAAC;;IACpD,gBAAyB,YAAY,mCAAoC;gBAI7D,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAK1C,cAAc,CAAC,MAAM,EAAE,kBAAkB,GAAG,YAAY;IAIlD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}

package/lib/adapter.js

@@ -0,0 +1,20 @@
+/**
+ * LINE 适配器
+ */
+import { Adapter, } from "zhin.js";
+import { LineEndpoint } from "./endpoint.js";
+export class LineAdapter extends Adapter {
+    static capabilities = ['inbound', 'outbound'];
+    #router;
+    constructor(plugin, router) {
+        super(plugin, "line", []);
+        this.#router = router;
+    }
+    createEndpoint(config) {
+        return new LineEndpoint(this, this.#router, config);
+    }
+    async start() {
+        await super.start();
+    }
+}
+//# sourceMappingURL=adapter.js.map

package/lib/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EACL,OAAO,GAER,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAI7C,MAAM,OAAO,WAAY,SAAQ,OAAqB;IACpD,MAAM,CAAmB,YAAY,GAAG,CAAC,SAAS,EAAE,UAAU,CAAU,CAAC;IAEzE,OAAO,CAAS;IAEhB,YAAY,MAAc,EAAE,MAAc;QACxC,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC;QAC1B,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACxB,CAAC;IAED,cAAc,CAAC,MAA0B;QACvC,OAAO,IAAI,YAAY,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACtD,CAAC;IAED,KAAK,CAAC,KAAK;QACT,MAAM,KAAK,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC"}

package/lib/endpoint.d.ts

@@ -0,0 +1,38 @@
+import { Endpoint, Message, SendOptions } from "zhin.js";
+import { type Router } from "@zhin.js/host-router/router";
+import type { LineEndpointConfig, LineEvent } from "./types.js";
+import type { LineAdapter } from "./adapter.js";
+export declare class LineEndpoint implements Endpoint<LineEndpointConfig, LineEvent> {
+    adapter: LineAdapter;
+    private router;
+    $config: LineEndpointConfig;
+    $connected: boolean;
+    get pluginLogger(): import("zhin.js").Logger;
+    get $id(): string;
+    constructor(adapter: LineAdapter, router: Router, $config: LineEndpointConfig);
+    $connect(): Promise<void>;
+    $disconnect(): Promise<void>;
+    private handleWebhook;
+    private verifySignature;
+    private handleEvent;
+    private handleMessageEvent;
+    private handleFollowEvent;
+    private handleJoinEvent;
+    $formatMessage(event: LineEvent): Message<LineEvent>;
+    private generateMessageId;
+    private resolveChannel;
+    private extractRawText;
+    private parseMessageContent;
+    $sendMessage(options: SendOptions): Promise<string>;
+    private replyTokenCache;
+    /**
+     * 缓存 replyToken，用于后续发送回复消息
+     */
+    cacheReplyToken(channelId: string, replyToken: string): void;
+    private replyMessage;
+    private pushMessage;
+    private buildLineMessages;
+    private buildTextMessage;
+    $recallMessage(_id: string): Promise<void>;
+}
+//# sourceMappingURL=endpoint.d.ts.map

package/lib/endpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint.d.ts","sourceRoot":"","sources":["../src/endpoint.ts"],"names":[],"mappings":"AAOA,OAAO,EACL,QAAQ,EACR,OAAO,EACP,WAAW,EAMZ,MAAM,SAAS,CAAC;AACjB,OAAO,EAAsB,KAAK,MAAM,EAAsB,MAAM,6BAA6B,CAAC;AAClG,OAAO,KAAK,EACV,kBAAkB,EAClB,SAAS,EAWV,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAYhD,qBAAa,YAAa,YAAW,QAAQ,CAAC,kBAAkB,EAAE,SAAS,CAAC;IAYjE,OAAO,EAAE,WAAW;IAC3B,OAAO,CAAC,MAAM;IACP,OAAO,EAAE,kBAAkB;IAbpC,UAAU,EAAE,OAAO,CAAS;IAE5B,IAAI,YAAY,6BAEf;IAED,IAAI,GAAG,WAEN;gBAGQ,OAAO,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,EACf,OAAO,EAAE,kBAAkB;IAG9B,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAgBzB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;YAapB,aAAa;IAsD3B,OAAO,CAAC,eAAe;YAYT,WAAW;YAgDX,kBAAkB;YAelB,iBAAiB;YAajB,eAAe;IAiB7B,cAAc,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IAoDpD,OAAO,CAAC,iBAAiB;IAOzB,OAAO,CAAC,cAAc;IAatB,OAAO,CAAC,cAAc;IAYtB,OAAO,CAAC,mBAAmB;IAyFrB,YAAY,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IA6BzD,OAAO,CAAC,eAAe,CAA6B;IAEpD;;OAEG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;YAK9C,YAAY;YAsBZ,WAAW;IAqBzB,OAAO,CAAC,iBAAiB;IAgFzB,OAAO,CAAC,gBAAgB;IAelB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAKjD"}