@zhin.js/adapter-napcat 3.0.1 → 4.0.1

package/lib/wss-endpoint.js

@@ -0,0 +1,157 @@
+/**
+ * NapCat reverse WSS endpoint — accepts inbound WebSocket from NapCat.
+ */
+import { clearInterval } from 'node:timers';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { registerNapcatAgentEndpoint } from './napcat-agent-deps.js';
+import { InboundMessageDeduper, isNapCatBotMentioned, isSelfMessage, normalizeMessage, } from './napcat-inbound.js';
+import { buildSendAction, formatInboundContent, formatInboundTarget, formatOutboundSegments, isMessageEvent, senderNickname, senderUserId, } from './protocol.js';
+import { callNapCatWsAction, handleNapCatWsMessage, rejectAllPending, startNapCatHeartbeat, } from './ws-transport.js';
+import { verifyNapCatAccessToken } from './wss-auth.js';
+const logger = getLogger('napcat');
+export class NapCatWssEndpoint {
+    #options;
+    #inboundDeduper = new InboundMessageDeduper();
+    #ws;
+    #wsRelease;
+    #heartbeatTimer;
+    #requestId = { value: 0 };
+    #pending = new Map();
+    #open = false;
+    #started = false;
+    #unregisterAgent;
+    constructor(options) {
+        this.#options = options;
+    }
+    async start() {
+        if (this.#started)
+            return;
+        this.#started = true;
+        this.#unregisterAgent = registerNapcatAgentEndpoint(this.#options.config.name, this);
+        const handle = this.#options.http.ws(this.#options.config.path);
+        this.#wsRelease = handle.onConnection((connection) => {
+            this.#acceptConnection(connection);
+        });
+        logger.info(formatCompact({
+            op: 'listen',
+            endpoint: this.#options.config.name,
+            mode: 'wss',
+            path: this.#options.config.path,
+        }));
+    }
+    open() {
+        this.#open = true;
+    }
+    close() {
+        this.#open = false;
+    }
+    async stop() {
+        this.#open = false;
+        this.#unregisterAgent?.();
+        this.#unregisterAgent = undefined;
+        this.#wsRelease?.();
+        this.#wsRelease = undefined;
+        if (this.#heartbeatTimer) {
+            clearInterval(this.#heartbeatTimer);
+            this.#heartbeatTimer = undefined;
+        }
+        rejectAllPending(this.#pending);
+        this.#inboundDeduper.clear();
+        if (this.#ws) {
+            try {
+                this.#ws.close();
+            }
+            catch {
+                /* ignore */
+            }
+            this.#ws = undefined;
+        }
+        this.#started = false;
+    }
+    async send({ target, payload }) {
+        const message = formatOutboundSegments(payload);
+        const { action, params } = buildSendAction(target, message);
+        const data = await this.callApi(action, params);
+        return data?.message_id != null ? String(data.message_id) : '';
+    }
+    callApi(action, params = {}) {
+        return callNapCatWsAction(this.#ws, this.#pending, this.#requestId, action, params);
+    }
+    admit(ev) {
+        if (!this.#open || !isMessageEvent(ev))
+            return;
+        if (isSelfMessage(ev))
+            return;
+        const msgId = String(ev.message_id);
+        if (!this.#inboundDeduper.shouldProcess(msgId))
+            return;
+        if (Array.isArray(ev.message) || typeof ev.message === 'string') {
+            ev = { ...ev, message: normalizeMessage(ev.message) };
+        }
+        const target = formatInboundTarget(ev);
+        const nickname = senderNickname(ev);
+        const mentioned = isNapCatBotMentioned(ev);
+        void this.#options.gateway.receive({
+            adapter: this.#options.id,
+            target,
+            content: formatInboundContent(ev),
+            sender: senderUserId(ev),
+            id: msgId,
+            metadata: Object.freeze({
+                message_type: ev.message_type,
+                user_id: ev.user_id != null ? String(ev.user_id) : undefined,
+                group_id: ev.group_id != null ? String(ev.group_id) : undefined,
+                endpoint: this.#options.config.name,
+                time: ev.time,
+                self_id: ev.self_id != null ? String(ev.self_id) : undefined,
+                role: ev.sender?.role,
+                ...(nickname ? { nickname } : {}),
+                ...(mentioned ? { mentioned: true } : {}),
+            }),
+        }).catch((err) => {
+            logger.warn(formatCompact({
+                op: 'napcat_gateway_receive_failed',
+                target,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
+    #acceptConnection(connection) {
+        if (!verifyNapCatAccessToken(this.#options.config.access_token, connection.request)) {
+            connection.socket.close(4003, 'Unauthorized');
+            return;
+        }
+        const socket = connection.socket;
+        if (this.#ws) {
+            try {
+                this.#ws.close();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        this.#ws = socket;
+        this.#heartbeatTimer = startNapCatHeartbeat(this.#ws, this.#options.config.heartbeat_interval, this.#heartbeatTimer);
+        socket.on('message', (data) => {
+            handleNapCatWsMessage(data, {
+                endpointName: this.#options.config.name,
+                pending: this.#pending,
+                admit: (event) => this.admit(event),
+            });
+        });
+        socket.on('close', () => {
+            if (this.#ws === socket) {
+                this.#ws = undefined;
+                if (this.#heartbeatTimer) {
+                    clearInterval(this.#heartbeatTimer);
+                    this.#heartbeatTimer = undefined;
+                }
+            }
+        });
+        logger.debug(formatCompact({
+            endpoint: this.#options.config.name,
+            mode: 'wss',
+            peer: connection.request.socket.remoteAddress,
+        }));
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zhin.js/adapter-napcat",
-  "version": "3.0.1",
-  "description": "Zhin.js adapter for NapCatQQ (OneBot11 superset with go-cqhttp & NapCat extensions)",
+  "version": "4.0.1",
+  "description": "Zhin.js NapCat adapter for Plugin Runtime (WebSocket client, OneBot11 + NapCat extensions)",
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -13,12 +13,12 @@
     }
   },
   "files": [
+    "adapters",
+    "plugin.ts",
+    "schema.json",
     "src",
     "lib",
-    "client",
-    "dist",
-    "skills",
-    "plugin.yml",
+    "agent",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -34,52 +34,53 @@
     "qq",
     "chatbot"
   ],
-  "author": {
-    "name": "lc-cn",
-    "email": "admin@liucl.cn",
-    "url": "https://github.com/lc-cn"
-  },
   "license": "MIT",
   "repository": {
-    "url": "git+https://github.com/zhinjs/zhin.git",
     "type": "git",
+    "url": "https://github.com/zhinjs/zhin",
     "directory": "plugins/adapters/napcat"
   },
   "dependencies": {
-    "ws": "^8.21.0"
+    "ws": "^8.21.0",
+    "@zhin.js/adapter": "1.0.1",
+    "@zhin.js/core": "1.3.5",
+    "@zhin.js/host-http": "1.0.1",
+    "@zhin.js/logger": "1.0.75",
+    "@zhin.js/plugin-runtime": "1.0.1"
   },
   "devDependencies": {
     "@types/node": "^26.1.0",
-    "@types/react": "^19.2.17",
-    "@types/react-dom": "^19.2.3",
     "@types/ws": "^8.18.1",
-    "lucide-react": "^1.22.0",
     "typescript": "^6.0.3",
-    "@zhin.js/cli": "1.0.92",
-    "@zhin.js/contract": "1.0.2",
-    "@zhin.js/agent": "1.0.2",
-    "@zhin.js/host-api": "2.0.4",
-    "@zhin.js/host-router": "2.0.2",
-    "zhin.js": "4.1.1"
+    "vitest": "^4.1.10",
+    "zod": "^4.4.3",
+    "@zhin.js/agent": "1.0.4",
+    "@zhin.js/host-http": "1.0.1"
   },
   "peerDependencies": {
-    "@zhin.js/contract": "1.0.2",
-    "@zhin.js/host-router": "2.0.2",
-    "@zhin.js/agent": "1.0.2",
-    "zhin.js": "4.1.1",
-    "@zhin.js/host-api": "2.0.4"
+    "zod": "^4.0.0",
+    "@zhin.js/adapter": "1.0.1",
+    "@zhin.js/core": "1.3.5",
+    "@zhin.js/plugin-runtime": "1.0.1",
+    "zhin.js": "4.1.3",
+    "@zhin.js/agent": "1.0.4"
   },
   "peerDependenciesMeta": {
-    "@zhin.js/agent": {
+    "zhin.js": {
       "optional": true
     },
-    "@zhin.js/host-api": {
+    "@zhin.js/agent": {
       "optional": true
     },
-    "@zhin.js/host-router": {
+    "zod": {
       "optional": true
     }
   },
+  "author": {
+    "name": "lc-cn",
+    "email": "admin@liucl.cn",
+    "url": "https://github.com/lc-cn"
+  },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
@@ -87,8 +88,23 @@
   "engines": {
     "node": "^20.19.0 || >=22.12.0"
   },
+  "zhin": {
+    "protocol": 1,
+    "type": "plugin",
+    "entry": "./plugin.ts",
+    "engine": "^1.0.0",
+    "runtime": "trusted",
+    "features": [
+      {
+        "package": "@zhin.js/adapter",
+        "api": "^1.0.0"
+      }
+    ],
+    "plugins": []
+  },
   "scripts": {
-    "build": "zhin build",
-    "clean": "rimraf lib"
+    "build": "tsc",
+    "clean": "rimraf lib",
+    "test": "NODE_OPTIONS=--experimental-strip-types vitest run --root ../../.. plugins/adapters/napcat/tests"
   }
 }

package/plugin.ts

@@ -0,0 +1,13 @@
+import { definePlugin } from '@zhin.js/plugin-runtime';
+import { registerDefaultScenePlatformPermitChecker } from '@zhin.js/core';
+
+export default definePlugin({
+  name: 'napcat',
+  metadata: {
+    displayName: 'NapCat Adapter',
+  },
+  setup() {
+    // 平台权限门禁：scene_admin / scene_owner 由 sender role 判定（见各 endpoint admit metadata）
+    return registerDefaultScenePlatformPermitChecker('napcat');
+  },
+});

package/schema.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "connection": {
+      "type": "string",
+      "enum": ["ws", "wss", "http"],
+      "default": "ws",
+      "description": "ws (default), wss (reverse WS), or http (POST webhook + HTTP API outbound)"
+    },
+    "name": {
+      "type": "string",
+      "default": "napcat-bot"
+    },
+    "url": {
+      "type": "string",
+      "description": "NapCat WebSocket URL (required for connection: ws)"
+    },
+    "path": {
+      "type": "string",
+      "description": "WS path for reverse-wss"
+    },
+    "http_url": {
+      "type": "string",
+      "description": "HTTP API base URL (connection: http outbound)"
+    },
+    "post_path": {
+      "type": "string",
+      "description": "HTTP POST event path (connection: http inbound)"
+    },
+    "access_token": {
+      "type": "string"
+    },
+    "reconnect_interval": {
+      "type": "number",
+      "default": 5000
+    },
+    "heartbeat_interval": {
+      "type": "number",
+      "default": 30000
+    },
+    "poll_interval": {
+      "type": "number",
+      "default": 30000
+    }
+  }
+}

package/src/http-endpoint.ts

@@ -0,0 +1,197 @@
+/**
+ * NapCat HTTP endpoint — POST inbound events + HTTP API outbound.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { EndpointInstance } from '@zhin.js/adapter';
+import type { MessageGateway } from '@zhin.js/core/runtime';
+import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import type { CapabilityId } from '@zhin.js/plugin-runtime';
+import { registerNapcatAgentEndpoint } from './napcat-agent-deps.js';
+import {
+  InboundMessageDeduper,
+  isNapCatBotMentioned,
+  isSelfMessage,
+  normalizeMessage,
+} from './napcat-inbound.js';
+import {
+  buildSendAction,
+  callNapCatHttpAction,
+  formatInboundContent,
+  formatInboundTarget,
+  formatOutboundSegments,
+  isMessageEvent,
+  senderNickname,
+  senderUserId,
+  type NapCatEvent,
+  type NapCatHttpConfig,
+} from './protocol.js';
+import { readRequestBody } from './webhook.js';
+import { NapCatWsEndpoint } from './ws-endpoint.js';
+import { verifyNapCatAccessToken } from './wss-auth.js';
+
+const logger = getLogger('napcat');
+
+export interface NapCatHttpEndpointOptions {
+  readonly id: CapabilityId;
+  readonly gateway: MessageGateway;
+  readonly http: HttpHost;
+  readonly config: NapCatHttpConfig;
+  readonly callHttpAction?: typeof callNapCatHttpAction;
+}
+
+export class NapCatHttpEndpoint implements EndpointInstance {
+  readonly #options: NapCatHttpEndpointOptions;
+  readonly #inboundDeduper = new InboundMessageDeduper();
+  readonly #callHttpAction: typeof callNapCatHttpAction;
+  #routeReleases: HttpRouteRegistration[] = [];
+  #open = false;
+  #started = false;
+  #unregisterAgent?: () => void;
+
+  constructor(options: NapCatHttpEndpointOptions) {
+    this.#options = options;
+    this.#callHttpAction = options.callHttpAction ?? callNapCatHttpAction;
+  }
+
+  async start(): Promise<void> {
+    if (this.#started) return;
+    this.#started = true;
+    this.#unregisterAgent = registerNapcatAgentEndpoint(
+      this.#options.config.name,
+      this as unknown as NapCatWsEndpoint,
+    );
+    this.#setupRoutes();
+    logger.info(formatCompact({
+      op: 'listen',
+      endpoint: this.#options.config.name,
+      mode: 'http',
+      path: this.#options.config.post_path,
+    }));
+  }
+
+  open(): void {
+    this.#open = true;
+  }
+
+  close(): void {
+    this.#open = false;
+  }
+
+  async stop(): Promise<void> {
+    this.#open = false;
+    for (const release of this.#routeReleases.splice(0)) release();
+    this.#unregisterAgent?.();
+    this.#unregisterAgent = undefined;
+    this.#inboundDeduper.clear();
+    this.#started = false;
+    logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
+  }
+
+  async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
+    const message = formatOutboundSegments(payload);
+    const { action, params } = buildSendAction(target, message);
+    const resp = await this.#callHttpAction(
+      {
+        http_url: this.#options.config.http_url,
+        access_token: this.#options.config.access_token,
+      },
+      action,
+      params,
+    );
+    const data = resp.data as { message_id?: number | string } | undefined;
+    const messageId = data?.message_id != null ? String(data.message_id) : '';
+    logger.debug(formatCompact({
+      op: 'napcat_send',
+      endpoint: this.#options.config.name,
+      target,
+      messageId,
+    }));
+    return messageId;
+  }
+
+  callApi(action: string, params: Record<string, unknown> = {}): Promise<unknown> {
+    return this.#callHttpAction(
+      {
+        http_url: this.#options.config.http_url,
+        access_token: this.#options.config.access_token,
+      },
+      action,
+      params,
+    ).then((resp) => resp.data);
+  }
+
+  admit(ev: NapCatEvent): void {
+    if (!this.#open || !isMessageEvent(ev)) return;
+    if (isSelfMessage(ev)) return;
+    const msgId = String(ev.message_id);
+    if (!this.#inboundDeduper.shouldProcess(msgId)) return;
+    if (Array.isArray(ev.message) || typeof ev.message === 'string') {
+      ev = { ...ev, message: normalizeMessage(ev.message) };
+    }
+    const target = formatInboundTarget(ev);
+    const nickname = senderNickname(ev);
+    const mentioned = isNapCatBotMentioned(ev);
+    void this.#options.gateway.receive({
+      adapter: this.#options.id,
+      target,
+      content: formatInboundContent(ev),
+      sender: senderUserId(ev),
+      id: msgId,
+      metadata: Object.freeze({
+        message_type: ev.message_type,
+        user_id: ev.user_id != null ? String(ev.user_id) : undefined,
+        group_id: ev.group_id != null ? String(ev.group_id) : undefined,
+        endpoint: this.#options.config.name,
+        time: ev.time,
+        self_id: ev.self_id != null ? String(ev.self_id) : undefined,
+        role: ev.sender?.role,
+        ...(nickname ? { nickname } : {}),
+        ...(mentioned ? { mentioned: true } : {}),
+      }),
+    }).catch((err) => {
+      logger.warn(formatCompact({
+        op: 'napcat_gateway_receive_failed',
+        target,
+        error: err instanceof Error ? err.message : String(err),
+      }));
+    });
+  }
+
+  #setupRoutes(): void {
+    const path = this.#options.config.post_path;
+    this.#routeReleases.push(
+      this.#options.http.route('POST', path, async (request, response) => {
+        await this.#handlePost(request, response);
+      }, { summary: 'NapCat HTTP event callback', tags: ['napcat'] }),
+    );
+  }
+
+  async #handlePost(request: IncomingMessage, response: ServerResponse): Promise<void> {
+    try {
+      if (!verifyNapCatAccessToken(this.#options.config.access_token, request)) {
+        response.writeHead(403, { 'Content-Type': 'application/json' });
+        response.end(JSON.stringify({ message: 'Unauthorized' }));
+        return;
+      }
+      const raw = await readRequestBody(request);
+      let ev: NapCatEvent;
+      try {
+        ev = JSON.parse(raw) as NapCatEvent;
+      } catch {
+        response.writeHead(400, { 'Content-Type': 'application/json' });
+        response.end(JSON.stringify({ message: 'Invalid JSON' }));
+        return;
+      }
+      if (this.#open) this.admit(ev);
+      response.writeHead(200, { 'Content-Type': 'application/json' });
+      response.end(JSON.stringify({ status: 'ok' }));
+    } catch (error) {
+      logger.error('NapCat HTTP webhook error:', error);
+      if (!response.headersSent) {
+        response.writeHead(500, { 'Content-Type': 'application/json' });
+        response.end(JSON.stringify({ message: 'Internal Server Error' }));
+      }
+    }
+  }
+}