@zhin.js/adapter-line 0.1.0 → 1.1.0

package/lib/endpoint.js

@@ -1,437 +1,169 @@
-/**
- * LINE Endpoint 实现
- *
- * 使用 Webhook 模式接收消息，通过 LINE Messaging API 发送消息。
- * HMAC-SHA256 签名验证确保请求来自 LINE 平台。
- */
-import { createHmac, timingSafeEqual } from "node:crypto";
-import { Message, segment, formatCompact, } from "zhin.js";
-import { registerFetchRoute } from "@zhin.js/host-router/router";
-/** Type guard: narrows a LineEvent to a message event */
-function isMessageEvent(e) {
-    return e.type === "message" && "message" in e && e.message != null;
-}
-/** Type guard: narrows a LineEvent to a postback event */
-function isPostbackEvent(e) {
-    return e.type === "postback" && "postback" in e;
-}
-export class LineEndpoint {
-    adapter;
-    router;
-    $config;
-    $connected = false;
-    get pluginLogger() {
-        return this.adapter.plugin.logger;
-    }
-    get $id() {
-        return this.$config.name;
-    }
-    constructor(adapter, router, $config) {
-        this.adapter = adapter;
-        this.router = router;
-        this.$config = $config;
-    }
-    async $connect() {
+import { Endpoint } from 'zhin.js/adapter';
+import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
+import { formatInboundContent, formatOutboundMessages, generateMessageId, isLineLifecycleEvent, isMessageEvent, isValidLineRecipientId, lineInboundConversation, } from './protocol.js';
+import { registerLineWebhookRoutes } from './webhook.js';
+import { receiveLineSideEvent } from './side-event-dispatch.js';
+import { LineClient } from './client.js';
+/** LINE replyToken 有效期短，过期后 reply 必 400；缓存带时间戳，超时弃用改走 push。 */
+const REPLY_TOKEN_TTL_MS = 60_000;
+/** 出站 HTTP 调用统一 30s 超时。 */
+const OUTBOUND_TIMEOUT_MS = 30_000;
+export class LineEndpoint extends Endpoint {
+    client;
+    #logger;
+    #options;
+    #fetch;
+    #routeReleases = [];
+    #replyTokenCache = new Map();
+    #open = false;
+    #started = false;
+    management = createLineEndpointManagement(this);
+    constructor(options) {
+        super();
+        this.#logger = getAdapterLogger('line', options.config.id);
+        this.#options = options;
+        this.#fetch = options.fetch ?? globalThis.fetch;
+        this.client = new LineClient(options.config, this.#fetch);
+    }
+    /** Used by webhook handler. */
+    get isOpen() {
+        return this.#open;
+    }
+    get config() {
+        return this.#options.config;
+    }
+    async start() {
+        if (this.#started)
+            return;
+        this.#started = true;
         try {
-            const path = this.$config.webhookPath || "/line/webhook";
-            const cleanPath = path.startsWith("/") ? path : `/${path}`;
-            registerFetchRoute(this.router, "POST", cleanPath, async (ctx) => {
-                await this.handleWebhook(ctx);
-            });
-            this.$connected = true;
-            this.pluginLogger.info(formatCompact({ op: "webhook", path: cleanPath }));
+            this.#routeReleases.push(...registerLineWebhookRoutes(this.#options.http, this));
+            this.#logger.debug(formatCompact({
+                endpoint: this.#options.config.id,
+                op: 'webhook',
+                path: this.#options.config.webhookPath,
+            }));
         }
         catch (error) {
-            this.pluginLogger.error("Failed to connect LINE endpoint:", error);
-            this.$connected = false;
+            await this.stop();
+            this.#logger.error('Failed to connect LINE endpoint:', error);
             throw error;
         }
     }
-    async $disconnect() {
-        try {
-            this.$connected = false;
-            this.replyTokenCache.clear();
-            this.pluginLogger.info(`LINE endpoint ${this.$config.name} disconnected`);
-        }
-        catch (error) {
-            this.pluginLogger.error("Error disconnecting LINE endpoint:", error);
-            // L02: Log and swallow instead of re-throwing
-        }
-    }
-    // ── Webhook 处理 ────────────────────────────────────────────────────
-    async handleWebhook(ctx) {
-        try {
-            // 1. 签名验证
-            const signature = ctx.get("x-line-signature");
-            if (!signature) {
-                ctx.status = 403;
-                ctx.body = { message: "Missing signature" };
-                return;
-            }
-            // L05: 获取原始请求体用于签名验证
-            // Koa ctx.req 是 Node.js IncomingMessage，koa-body 可能已经消费了流
-            // 因此优先使用已解析的 body 并序列化，记录警告说明可能不精确
-            let rawBody;
-            if (typeof ctx.request.body === "string") {
-                rawBody = ctx.request.body;
-            }
-            else {
-                rawBody = JSON.stringify(ctx.request.body);
-                this.pluginLogger.debug("Signature verification using JSON.stringify(body) — may differ from original raw body");
-            }
-            if (!this.verifySignature(rawBody, signature)) {
-                this.pluginLogger.warn(formatCompact({ op: "webhook", ok: false, error: "invalid signature" }));
-                ctx.status = 403;
-                ctx.body = { message: "Invalid signature" };
-                return;
-            }
-            // 2. 解析事件
-            const body = typeof ctx.request.body === "string"
-                ? JSON.parse(ctx.request.body)
-                : ctx.request.body;
-            if (!body.events || !Array.isArray(body.events)) {
-                ctx.status = 200;
-                ctx.body = { message: "OK" };
-                return;
-            }
-            // 3. 处理每个事件
-            for (const event of body.events) {
-                await this.handleEvent(event);
-            }
-            ctx.status = 200;
-            ctx.body = { message: "OK" };
-        }
-        catch (error) {
-            this.pluginLogger.error("LINE webhook error:", error);
-            ctx.status = 200;
-            ctx.body = { message: "OK" };
-        }
-    }
-    // L07: Use timing-safe comparison for signature
-    verifySignature(body, signature) {
-        const channelSecret = this.$config.channelSecret;
-        const hmac = createHmac("sha256", channelSecret);
-        hmac.update(body, "utf-8");
-        const computedSignature = hmac.digest("base64");
-        const sigBuf = Buffer.from(signature);
-        const computedBuf = Buffer.from(computedSignature);
-        if (sigBuf.length !== computedBuf.length)
-            return false;
-        return timingSafeEqual(sigBuf, computedBuf);
-    }
-    // L04: Use type guards instead of "in" checks + `as any` casts
-    async handleEvent(event) {
-        switch (event.type) {
-            case "message":
-                if (isMessageEvent(event)) {
-                    await this.handleMessageEvent(event);
+    open() {
+        this.#open = true;
+    }
+    close() {
+        this.#open = false;
+    }
+    async stop() {
+        this.#open = false;
+        this.#replyTokenCache.clear();
+        for (const release of this.#routeReleases.splice(0))
+            release();
+        this.#started = false;
+        this.#logger.debug(formatCompact({ op: 'disconnect' }));
+    }
+    async send({ conversation, payload }) {
+        const messages = formatOutboundMessages(payload);
+        if (messages.length === 0) {
+            throw new Error('No valid LINE messages to send');
+        }
+        // LINE recipient id 前缀（U/G/R）自带场景信息，原生 id 即投递地址。
+        const target = conversation.id;
+        const cached = this.#replyTokenCache.get(target);
+        if (cached) {
+            this.#replyTokenCache.delete(target);
+            if (Date.now() - cached.timestamp <= REPLY_TOKEN_TTL_MS) {
+                try {
+                    return await this.#replyMessage(cached.token, messages);
                 }
-                break;
-            case "follow":
-                await this.handleFollowEvent(event);
-                break;
-            case "unfollow":
-                this.pluginLogger.debug(formatCompact({
-                    op: "unfollow",
-                    endpoint: this.$config.name,
-                    userId: event.source.userId,
-                }));
-                break;
-            case "join":
-                await this.handleJoinEvent(event);
-                break;
-            case "leave":
-                this.pluginLogger.debug(formatCompact({
-                    op: "leave",
-                    endpoint: this.$config.name,
-                    sourceType: event.source.type,
-                    groupId: event.source.groupId,
-                    roomId: event.source.roomId,
-                }));
-                break;
-            case "postback":
-                if (isPostbackEvent(event)) {
-                    this.pluginLogger.debug(formatCompact({
-                        op: "postback",
-                        endpoint: this.$config.name,
-                        data: event.postback.data,
+                catch (error) {
+                    // replyToken 过期/失效时 LINE 返回 400，回退 push 保证消息不丢
+                    if (error.status !== 400)
+                        throw error;
+                    this.#logger.warn(formatCompact({
+                        op: 'line_reply_fallback_push',
+                        endpoint: this.#options.config.id,
+                        target,
                     }));
                 }
-                break;
-            default:
-                this.pluginLogger.debug(formatCompact({
-                    op: "unknown_event",
-                    endpoint: this.$config.name,
-                    type: event.type,
-                }));
-        }
-    }
-    // L01: Cache replyToken from webhook events before emitting
-    async handleMessageEvent(event) {
-        const { channelId } = this.resolveChannel(event.source);
-        this.cacheReplyToken(channelId, event.replyToken);
-        const message = this.$formatMessage(event);
-        this.adapter.emit("message.receive", message);
-        this.pluginLogger.debug(formatCompact({
-            op: "recv",
-            endpoint: this.$config.name,
-            channel: message.$channel.type,
-            id: message.$channel.id,
-            len: segment.raw(message.$content).length,
-        }));
-    }
-    async handleFollowEvent(event) {
-        const { channelId } = this.resolveChannel(event.source);
-        this.cacheReplyToken(channelId, event.replyToken);
-        const message = this.$formatMessage(event);
-        this.adapter.emit("message.receive", message);
-        this.pluginLogger.debug(formatCompact({
-            op: "follow",
-            endpoint: this.$config.name,
-            userId: event.source.userId,
-        }));
-    }
-    async handleJoinEvent(event) {
-        const { channelId } = this.resolveChannel(event.source);
-        this.cacheReplyToken(channelId, event.replyToken);
-        const message = this.$formatMessage(event);
-        this.adapter.emit("message.receive", message);
-        this.pluginLogger.debug(formatCompact({
-            op: "join",
-            endpoint: this.$config.name,
-            sourceType: event.source.type,
-            groupId: event.source.groupId,
-            roomId: event.source.roomId,
-        }));
-    }
-    // ── 消息格式化 ────────────────────────────────────────────────────
-    $formatMessage(event) {
-        const { channelType, channelId } = this.resolveChannel(event.source);
-        const content = this.parseMessageContent(event);
-        const quoteId = Message.quoteIdFromContent(content);
-        Message.alignReplySegments(content, quoteId);
-        const userId = event.source.userId || "";
-        const timestamp = event.timestamp || Date.now();
-        const rawText = this.extractRawText(event);
-        return Message.from(event, {
-            $id: this.generateMessageId(event),
-            $adapter: "line",
-            $endpoint: this.$config.name,
-            $sender: {
-                id: userId,
-                name: userId,
-            },
-            $channel: {
-                id: channelId,
-                type: channelType,
-            },
-            $content: content,
-            $quote_id: quoteId,
-            $raw: rawText,
-            $timestamp: timestamp,
-            $recall: async () => {
-                // LINE 不支持消息撤回
-                this.pluginLogger.warn("LINE does not support message recall");
-            },
-            $reply: async (content, quote) => {
-                if (!Array.isArray(content))
-                    content = [content];
-                if (quote) {
-                    const replyToMessageId = typeof quote === "boolean"
-                        ? (isMessageEvent(event) && event.message?.id) || ""
-                        : quote;
-                    content.unshift({ type: "reply", data: { id: replyToMessageId } });
-                }
-                return await this.adapter.sendMessage({
-                    context: "line",
-                    endpoint: this.$config.name,
-                    id: channelId,
-                    type: channelType,
-                    content: content,
-                });
-            },
-        });
-    }
-    generateMessageId(event) {
-        if (isMessageEvent(event) && event.message?.id) {
-            return event.message.id;
-        }
-        return `${event.type}-${event.timestamp}`;
-    }
-    resolveChannel(source) {
-        switch (source.type) {
-            case "user":
-                return { channelType: "private", channelId: source.userId || "" };
-            case "group":
-                return { channelType: "group", channelId: source.groupId || "" };
-            case "room":
-                return { channelType: "channel", channelId: source.roomId || "" };
-            default:
-                return { channelType: "private", channelId: "" };
-        }
-    }
-    extractRawText(event) {
-        if (isMessageEvent(event)) {
-            const msg = event.message;
-            if (msg.type === "text" && msg.text)
-                return msg.text;
-            if (msg.type === "location" && msg.address)
-                return msg.address;
-            return `[${msg.type}]`;
-        }
-        if (event.type === "follow")
-            return "[follow]";
-        if (event.type === "join")
-            return "[join]";
-        return "";
-    }
-    parseMessageContent(event) {
-        const segments = [];
-        if (isMessageEvent(event)) {
-            const msg = event.message;
-            switch (msg.type) {
-                case "text":
-                    if (msg.text) {
-                        segments.push({ type: "text", data: { text: msg.text } });
-                    }
-                    break;
-                case "image":
-                    segments.push({
-                        type: "image",
-                        data: {
-                            message_id: msg.id,
-                            platform: "line",
-                        },
-                    });
-                    break;
-                case "video":
-                    segments.push({
-                        type: "video",
-                        data: {
-                            message_id: msg.id,
-                            platform: "line",
-                        },
-                    });
-                    break;
-                case "audio":
-                    segments.push({
-                        type: "audio",
-                        data: {
-                            message_id: msg.id,
-                            duration: msg.duration || 0,
-                            platform: "line",
-                        },
-                    });
-                    break;
-                case "file":
-                    segments.push({
-                        type: "file",
-                        data: {
-                            message_id: msg.id,
-                            file_name: msg.fileName,
-                            file_size: msg.fileSize,
-                            platform: "line",
-                        },
-                    });
-                    break;
-                case "location":
-                    segments.push({
-                        type: "location",
-                        data: {
-                            title: msg.title,
-                            address: msg.address,
-                            latitude: msg.latitude,
-                            longitude: msg.longitude,
-                        },
-                    });
-                    break;
-                case "sticker":
-                    segments.push({
-                        type: "sticker",
-                        data: {
-                            package_id: msg.packageId,
-                            sticker_id: msg.stickerId,
-                            resource_type: msg.stickerResourceType,
-                        },
-                    });
-                    break;
-                default:
-                    segments.push({ type: "text", data: { text: `[unsupported message type]` } });
             }
         }
-        else {
-            // 系统事件（follow/unfollow/join/leave）
-            const text = event.type === "follow" ? "[follow event]"
-                : event.type === "join" ? "[join event]"
-                    : event.type === "unfollow" ? "[unfollow event]"
-                        : event.type === "leave" ? "[leave event]"
-                            : `[${event.type} event]`;
-            segments.push({ type: "text", data: { text } });
-        }
-        return segments.length > 0 ? segments : [{ type: "text", data: { text: "" } }];
-    }
-    // ── 发送消息 ──────────────────────────────────────────────────────
-    async $sendMessage(options) {
-        try {
-            const messages = this.buildLineMessages(options.content);
-            if (messages.length === 0) {
-                throw new Error("No valid LINE messages to send");
-            }
-            // 优先使用 Reply API（如果存在 replyToken）
-            const replyToken = this.replyTokenCache.get(options.id);
-            if (replyToken) {
-                this.replyTokenCache.delete(options.id);
-                return await this.replyMessage(replyToken, messages);
-            }
-            // L06: Validate Push API `to` field
-            if (!/^[UGR]/.test(options.id)) {
-                throw new Error(`Invalid LINE recipient ID "${options.id}": must start with U (user), G (group), or R (room)`);
-            }
-            // 使用 Push API
-            return await this.pushMessage(options.id, messages);
-        }
-        catch (error) {
-            this.pluginLogger.error("Failed to send LINE message:", error);
-            throw error;
-        }
-    }
-    replyTokenCache = new Map();
-    /**
-     * 缓存 replyToken，用于后续发送回复消息
-     */
-    cacheReplyToken(channelId, replyToken) {
-        this.replyTokenCache.set(channelId, replyToken);
+        if (!isValidLineRecipientId(target)) {
+            throw new Error(`Invalid LINE recipient ID "${target}": must start with U (user), G (group), or R (room)`);
+        }
+        return this.#pushMessage(target, messages);
+    }
+    /** Test / internal: admit a parsed event when open (non-webhook path). */
+    admit(event) {
+        if (!this.#open)
+            return;
+        void this.emitPlatform(event.type || 'event', event).catch((error) => {
+            this.#logger.warn(formatCompact({
+                op: 'line_platform_event_failed',
+                event: event.type,
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        });
+        if (isLineLifecycleEvent(event)) {
+            receiveLineSideEvent((name, payload) => this.emit(name, payload), String(this.#options.id), this.#options.config.id, event, this.#logger);
+            return;
+        }
+        const conversation = lineInboundConversation(String(this.#options.id), event.source);
+        if ('replyToken' in event && typeof event.replyToken === 'string') {
+            this.#replyTokenCache.set(conversation.id, { token: event.replyToken, timestamp: Date.now() });
+        }
+        void this.emit('message.receive', {
+            conversation,
+            message: { conversation, id: generateMessageId(event) },
+            content: formatInboundContent(event),
+            sender: { id: event.source.userId || conversation.id },
+            endpointId: this.#options.config.id,
+            metadata: Object.freeze({
+                eventType: event.type,
+                sourceType: event.source.type,
+                timestamp: event.timestamp,
+                ...(isMessageEvent(event) ? { messageType: event.message.type } : {}),
+            }),
+        }).catch((err) => {
+            this.#logger.warn(formatCompact({
+                op: 'line_gateway_receive_failed',
+                target: `${conversation.kind}:${conversation.id}`,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
     }
-    // L15: Parse Reply API response for message ID
-    async replyMessage(replyToken, messages) {
-        const baseUrl = this.$config.apiBaseUrl || "https://api.line.me";
-        const request = { replyToken, messages };
-        const response = await fetch(`${baseUrl}/v2/bot/message/reply`, {
-            method: "POST",
+    async #replyMessage(replyToken, messages) {
+        const url = `${this.#options.config.apiBaseUrl}/v2/bot/message/reply`;
+        const response = await this.#fetch(url, {
+            method: 'POST',
             headers: {
-                "Content-Type": "application/json",
-                "Authorization": `Bearer ${this.$config.channelAccessToken}`,
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${this.#options.config.channelAccessToken}`,
             },
-            body: JSON.stringify(request),
+            body: JSON.stringify({ replyToken, messages }),
+            signal: AbortSignal.timeout(OUTBOUND_TIMEOUT_MS),
         });
         if (!response.ok) {
             const errorText = await response.text();
-            throw new Error(`LINE Reply API error ${response.status}: ${errorText}`);
+            const error = new Error(`LINE Reply API error ${response.status}: ${errorText}`);
+            error.status = response.status;
+            throw error;
         }
-        // Reply API now returns sentMessages in the response body
         const result = await response.json();
         return result.sentMessages?.[0]?.id || `reply-${Date.now()}`;
     }
-    async pushMessage(to, messages) {
-        const baseUrl = this.$config.apiBaseUrl || "https://api.line.me";
-        const request = { to, messages };
-        const response = await fetch(`${baseUrl}/v2/bot/message/push`, {
-            method: "POST",
+    async #pushMessage(to, messages) {
+        const url = `${this.#options.config.apiBaseUrl}/v2/bot/message/push`;
+        const response = await this.#fetch(url, {
+            method: 'POST',
             headers: {
-                "Content-Type": "application/json",
-                "Authorization": `Bearer ${this.$config.channelAccessToken}`,
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${this.#options.config.channelAccessToken}`,
             },
-            body: JSON.stringify(request),
+            body: JSON.stringify({ to, messages }),
+            signal: AbortSignal.timeout(OUTBOUND_TIMEOUT_MS),
         });
         if (!response.ok) {
             const errorText = await response.text();
@@ -440,93 +172,10 @@ export class LineEndpoint {
         const result = await response.json();
         return result.sentMessages?.[0]?.id || `push-${Date.now()}`;
     }
-    buildLineMessages(content) {
-        if (!Array.isArray(content))
-            content = [content];
-        const messages = [];
-        for (const item of content) {
-            if (typeof item === "string") {
-                messages.push(this.buildTextMessage(item));
-                continue;
-            }
-            const seg = item;
-            switch (seg.type) {
-                case "text":
-                    messages.push(this.buildTextMessage(seg.data.text || ""));
-                    break;
-                case "at":
-                    // LINE 没有 @ 语法，转为文本
-                    if (seg.data.id) {
-                        messages.push(this.buildTextMessage(`@${seg.data.name || seg.data.id}`));
-                    }
-                    break;
-                case "image":
-                    if (seg.data.url) {
-                        messages.push({
-                            type: "image",
-                            originalContentUrl: seg.data.url,
-                            previewImageUrl: seg.data.url,
-                        });
-                    }
-                    break;
-                case "video":
-                    if (seg.data.url) {
-                        messages.push({
-                            type: "video",
-                            originalContentUrl: seg.data.url,
-                            previewImageUrl: seg.data.previewUrl || seg.data.url,
-                        });
-                    }
-                    break;
-                case "audio":
-                    if (seg.data.url) {
-                        messages.push({
-                            type: "audio",
-                            originalContentUrl: seg.data.url,
-                            duration: seg.data.duration || 0,
-                        });
-                    }
-                    break;
-                case "location":
-                    messages.push({
-                        type: "location",
-                        title: seg.data.title || "Location",
-                        address: seg.data.address || "",
-                        latitude: seg.data.latitude || 0,
-                        longitude: seg.data.longitude || 0,
-                    });
-                    break;
-                case "sticker":
-                    messages.push({
-                        type: "sticker",
-                        packageId: seg.data.package_id || "1",
-                        stickerId: seg.data.sticker_id || "1",
-                    });
-                    break;
-                default:
-                    messages.push(this.buildTextMessage(`[${seg.type}]`));
-            }
-        }
-        // L14: Log warning when messages are sliced to 5 (LINE limit)
-        if (messages.length > 5) {
-            this.pluginLogger.warn(`LINE messages truncated from ${messages.length} to 5 (platform limit)`);
-        }
-        // LINE 单次最多发送 5 条消息
-        return messages.slice(0, 5);
-    }
-    buildTextMessage(text) {
-        // L13: Log warning on text truncation
-        if (text.length > 5000) {
-            this.pluginLogger.warn(`LINE text message truncated from ${text.length} to 5000 characters`);
-        }
-        // LINE 消息文本限制 5000 字符
-        const truncated = text.length > 5000 ? text.slice(0, 4997) + "..." : text;
-        return { type: "text", text: truncated };
-    }
-    // ── 消息撤回 ──────────────────────────────────────────────────────
-    // L16: Log warning and return gracefully (matching WeCom/DingTalk pattern)
-    async $recallMessage(_id) {
-        this.pluginLogger.warn(formatCompact({ op: "recall", ok: false, error: "LINE Messaging API does not support message recall" }));
-    }
 }
-//# sourceMappingURL=endpoint.js.map
+function createLineEndpointManagement(endpoint) {
+    return Object.freeze({
+        // listGroups 不接：LINE Bot API 没有"我加入了哪些群"的接口，群 id 只能来自入站事件。
+        listGroupMembers: (groupId) => endpoint.client.getGroupMembers(groupId),
+    });
+}