@zhin.js/adapter-kook 1.1.4 → 1.1.6

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # @zhin.js/adapter-kook
 
+## 1.1.6
+
+### Patch Changes
+
+- 2cdb181: Upgrade kook-client to ^1.0.5 and qq-official-bot to ^1.3.1, which include the upstream lifecycle and upload fixes. Remove local SDK patches and validate the published SDK directly in regression fixtures.
+- Updated dependencies [badcc1f]
+  - @zhin.js/core@1.1.41
+  - @zhin.js/feature-kit@1.1.3
+  - @zhin.js/adapter@1.1.17
+  - @zhin.js/agent-feature@1.1.4
+  - @zhin.js/skill@1.1.4
+  - @zhin.js/tool@1.1.4
+  - @zhin.js/host-http@1.1.4
+  - @zhin.js/permission@1.1.4
+
+## 1.1.5
+
+### Patch Changes
+
+- b9b3953: Add an opt-in fixed-loopback JSON API fault proxy through the actual SDK Axios HTTPS agent. Preserve the canonical www.kookapp.cn identity and TLS validation, refuse other destinations and redirects, and keep media fetch uploads outside this proxy scope.
+- b9b3953: canonical reply 映射原生 quote。图片经原生二进制 multipart 上传，图文混排用卡片保持顺序，修复仅显示 [image] 或丢失文本；上传失败不发文字替代，缺真实消息 ID 不确认成功，日志错误不携带原始平台响应。
+
+  撤回使用完整会话路由调用真实频道/私聊删除接口，修复不存在 recallMsg 方法被 optional no-op 当作成功的问题；false 回执和缺失方法明确失败。
+
+- b9b3953: Expose the actual KOOK SDK WebSocket receiver state to adapter health, including open, reconnecting and closed transitions, rather than leaving connected bots unobserved.
+- b9b3953: 兼容 API 错误规范化后的黑名单预加载权限拒绝。仅在启动预加载的黑名单接口明确返回 403 时跳过该可选资源；其他鉴权、网络失败和运行期调用继续报错。
+- b9b3953: Preserve inbound message identity and routing when kook-client user or channel cache enrichment getters throw. Missing cached display names and roles no longer discard incoming messages.
+
+  Allow message transport startup when optional blacklist cache preloading is explicitly denied with HTTP 403. Explicit blacklist management requests and other startup failures still propagate.
+
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+  - @zhin.js/adapter@1.1.16
+  - @zhin.js/im-contract@1.1.3
+  - @zhin.js/core@1.1.40
+  - @zhin.js/host-http@1.1.3
+  - @zhin.js/tool@1.1.3
+  - @zhin.js/skill@1.1.3
+  - @zhin.js/agent-feature@1.1.3
+
 ## 1.1.4
 
 ### Patch Changes

package/README.md

@@ -95,7 +95,11 @@ platform permit checker 由 `plugin.ts` 的 generation 生命周期注册；Capa
 
 ## 迁移后出站能力变化
 
-迁移到 Plugin Runtime 后，出站统一经 `outboundMessageToken` 渲染并由 endpoint 编码为 KMarkdown（`sendChannelMsg` / `sendPrivateMsg`）。canonical `markdown` 保留格式；图片、视频、音频和文件仅有远程 URL 时可表示为 KMarkdown 链接。卡片消息与附件上传仍未接入统一出站通道。
+出站统一经 `outboundMessageToken` 渲染。canonical `markdown` 保留 KMarkdown；图片上传后以原生卡片保留图文混排；canonical `reply` 通过 SDK quote 参数传递。视频、音频和文件 URL 表示为链接，本地这些文件的上传尚未接线。
+
+canonical `keyboard` 映射为原生 Card `action-group`，每行 1–4 个按钮，`click: return-val` 将 payload 原样返回。WebSocket 和 Webhook 的 `message_btn_click` 事件进入可靠的 canonical `action` 消息段，携带实际点击人、会话和 `sourceMessageId`。按钮显示成功不能算交互通过，必须实际点击并核对回调。disabled 和 command 模式按钮当前明确 `unsupported_operation`。官方合同：[卡片按钮](https://developer.kookapp.cn/doc/cardmessage)、[按钮点击事件](https://developer.kookapp.cn/doc/event/user)。
+
+canonical `share` 映射为含标题、描述/正文与“打开链接”按钮的 Card；只支持 HTTP(S) URL，不代表平台原生应用/音乐名片。share 的 image/audio/app metadata 尚未接线，明确拒绝。实机分享验收需核对标题、描述与点击后的目标 URL。
 
 ## 故障排查
 
@@ -109,3 +113,28 @@ platform permit checker 由 `plugin.ts` 的 generation 生命周期注册；Capa
 ## 许可证
 
 MIT License
+
+### 图片与引用
+
+canonical reply 使用原生 `quote`，关联原消息 ID。canonical 图片（URL、本地路径、base64）先上传到 KOOK asset 接口，再用原生卡片发送；图片与文本混排按原顺序保留。上传失败不会用文字代替并确认成功，缺失真实消息 ID 为 unknown。文件/音视频暂仅支持既有 URL 链接，二进制上传会明确拒绝。
+
+撤回通过 canonical control 的完整 MessageRef 区分频道与私聊，并调用对应正式删除接口。transport 未实现删除或平台返回 false 时明确失败，不允许静默成功；直接调用 `recallMessage` 须同时传入 ConversationRef。
+# WSS 可控故障验收
+
+`kook-client@1.0.5` 已在上游提供可选 `socketFactory`、`autoReconnect` 与 `handleProcessErrors`，无需本地 pnpm 补丁。Zhin 显式设置 `handleProcessErrors: false`，让框架管理进程错误，不扫描或删除其他全局监听。Zhin 关闭 SDK 内部重连/DNS 监视，由统一 Endpoint lifecycle 负责 start/stop/reconnect，SDK 保留协议心跳和事件转换。停止会取消 pending hello，迟到 discovery 不会再建连接。
+
+可选 `streamProxy: { port: 18443, serverName: "实际网关域名" }` 仅改 TCP 路由到 `127.0.0.1`，真实 WSS URL、Host、SNI 和证书链/域名校验保留；网关变化拒绝并只记录安全 hostname，不输出私有 URL/query 或回退直连。验收项目支持 `KOOK_STREAM_PROXY_PORT` / `KOOK_STREAM_PROXY_SERVER_NAME` 临时进程覆盖，需同时提供，留空正常直连。先以占位域名获取安全日志中的实际 gateway hostname，随后启动固定上游 `tcp-fault-proxy.mjs --upstream-host 实际网关域名 --upstream-port 443 --port 18443 --control-port 18444` 并同步 serverName，不覆盖已有 `.env`。
+
+正常入站后 POST `/cut`，观察 SDK断线和 lifecycle离开 open；POST `/recover` 后等待新连接 open，再发送唯一新 probe确认真实入站及可见回包。切断仅 WSS；HTTP discovery/出站仍直连，不能据此证明所有网络恢复、离线事件无损或发送重试。停止代理并移除临时覆盖后恢复常规运行。本地实际SDK/TLS回归与平台实机证据分开记录。
+
+受控重连使用原会话 URL、已处理 SN 与 session_id 恢复。收到 Resume ACK 前缓存离线事件；确认后依 SN 连续顺序派发，重复事件不再次进入业务链。服务器要求新会话时清除旧 SN 和未派发数据，重新发现网关并初始化缓存。已初始化会话恢复成功时复用路由缓存，避免重复加载成员；停止会取消 Hello/Resume 等待和后续重连。上述本地 TLS 回归不替代真实平台 cut/recover 验收。
+
+### 出站 HTTP 结果
+
+HTTP 408 与所有 5xx 保持 unknown，即使正文包含拒绝码也不认定明确未发送；其他 4xx 和成功 HTTP 响应中的非零平台 code 为 rejected。Runtime 在 Axios 正式 transformResponse 阶段保留 HTTP 状态语义，避免 SDK 错误转换丢掉状态。真实已安装 SDK + loopback HTTP fixture 验证单次 POST、不自动重发。Stream 故障代理不影响出站 API；API 专用测试需另行配置 Axios httpsAgent 固定 loopback 转发，并保持实际域名/SNI/证书校验，当前验收配置尚未暴露。
+
+### JSON API 故障验收代理
+
+可选 `apiProxy: { port: 18580 }` 使用 SDK Axios 实例正式 `httpsAgent` 扩展，仅将 `www.kookapp.cn:443` 的 TCP 路由到 `127.0.0.1`；原 Host、SNI、证书链及域名验证保留，拒绝其他目标和重定向，无自动直连回退。默认关闭。它与 `streamProxy` 独立，覆盖 SDK JSON API（含网关查询、初始化、消息发送/撤回），不覆盖适配器的 fetch 图片上传及外部媒体下载。Axios 正式 agent 配置见 https://axios-http.com/docs/req_config 。
+
+启动固定上游代理：`node scripts/platform-acceptance/tcp-fault-proxy.mjs --upstream-host www.kookapp.cn --upstream-port 443 --port 18580 --control-port 18581`。验收项目可用 `KOOK_API_PROXY_PORT=18580 pnpm --filter platform-acceptance-bot dev:kook` 临时覆盖；不改 `.env`。POST 已提交后断线只能记 unknown，不自动重发；恢复后使用新探针样本。

package/adapters/kook/index.js

@@ -12,11 +12,11 @@ export { KookWebhookEndpoint, KookWebsocketEndpoint, } from "../../lib/endpoint.
 export default defineAdapter({
     capabilities: ['inbound', 'outbound'],
     operations: ['recall'],
-    // KOOK 图片消息消费远程 URL；KMarkdown 由 endpoint codec 原生消费；
-    // 无按钮交互面，交互段降级纯文本。
+    // KOOK 图片上传后以原生卡片保留图文混排；KMarkdown 原生消费；
+    // 原生卡片按钮经 return-val 事件进入 canonical action 链路。
     segments: {
-        outboundMedia: ['url'],
-        interactive: 'text',
+        outboundMedia: ['url', 'upload'],
+        interactive: 'native',
         markdown: 'native',
     },
     create(context) {

package/adapters/kook/index.ts

@@ -27,11 +27,11 @@ export type { CreateKookClient, KookClientTransport } from '../../src/ws.js';
 export default defineAdapter<KookEndpointConfig>({
   capabilities: ['inbound', 'outbound'],
   operations: ['recall'],
-  // KOOK 图片消息消费远程 URL；KMarkdown 由 endpoint codec 原生消费；
-  // 无按钮交互面，交互段降级纯文本。
+  // KOOK 图片上传后以原生卡片保留图文混排；KMarkdown 原生消费；
+  // 原生卡片按钮经 return-val 事件进入 canonical action 链路。
   segments: {
-    outboundMedia: ['url'],
-    interactive: 'text',
+    outboundMedia: ['url', 'upload'],
+    interactive: 'native',
     markdown: 'native',
   },
   create(context) {

package/lib/api-proxy.d.ts

@@ -0,0 +1,6 @@
+import { Agent } from 'node:https';
+export interface KookApiProxy {
+    readonly port: number;
+}
+/** JSON Web API only: keep www.kookapp.cn identity, route TCP to a fixed loopback port. */
+export declare function createKookApiAgent(proxy: KookApiProxy): Agent;

package/lib/api-proxy.js

@@ -0,0 +1,18 @@
+import { Agent } from 'node:https';
+import tls from 'node:tls';
+import { Socket } from 'node:net';
+/** JSON Web API only: keep www.kookapp.cn identity, route TCP to a fixed loopback port. */
+export function createKookApiAgent(proxy) {
+    const agent = new Agent({ keepAlive: false });
+    agent.createConnection = options => {
+        const hostname = String(options.hostname ?? options.host ?? '');
+        if (hostname !== 'www.kookapp.cn' || Number(options.port ?? 443) !== 443) {
+            const rejected = new Socket();
+            queueMicrotask(() => rejected.destroy(new Error('KOOK JSON API proxy rejected destination identity')));
+            return rejected;
+        }
+        return tls.connect({ ...options, path: undefined,
+            host: '127.0.0.1', port: proxy.port, servername: 'www.kookapp.cn', rejectUnauthorized: true });
+    };
+    return agent;
+}

package/lib/endpoint.d.ts

@@ -1,5 +1,5 @@
-import { Endpoint } from 'zhin.js/adapter';
-import { type EndpointControl, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
+import { type ConversationRef } from '@zhin.js/im-contract';
+import { Endpoint, type EndpointControl, type EndpointManagement, type EndpointSendRequest, type EndpointTransportState } from 'zhin.js/adapter';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from 'zhin.js';
 import { type KookInboundMessage, type KookWebhookEventData, type ResolvedKookWebhookConfig, type ResolvedKookWebsocketConfig } from './protocol.js';
@@ -15,6 +15,7 @@ export declare class KookWebsocketEndpoint extends Endpoint<KookClientTransport>
     readonly control: EndpointControl;
     constructor(options: KookEndpointOptions);
     get client(): KookClientTransport;
+    get transportState(): EndpointTransportState | undefined;
     start(): Promise<void>;
     open(): void;
     close(): void;
@@ -22,7 +23,8 @@ export declare class KookWebsocketEndpoint extends Endpoint<KookClientTransport>
     send({ conversation, payload }: EndpointSendRequest): Promise<string>;
     /** Test / internal: admit a normalized message when open. */
     admit(msg: KookInboundMessage): void;
-    recallMessage(messageId: string): Promise<void>;
+    recallMessage(messageId: string, conversation?: ConversationRef): Promise<void>;
+    admitButton(raw: unknown): Promise<void>;
 }
 export interface KookWebhookEndpointOptions {
     readonly id: CapabilityId;
@@ -45,11 +47,12 @@ export declare class KookWebhookEndpoint extends Endpoint<KookClientTransport> {
     close(): void;
     stop(): Promise<void>;
     send({ conversation, payload }: EndpointSendRequest): Promise<string>;
-    admitEvent(event: KookWebhookEventData): void;
+    admitEvent(event: KookWebhookEventData): Promise<void>;
     /** Test / internal: admit a message when open. */
     admit(msg: KookInboundMessage): void;
-    recallMessage(messageId: string): Promise<void>;
+    recallMessage(messageId: string, conversation?: ConversationRef): Promise<void>;
     checkAndRememberSn(sn: number): boolean;
+    forgetSn(sn: number): void;
 }
 /**
  * KOOK endpoint 的 EndpointManagement 语义端口（websocket / webhook 共用）。

package/lib/endpoint.js

@@ -1,11 +1,13 @@
-import { Endpoint } from 'zhin.js/adapter';
-import { createRecallEndpointControl, } from 'zhin.js/adapter';
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
+import { Endpoint, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
-import { formatInboundContent, formatOutboundKmarkdown, isKookBotMentioned, kookInboundConversation, normalizeKookWebhookEvent, senderDisplayName, } from './protocol.js';
+import { formatInboundContent, isKookBotMentioned, kookInboundConversation, normalizeKookWebhookEvent, normalizeKookButtonEvent, senderDisplayName, } from './protocol.js';
 import { registerKookWebhookRoutes } from './webhook.js';
 import { defaultCreateClient, defaultCreateWebhookClient, normalizeKookMessage, } from './ws.js';
+import { recallKookMessage, sendKookOutbound } from './outbound.js';
 import { receiveKookSideEvent } from './side-event-dispatch.js';
 export class KookWebsocketEndpoint extends Endpoint {
+    #sentConversations = new Map();
     #logger;
     #options;
     #createClient;
@@ -13,7 +15,9 @@ export class KookWebsocketEndpoint extends Endpoint {
     #open = false;
     #started = false;
     management = createKookEndpointManagement(() => this.#requireClient());
-    control = createRecallEndpointControl((id) => this.recallMessage(id));
+    control = Object.freeze({
+        recall: (message) => recallKookMessage(this.#requireClient(), message),
+    });
     constructor(options) {
         super();
         this.#logger = getAdapterLogger('kook', options.config.id);
@@ -23,6 +27,11 @@ export class KookWebsocketEndpoint extends Endpoint {
     get client() {
         return this.#requireClient();
     }
+    get transportState() {
+        if (!this.#started)
+            return 'stopped';
+        return this.#client?.getTransportState?.();
+    }
     async start() {
         if (this.#started)
             return;
@@ -52,6 +61,7 @@ export class KookWebsocketEndpoint extends Endpoint {
     }
     async stop() {
         this.#open = false;
+        this.#sentConversations.clear();
         if (this.#client) {
             try {
                 this.#client.removeAllListeners();
@@ -66,12 +76,8 @@ export class KookWebsocketEndpoint extends Endpoint {
         this.#logger.debug(formatCompact({ op: 'disconnect' }));
     }
     async send({ conversation, payload }) {
-        const body = formatOutboundKmarkdown(payload);
-        const client = this.#requireClient();
-        const result = conversation.kind === 'private'
-            ? await client.sendPrivateMsg(conversation.id, body)
-            : await client.sendChannelMsg(conversation.id, body);
-        const messageId = result?.msg_id != null ? String(result.msg_id) : '';
+        const messageId = await sendKookOutbound(this.#requireClient(), { conversation, payload });
+        rememberKookConversation(this.#sentConversations, messageId, conversation);
         this.#logger.debug(formatCompact({
             op: 'kook_send',
             endpoint: this.#options.config.id,
@@ -113,10 +119,10 @@ export class KookWebsocketEndpoint extends Endpoint {
             }));
         });
     }
-    async recallMessage(messageId) {
-        if (!messageId)
-            return;
-        await this.#requireClient().recallMsg?.(messageId);
+    async recallMessage(messageId, conversation) {
+        if (!conversation)
+            throw new EndpointDeliveryError('unsupported_operation', 'KOOK recall requires conversation routing', 'rejected');
+        await recallKookMessage(this.#requireClient(), { id: messageId, conversation });
     }
     #bindClient(client) {
         client.on('message', (raw) => {
@@ -127,10 +133,24 @@ export class KookWebsocketEndpoint extends Endpoint {
         });
         const receiver = client.receiver;
         receiver?.on('event', (raw) => {
+            if (this.#client !== client || !this.#open)
+                return;
             this.#emitPlatformEvent('event', raw);
+            if (normalizeKookButtonEvent(raw)) {
+                void this.admitButton(raw).catch(error => this.#logger.warn(formatCompact({ op: 'kook_button_failed', error: error instanceof Error ? error.message : 'dispatch failed' })));
+                return;
+            }
             receiveKookSideEvent((name, payload) => this.emit(name, payload), this.#options.config.id, raw, this.#logger);
         });
     }
+    async admitButton(raw) {
+        if (!this.#open)
+            throw new Error('KOOK endpoint is closed');
+        const event = normalizeKookButtonEvent(raw);
+        if (!event)
+            throw new Error('Invalid KOOK button event');
+        await this.emitAccepted('message.receive', kookButtonIngress(String(this.#options.id), this.#options.config.id, event, this.#sentConversations.get(event.sourceMessageId)));
+    }
     #emitPlatformEvent(name, event) {
         void this.emitPlatform(name, event).catch((error) => {
             this.#logger.warn(formatCompact({
@@ -147,6 +167,7 @@ export class KookWebsocketEndpoint extends Endpoint {
     }
 }
 export class KookWebhookEndpoint extends Endpoint {
+    #sentConversations = new Map();
     #logger;
     #options;
     #createClient;
@@ -156,7 +177,9 @@ export class KookWebhookEndpoint extends Endpoint {
     #open = false;
     #started = false;
     management = createKookEndpointManagement(() => this.#requireClient());
-    control = createRecallEndpointControl((id) => this.recallMessage(id));
+    control = Object.freeze({
+        recall: (message) => recallKookMessage(this.#requireClient(), message),
+    });
     constructor(options) {
         super();
         this.#logger = getAdapterLogger('kook', options.config.id);
@@ -206,6 +229,7 @@ export class KookWebhookEndpoint extends Endpoint {
     }
     async stop() {
         this.#open = false;
+        this.#sentConversations.clear();
         for (const release of this.#routeReleases.splice(0))
             release();
         this.#processedSn.clear();
@@ -223,12 +247,8 @@ export class KookWebhookEndpoint extends Endpoint {
         this.#logger.debug(formatCompact({ op: 'disconnect' }));
     }
     async send({ conversation, payload }) {
-        const body = formatOutboundKmarkdown(payload);
-        const client = this.#requireClient();
-        const result = conversation.kind === 'private'
-            ? await client.sendPrivateMsg(conversation.id, body)
-            : await client.sendChannelMsg(conversation.id, body);
-        const messageId = result?.msg_id != null ? String(result.msg_id) : '';
+        const messageId = await sendKookOutbound(this.#requireClient(), { conversation, payload });
+        rememberKookConversation(this.#sentConversations, messageId, conversation);
         this.#logger.debug(formatCompact({
             op: 'kook_send',
             endpoint: this.#options.config.id,
@@ -237,7 +257,14 @@ export class KookWebhookEndpoint extends Endpoint {
         }));
         return messageId;
     }
-    admitEvent(event) {
+    async admitEvent(event) {
+        if (normalizeKookButtonEvent(event)) {
+            if (!this.#open)
+                throw new Error('KOOK endpoint is closed');
+            const button = normalizeKookButtonEvent(event);
+            await this.emitAccepted('message.receive', kookButtonIngress(String(this.#options.id), this.#options.config.id, button, this.#sentConversations.get(button.sourceMessageId)));
+            return;
+        }
         void this.emitPlatform(String(event.type ?? 'event'), event).catch((error) => {
             this.#logger.warn(formatCompact({
                 op: 'kook_platform_event_failed',
@@ -287,10 +314,10 @@ export class KookWebhookEndpoint extends Endpoint {
             }));
         });
     }
-    async recallMessage(messageId) {
-        if (!messageId)
-            return;
-        await this.#requireClient().recallMsg?.(messageId);
+    async recallMessage(messageId, conversation) {
+        if (!conversation)
+            throw new EndpointDeliveryError('unsupported_operation', 'KOOK recall requires conversation routing', 'rejected');
+        await recallKookMessage(this.#requireClient(), { id: messageId, conversation });
     }
     checkAndRememberSn(sn) {
         if (this.#processedSn.has(sn))
@@ -303,6 +330,7 @@ export class KookWebhookEndpoint extends Endpoint {
         }
         return true;
     }
+    forgetSn(sn) { this.#processedSn.delete(sn); }
     #requireClient() {
         if (!this.#client)
             throw new Error('KOOK client not initialized');
@@ -319,6 +347,20 @@ function toGroupId(id) {
     return id;
 }
 /** KOOK 文字频道标记：HTTP API type=1（2=语音），kook-client 消息侧用 'GROUP'。 */
+function rememberKookConversation(cache, messageId, conversation) {
+    cache.set(messageId, conversation);
+    while (cache.size > 2048)
+        cache.delete(cache.keys().next().value);
+}
+function kookButtonIngress(endpointKey, endpointId, event, sentConversation) {
+    const conversation = { endpoint: { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey },
+        kind: sentConversation?.kind ?? event.channelKind, id: sentConversation?.id ?? event.channelId,
+        ...(sentConversation?.parent ? { parent: sentConversation.parent } : {}) };
+    return { conversation, message: { conversation, id: event.id }, content: `[action: ${event.payload}]`,
+        segments: [{ type: 'action', data: { id: event.id, payload: event.payload, sourceMessageId: event.sourceMessageId } }],
+        sender: { id: event.userId }, endpointId,
+        metadata: Object.freeze({ eventType: 'message_btn_click', payload: event.payload, sourceMessageId: event.sourceMessageId, timestamp: event.timestamp }) };
+}
 function isKookTextChannelType(type) {
     return type === 1 || type === '1' || type === 'GROUP';
 }

package/lib/outbound.d.ts

@@ -0,0 +1,7 @@
+import { type MessageRef } from '@zhin.js/im-contract';
+import type { EndpointSendRequest } from 'zhin.js/adapter';
+import type { KookClientTransport } from './ws.js';
+/** Native cards preserve mixed text/images; SDK's ordinary segments stop at first media. */
+export declare function sendKookOutbound(client: KookClientTransport, { conversation, payload }: EndpointSendRequest): Promise<string>;
+/** Deletion requires the canonical conversation: KOOK has separate channel/private APIs. */
+export declare function recallKookMessage(client: KookClientTransport, message: MessageRef): Promise<void>;

package/lib/outbound.js

@@ -0,0 +1,141 @@
+import { readFile } from 'node:fs/promises';
+import { EndpointDeliveryError, isMediaRef } from '@zhin.js/im-contract';
+import { formatOutboundKmarkdown } from './protocol.js';
+/** Native cards preserve mixed text/images; SDK's ordinary segments stop at first media. */
+export async function sendKookOutbound(client, { conversation, payload }) {
+    try {
+        const items = Array.isArray(payload) ? payload : payload && typeof payload === 'object' ? [payload] : [payload];
+        let quote;
+        const modules = [];
+        let hasImage = false;
+        let hasCard = false;
+        for (const item of items) {
+            if (item && typeof item === 'object' && item.type === 'reply') {
+                if (typeof item.data?.message_id === 'string' && item.data.message_id.trim())
+                    quote = { message_id: item.data.message_id };
+                continue;
+            }
+            if (item && typeof item === 'object' && item.type === 'keyboard') {
+                hasCard = true;
+                const rows = item.data?.rows;
+                if (!Array.isArray(rows) || !rows.length)
+                    throw new EndpointDeliveryError('invalid_payload', 'KOOK keyboard requires button rows', 'not_sent');
+                for (const row of rows) {
+                    if (!Array.isArray(row) || !row.length || row.length > 4)
+                        throw new EndpointDeliveryError('invalid_payload', 'KOOK button rows require 1-4 buttons', 'not_sent');
+                    const elements = row.map(button => {
+                        if (!button || typeof button !== 'object' || typeof button.label !== 'string' || !button.label.trim() || typeof button.payload !== 'string' || !button.payload)
+                            throw new EndpointDeliveryError('invalid_payload', 'KOOK buttons require label and payload', 'not_sent');
+                        if (button.disabled || button.mode === 'command')
+                            throw new EndpointDeliveryError('unsupported_operation', 'KOOK disabled/command buttons are not implemented', 'not_sent');
+                        return { type: 'button', theme: button.style === 'danger' ? 'danger' : button.style === 'primary' ? 'primary' : 'secondary',
+                            value: button.payload, click: 'return-val', text: { type: 'plain-text', content: button.label } };
+                    });
+                    modules.push({ type: 'action-group', elements });
+                }
+            }
+            else if (item && typeof item === 'object' && item.type === 'share') {
+                hasCard = true;
+                const data = item.data ?? {};
+                let url;
+                try {
+                    url = new URL(data.url);
+                }
+                catch {
+                    throw new EndpointDeliveryError('invalid_payload', 'KOOK share requires an HTTP(S) URL', 'not_sent');
+                }
+                if (!['http:', 'https:'].includes(url.protocol) || typeof data.title !== 'string' || !data.title.trim())
+                    throw new EndpointDeliveryError('invalid_payload', 'KOOK share requires URL and title', 'not_sent');
+                if (['image', 'audio', 'artist', 'duration', 'config'].some(key => data[key] !== undefined))
+                    throw new EndpointDeliveryError('unsupported_operation', 'KOOK share media/app metadata is not implemented', 'not_sent');
+                modules.push({ type: 'section', mode: 'left', text: { type: 'plain-text', content: data.title } });
+                for (const value of [data.description, data.content])
+                    if (typeof value === 'string' && value)
+                        modules.push({ type: 'section', mode: 'left', text: { type: 'plain-text', content: value } });
+                modules.push({ type: 'action-group', elements: [{ type: 'button', theme: 'secondary', click: 'link', value: url.href, text: { type: 'plain-text', content: '打开链接' } }] });
+            }
+            else if (item && typeof item === 'object' && item.type === 'image') {
+                hasImage = true;
+                const media = item.data?.media;
+                if (!isMediaRef(media))
+                    throw new EndpointDeliveryError('unsupported_media', 'KOOK image requires canonical media', 'rejected');
+                let url;
+                if (media.kind === 'file')
+                    url = media.value;
+                else {
+                    if (!client.uploadMedia)
+                        throw new EndpointDeliveryError('unsupported_media', 'KOOK transport cannot upload images', 'rejected');
+                    let bytes;
+                    if (media.kind === 'base64')
+                        bytes = Buffer.from(media.value.replace(/^data:[^,]*,/, ''), 'base64');
+                    else if (media.kind === 'path')
+                        bytes = await readFile(media.value);
+                    else {
+                        const response = await fetch(media.value, { signal: AbortSignal.timeout(30_000) });
+                        if (!response.ok)
+                            throw new EndpointDeliveryError('media_download_failed', 'KOOK media download failed', 'rejected');
+                        bytes = Buffer.from(await response.arrayBuffer());
+                    }
+                    url = await client.uploadMedia(bytes);
+                }
+                if (typeof url !== 'string' || !/^https:\/\//.test(url))
+                    throw new EndpointDeliveryError('delivery_unconfirmed', 'KOOK upload returned no media URL', 'unknown');
+                modules.push({ type: 'container', elements: [{ type: 'image', src: url, alt: String(item.data?.alt ?? 'image') }] });
+            }
+            else {
+                if (item && typeof item === 'object' && ['file', 'audio', 'video'].includes(item.type)
+                    && isMediaRef(item.data?.media) && !['url', 'file'].includes(item.data.media.kind)) {
+                    throw new EndpointDeliveryError('unsupported_media', 'KOOK binary uploads currently support images only', 'rejected');
+                }
+                const text = formatOutboundKmarkdown([item]);
+                if (text)
+                    modules.push({ type: 'section', mode: 'left', text: { type: 'kmarkdown', content: text } });
+            }
+        }
+        const body = hasImage || hasCard ? { __isCard: true, type: 'card', theme: 'secondary', size: 'lg', modules } : formatOutboundKmarkdown(payload);
+        const result = conversation.kind === 'private'
+            ? await client.sendPrivateMsg(conversation.id, body, quote)
+            : await client.sendChannelMsg(conversation.id, body, quote);
+        const id = result?.msg_id != null ? String(result.msg_id) : '';
+        if (!id.trim())
+            throw new EndpointDeliveryError('delivery_unconfirmed', 'KOOK did not return a real message ID', 'unknown');
+        return id;
+    }
+    catch (error) {
+        if (error instanceof EndpointDeliveryError)
+            throw error;
+        // Installed SDK discards HTTP metadata; its exact numerical rejection prefix is safe to recover.
+        const code = error instanceof Error ? /error with code\((\d+)\):/.exec(error.message)?.[1] : undefined;
+        if (code && Number(code) !== 408 && !(Number(code) >= 500 && Number(code) < 600))
+            throw new EndpointDeliveryError('platform_rejected', `KOOK request rejected (code=${code})`, 'rejected');
+        throw new EndpointDeliveryError('delivery_unconfirmed', 'KOOK outbound outcome is unknown', 'unknown');
+    }
+}
+/** Deletion requires the canonical conversation: KOOK has separate channel/private APIs. */
+export async function recallKookMessage(client, message) {
+    if (!message.id.trim())
+        throw new EndpointDeliveryError('invalid_message_id', 'KOOK recall requires a message ID', 'rejected');
+    try {
+        let deleted;
+        if (message.conversation.kind === 'private') {
+            if (!client.recallPrivateMsg)
+                throw new EndpointDeliveryError('unsupported_operation', 'KOOK transport cannot delete private messages', 'rejected');
+            deleted = await client.recallPrivateMsg(message.conversation.id, message.id);
+        }
+        else {
+            if (!client.recallChannelMsg)
+                throw new EndpointDeliveryError('unsupported_operation', 'KOOK transport cannot delete channel messages', 'rejected');
+            deleted = await client.recallChannelMsg(message.conversation.id, message.id);
+        }
+        if (deleted !== true)
+            throw new EndpointDeliveryError('platform_rejected', 'KOOK did not confirm message deletion', 'rejected');
+    }
+    catch (error) {
+        if (error instanceof EndpointDeliveryError)
+            throw error;
+        const code = error instanceof Error ? /error with code\((\d+)\):/.exec(error.message)?.[1] : undefined;
+        if (code && Number(code) !== 408 && !(Number(code) >= 500 && Number(code) < 600))
+            throw new EndpointDeliveryError('platform_rejected', `KOOK deletion rejected (code=${code})`, 'rejected');
+        throw new EndpointDeliveryError('delivery_unconfirmed', 'KOOK deletion outcome is unknown', 'unknown');
+    }
+}

package/lib/protocol.d.ts

@@ -10,6 +10,8 @@ export declare enum KookPermission {
 }
 /** One endpoint config after AdapterIndex expands `plugins.<instanceKey>.endpoints`. */
 export interface KookEndpointConfig {
+    readonly apiProxy?: import('./api-proxy.js').KookApiProxy;
+    readonly streamProxy?: import('./stream-proxy.js').KookStreamProxy;
     readonly id: string;
     readonly token: string;
     /** Default `websocket`. `webhook` requires httpHostToken + verify_token. */
@@ -24,6 +26,8 @@ export interface KookEndpointConfig {
     readonly logLevel?: LogLevel;
 }
 export interface ResolvedKookWebsocketConfig {
+    readonly apiProxy?: import('./api-proxy.js').KookApiProxy;
+    readonly streamProxy?: import('./stream-proxy.js').KookStreamProxy;
     readonly context: 'kook';
     readonly connection: 'websocket';
     readonly id: string;
@@ -35,6 +39,7 @@ export interface ResolvedKookWebsocketConfig {
     readonly logLevel: LogLevel;
 }
 export interface ResolvedKookWebhookConfig {
+    readonly apiProxy?: import('./api-proxy.js').KookApiProxy;
     readonly context: 'kook';
     readonly connection: 'webhook';
     readonly id: string;
@@ -64,6 +69,7 @@ export interface KookWebhookEventData {
             readonly author_id?: string;
             readonly target_id?: string;
             readonly chat_code?: string;
+            readonly value?: string;
             readonly emoji?: {
                 readonly id?: string;
                 readonly name?: string;
@@ -137,3 +143,13 @@ export declare function normalizeKookWebhookEvent(event: KookWebhookEventData, o
     readonly ignore?: 'bot' | 'self';
     readonly selfId?: string;
 }): KookInboundMessage | null;
+/** Native Card return-val events; routing and actor must come from the click event. */
+export declare function normalizeKookButtonEvent(raw: unknown): {
+    id: string;
+    sourceMessageId: string;
+    payload: string;
+    userId: string;
+    channelKind: 'private' | 'channel';
+    channelId: string;
+    timestamp: number;
+} | null;