@zhin.js/adapter-kook 1.1.18 → 1.1.19

package/lib/endpoint.js

@@ -1,9 +1,12 @@
 import { EndpointDeliveryError } from '@zhin.js/im-contract';
-import { Endpoint, } from 'zhin.js/adapter';
+/**
+ * KookEndpoint — lifecycle, outbound, admit, OpenAPI helpers for agent tools.
+ */
+import { createEndpointSpecification, endpointSpec, createEndpointOperation, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import { formatInboundContent, isKookBotMentioned, kookInboundConversation, normalizeKookWebhookEvent, normalizeKookButtonEvent, senderDisplayName, } from './protocol.js';
 import { registerKookWebhookRoutes } from './webhook.js';
-import { defaultCreateClient, defaultCreateWebhookClient, normalizeKookMessage, } from './ws.js';
+import { RuntimeKookClient, kookWebsocketClientOptions, kookWebhookClientOptions, normalizeKookMessage, } from './ws.js';
 import { recallKookMessage, sendKookOutbound } from './outbound.js';
 import { KookSenderRoleResolver } from './sender-roles.js';
 import { receiveKookSideEvent } from './side-event-dispatch.js';
@@ -11,6 +14,8 @@ import { receiveKookSideEvent } from './side-event-dispatch.js';
 function kookInboundPayload(endpointId, conversation, msg, projection, selfId) {
     return {
         conversation,
+        event: msg.event,
+        platformSentAt: msg.platformSentAt,
         message: { conversation, id: msg.id },
         content: formatInboundContent(msg),
         sender: {
@@ -30,77 +35,73 @@ function kookInboundPayload(endpointId, conversation, msg, projection, selfId) {
         }),
     };
 }
-export class KookWebsocketEndpoint extends Endpoint {
+export class KookWebsocketEndpoint extends RuntimeKookClient {
+    [endpointSpec];
     #sentConversations = new Map();
     #logger;
     #options;
-    #createClient;
-    #client = null;
-    #roles = new KookSenderRoleResolver(() => this.#client);
+    #roles = new KookSenderRoleResolver(() => this);
     #open = false;
+    #executionSignal;
     #started = false;
-    management = createKookEndpointManagement(() => this.#requireClient());
-    control = Object.freeze({
-        recall: (message) => recallKookMessage(this.#requireClient(), message),
+    #management = createKookEndpointManagement(() => this.#requireClient());
+    #control = Object.freeze({
+        recall: request => recallKookMessage(this.#requireClient(), request),
     });
     constructor(options) {
-        super();
+        super(kookWebsocketClientOptions(options.config), undefined, options.config.apiProxy);
         this.#logger = getAdapterLogger('kook', options.config.id);
         this.#options = options;
-        this.#createClient = options.createClient ?? defaultCreateClient;
-    }
-    get client() {
-        return this.#requireClient();
+        const endpoint = this;
+        this[endpointSpec] = createEndpointSpecification(this, {
+            start: signal => this.#startFramework(signal), open: () => this.#openFramework(), close: () => this.#closeFramework(),
+            stop: () => this.#stopFramework(), send: request => this.#sendFramework(request),
+            name: options.config.id, get transportState() { return endpoint.#transportState; },
+            management: this.#management, control: this.#control,
+        });
     }
-    get transportState() {
+    get #transportState() {
         if (!this.#started)
             return 'stopped';
-        return this.#client?.getTransportState?.();
+        return this.getTransportState?.();
     }
-    async start() {
+    async #startFramework(signal) {
+        this.#executionSignal = signal;
+        this.request.interceptors.request.use(request => { request.signal = signal; return request; });
         if (this.#started)
             return;
         this.#started = true;
         try {
-            this.#client = this.#createClient(this.#options.config);
-            this.#bindClient(this.#client);
-            await this.#client.connect();
+            this.#bindClient(this);
+            await this.connect();
             this.#logger.info(formatCompact({
                 op: 'connect',
                 endpoint: this.#options.config.id,
                 mode: 'websocket',
-                self_id: this.#client.self_id != null ? String(this.#client.self_id) : undefined,
+                self_id: this.self_id != null ? String(this.self_id) : undefined,
             }));
         }
         catch (error) {
-            await this.stop();
+            await this.#stopFramework();
             this.#logger.error('Failed to connect KOOK websocket:', error);
             throw error;
         }
     }
-    open() {
+    #openFramework() {
         this.#open = true;
     }
-    close() {
+    #closeFramework() {
         this.#open = false;
     }
-    async stop() {
+    async #stopFramework() {
         this.#open = false;
         this.#sentConversations.clear();
-        if (this.#client) {
-            try {
-                this.#client.removeAllListeners();
-                await this.#client.disconnect();
-            }
-            catch {
-                /* ignore */
-            }
-            this.#client = null;
-        }
+        this.removeAllListeners();
+        await this.disconnect();
         this.#started = false;
         this.#logger.debug(formatCompact({ op: 'disconnect' }));
     }
-    async send(request) {
+    async #sendFramework(request) {
         const { conversation } = request;
         const messageId = await sendKookOutbound(this.#requireClient(), request);
         rememberKookConversation(this.#sentConversations, messageId, conversation);
@@ -114,54 +115,61 @@ export class KookWebsocketEndpoint extends Endpoint {
     }
     /** Test / internal: admit a normalized message when open. */
     admit(msg) {
-        if (!this.#open)
-            return;
-        if (msg.authorBot)
-            return;
-        const conversation = kookInboundConversation(String(this.#options.id), msg);
-        const selfId = this.#client?.self_id != null ? String(this.#client.self_id) : undefined;
-        void this.#roles.resolve(msg).then((projection) => this.emit('message.receive', kookInboundPayload(this.#options.config.id, conversation, msg, projection, selfId))).catch((err) => {
-            this.#logger.warn(formatCompact({
-                op: 'kook_gateway_receive_failed',
-                target: `${conversation.kind}:${conversation.id}`,
-                error: err instanceof Error ? err.message : String(err),
-            }));
-        });
+        void this[endpointSpec].events.run(() => {
+            if (msg.authorBot)
+                return;
+            const conversation = kookInboundConversation(String(this.#options.id), msg);
+            const selfId = this.self_id != null ? String(this.self_id) : undefined;
+            return this.#roles.resolve(msg).then((projection) => {
+                this.#executionSignal?.throwIfAborted();
+                return this[endpointSpec].events.emit('message.receive', kookInboundPayload(this.#options.config.id, conversation, msg, projection, selfId));
+            }).catch((err) => {
+                this.#logger.warn(formatCompact({
+                    op: 'kook_gateway_receive_failed',
+                    target: `${conversation.kind}:${conversation.id}`,
+                    error: err instanceof Error ? err.message : String(err),
+                }));
+            });
+        }).catch(() => this.#logger.debug('Inbound callback was not admitted'));
     }
     async recallMessage(messageId, conversation) {
         if (!conversation)
             throw new EndpointDeliveryError('unsupported_operation', 'KOOK recall requires conversation routing', 'rejected');
-        await recallKookMessage(this.#requireClient(), { id: messageId, conversation });
+        await recallKookMessage(this.#requireClient(), { message: { id: messageId, conversation } });
     }
     #bindClient(client) {
         client.on('message', (raw) => {
-            this.#emitPlatformEvent('message', raw);
-            const msg = normalizeKookMessage(raw);
-            if (msg)
-                this.admit(msg);
+            void this[endpointSpec].events.run(() => {
+                this.#emitPlatformEvent('message', raw);
+                const msg = normalizeKookMessage(raw);
+                if (msg)
+                    this.admit(msg);
+            }).catch(() => this.#logger.debug('Native callback was not admitted'));
         });
         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);
+            void this[endpointSpec].events.run(() => {
+                if (this !== 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[endpointSpec].events.emit(name, payload), this.#options.config.id, raw, this.#logger);
+            }).catch(() => this.#logger.debug('Native callback was not admitted'));
         });
     }
     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)));
+        return this[endpointSpec].events.run(async () => {
+            const event = normalizeKookButtonEvent(raw);
+            if (!event)
+                throw new Error('Invalid KOOK button event');
+            await this[endpointSpec].events.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) => {
+        void this[endpointSpec].events.platform(name, event).catch((error) => {
             this.#logger.warn(formatCompact({
                 op: 'kook_platform_event_failed',
                 event: name,
@@ -170,93 +178,87 @@ export class KookWebsocketEndpoint extends Endpoint {
         });
     }
     #requireClient() {
-        if (!this.#client)
+        if (!this.#started)
             throw new Error('KOOK client not connected');
-        return this.#client;
+        return this;
     }
 }
-export class KookWebhookEndpoint extends Endpoint {
+export class KookWebhookEndpoint extends RuntimeKookClient {
+    [endpointSpec];
     #sentConversations = new Map();
     #logger;
     #options;
-    #createClient;
-    #client = null;
-    #roles = new KookSenderRoleResolver(() => this.#client);
+    #roles = new KookSenderRoleResolver(() => this);
     #routeReleases = [];
     #processedSn = new Set();
     #open = false;
+    #executionSignal;
     #started = false;
-    management = createKookEndpointManagement(() => this.#requireClient());
-    control = Object.freeze({
-        recall: (message) => recallKookMessage(this.#requireClient(), message),
+    #management = createKookEndpointManagement(() => this.#requireClient());
+    #control = Object.freeze({
+        recall: request => recallKookMessage(this.#requireClient(), request),
     });
     constructor(options) {
-        super();
+        super(kookWebhookClientOptions(options.config), undefined, options.config.apiProxy);
         this.#logger = getAdapterLogger('kook', options.config.id);
         this.#options = options;
-        this.#createClient = options.createClient ?? defaultCreateWebhookClient;
-    }
-    get client() {
-        return this.#requireClient();
+        this[endpointSpec] = createEndpointSpecification(this, {
+            start: signal => this.#startFramework(signal), open: () => this.#openFramework(), close: () => this.#closeFramework(),
+            stop: () => this.#stopFramework(), send: request => this.#sendFramework(request), name: options.config.id,
+            management: this.#management, control: this.#control,
+        });
     }
     /** Used by webhook handler. */
     get isOpen() {
         return this.#open;
     }
-    get config() {
+    get endpointConfig() {
         return this.#options.config;
     }
     get selfId() {
-        return this.#client?.self_id != null ? String(this.#client.self_id) : undefined;
+        return this.self_id != null ? String(this.self_id) : undefined;
     }
-    async start() {
+    async #startFramework(signal) {
+        this.#executionSignal = signal;
+        this.request.interceptors.request.use(request => { request.signal = signal; return request; });
         if (this.#started)
             return;
         this.#started = true;
         try {
-            this.#client = this.#createClient(this.#options.config);
-            await this.#client.init();
+            await this.init();
             this.#routeReleases.push(...registerKookWebhookRoutes(this.#options.http, this));
             this.#logger.info(formatCompact({
                 op: 'connect',
                 endpoint: this.#options.config.id,
                 mode: 'webhook',
                 path: this.#options.config.webhookPath,
-                self_id: this.#client.self_id != null ? String(this.#client.self_id) : undefined,
+                self_id: this.self_id != null ? String(this.self_id) : undefined,
             }));
         }
         catch (error) {
-            await this.stop();
+            await this.#stopFramework();
             this.#logger.error('Failed to connect KOOK webhook:', error);
             throw error;
         }
     }
-    open() {
+    #openFramework() {
         this.#open = true;
     }
-    close() {
+    #closeFramework() {
         this.#open = false;
     }
-    async stop() {
+    async #stopFramework() {
         this.#open = false;
         this.#sentConversations.clear();
         for (const release of this.#routeReleases.splice(0))
             release();
         this.#processedSn.clear();
-        if (this.#client) {
-            try {
-                this.#client.removeAllListeners();
-                await this.#client.disconnect();
-            }
-            catch {
-                /* ignore */
-            }
-            this.#client = null;
-        }
+        this.removeAllListeners();
+        await this.disconnect();
         this.#started = false;
         this.#logger.debug(formatCompact({ op: 'disconnect' }));
     }
-    async send(request) {
+    async #sendFramework(request) {
         const { conversation } = request;
         const messageId = await sendKookOutbound(this.#requireClient(), request);
         rememberKookConversation(this.#sentConversations, messageId, conversation);
@@ -269,49 +271,54 @@ export class KookWebhookEndpoint extends Endpoint {
         return messageId;
     }
     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',
-                event: String(event.type ?? 'event'),
-                error: error instanceof Error ? error.message : String(error),
-            }));
-        });
-        if (receiveKookSideEvent((name, payload) => this.emit(name, payload), this.#options.config.id, event, this.#logger))
-            return;
-        const message = normalizeKookWebhookEvent(event, {
-            ignore: this.#options.config.ignore,
-            selfId: this.selfId,
+        return this[endpointSpec].events.run(async () => {
+            if (normalizeKookButtonEvent(event)) {
+                if (!this.#open)
+                    throw new Error('KOOK endpoint is closed');
+                const button = normalizeKookButtonEvent(event);
+                await this[endpointSpec].events.emitAccepted('message.receive', kookButtonIngress(String(this.#options.id), this.#options.config.id, button, this.#sentConversations.get(button.sourceMessageId)));
+                return;
+            }
+            void this[endpointSpec].events.platform(String(event.type ?? 'event'), event).catch((error) => {
+                this.#logger.warn(formatCompact({
+                    op: 'kook_platform_event_failed',
+                    event: String(event.type ?? 'event'),
+                    error: error instanceof Error ? error.message : String(error),
+                }));
+            });
+            if (receiveKookSideEvent((name, payload) => this[endpointSpec].events.emit(name, payload), this.#options.config.id, event, this.#logger))
+                return;
+            const message = normalizeKookWebhookEvent(event, {
+                ignore: this.#options.config.ignore,
+                selfId: this.selfId,
+            });
+            if (message)
+                this.admit(message);
         });
-        if (message)
-            this.admit(message);
     }
     /** Test / internal: admit a message when open. */
     admit(msg) {
-        if (!this.#open)
-            return;
-        if (msg.authorBot)
-            return;
-        const conversation = kookInboundConversation(String(this.#options.id), msg);
-        const selfId = this.#client?.self_id != null ? String(this.#client.self_id) : undefined;
-        void this.#roles.resolve(msg).then((projection) => this.emit('message.receive', kookInboundPayload(this.#options.config.id, conversation, msg, projection, selfId))).catch((err) => {
-            this.#logger.warn(formatCompact({
-                op: 'kook_gateway_receive_failed',
-                target: `${conversation.kind}:${conversation.id}`,
-                error: err instanceof Error ? err.message : String(err),
-            }));
-        });
+        void this[endpointSpec].events.run(() => {
+            if (msg.authorBot)
+                return;
+            const conversation = kookInboundConversation(String(this.#options.id), msg);
+            const selfId = this.self_id != null ? String(this.self_id) : undefined;
+            return this.#roles.resolve(msg).then((projection) => {
+                this.#executionSignal?.throwIfAborted();
+                return this[endpointSpec].events.emit('message.receive', kookInboundPayload(this.#options.config.id, conversation, msg, projection, selfId));
+            }).catch((err) => {
+                this.#logger.warn(formatCompact({
+                    op: 'kook_gateway_receive_failed',
+                    target: `${conversation.kind}:${conversation.id}`,
+                    error: err instanceof Error ? err.message : String(err),
+                }));
+            });
+        }).catch(() => this.#logger.debug('Inbound callback was not admitted'));
     }
     async recallMessage(messageId, conversation) {
         if (!conversation)
             throw new EndpointDeliveryError('unsupported_operation', 'KOOK recall requires conversation routing', 'rejected');
-        await recallKookMessage(this.#requireClient(), { id: messageId, conversation });
+        await recallKookMessage(this.#requireClient(), { message: { id: messageId, conversation } });
     }
     checkAndRememberSn(sn) {
         if (this.#processedSn.has(sn))
@@ -326,20 +333,11 @@ export class KookWebhookEndpoint extends Endpoint {
     }
     forgetSn(sn) { this.#processedSn.delete(sn); }
     #requireClient() {
-        if (!this.#client)
+        if (!this.#started)
             throw new Error('KOOK client not initialized');
-        return this.#client;
+        return this;
     }
 }
-/**
- * KOOK guild/channel/user id 是字符串形式的雪花号，超出
- * Number.MAX_SAFE_INTEGER，Number() 会丢精度。Console 社交面只把 group_id
- * 当 JSON 值透传、并以字符串回传给 listGroupMembers，因此保留原始字符串
- * （仅按契约类型声明强转）是全链路最不丢信息的方案。
- */
-function toGroupId(id) {
-    return id;
-}
 /** KOOK 文字频道标记：HTTP API type=1（2=语音），kook-client 消息侧用 'GROUP'。 */
 function rememberKookConversation(cache, messageId, conversation) {
     cache.set(messageId, conversation);
@@ -350,7 +348,7 @@ 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}]`,
+    return { event: event.event, platformSentAt: event.platformSentAt, 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 }) };
@@ -365,28 +363,30 @@ function isKookTextChannelType(type) {
  */
 export function createKookEndpointManagement(requireClient) {
     return Object.freeze({
-        async listGroups() {
-            const guilds = await requireClient().getGuildList();
+        async listGroups(request = {}) {
+            const operation = createEndpointOperation(request);
+            const guilds = await operation.run(() => requireClient().getGuildList());
             const groups = [];
             for (const guild of guilds) {
                 if (guild?.id == null)
                     continue;
                 groups.push({
-                    group_id: toGroupId(String(guild.id)),
+                    group_id: String(guild.id),
                     name: String(guild.name ?? guild.id),
                 });
             }
             return groups;
         },
-        async listChannels() {
+        async listChannels(request = {}) {
+            const operation = createEndpointOperation(request);
             const client = requireClient();
             const channels = [];
-            for (const guild of await client.getGuildList()) {
+            for (const guild of await operation.run(() => client.getGuildList())) {
                 if (guild?.id == null)
                     continue;
                 const guildId = String(guild.id);
                 const guildName = String(guild.name ?? guildId);
-                for (const channel of await client.getChannelList(guildId)) {
+                for (const channel of await operation.run(() => client.getChannelList(guildId))) {
                     if (channel?.id == null)
                         continue;
                     if (channel.is_category)
@@ -402,9 +402,10 @@ export function createKookEndpointManagement(requireClient) {
             }
             return channels;
         },
-        async listGroupMembers(groupId) {
+        async listGroupMembers({ groupId, signal }) {
+            const operation = createEndpointOperation({ signal });
             // 平台形状（User.Info[]）原样返回
-            return requireClient().getGuildUserList(groupId);
+            return operation.run(() => requireClient().getGuildUserList(groupId));
         },
     });
 }

package/lib/index.d.ts

@@ -1,6 +1,7 @@
 export { formatInboundContent, formatOutboundKmarkdown, resolveKookConfig, senderDisplayName, KookPermission, type KookEndpointConfig, type KookInboundMessage, type KookWireSegment, type LogLevel, type ResolvedKookConfig, type ResolvedKookWebhookConfig, type ResolvedKookWebsocketConfig, } from './protocol.js';
 export { KookWebhookEndpoint, KookWebsocketEndpoint, type KookEndpointOptions, type KookWebhookEndpointOptions, } from './endpoint.js';
 export { registerKookWebhookRoutes, handleKookWebhookRequest, type KookWebhookHandler, } from './webhook.js';
-export { defaultCreateClient, defaultCreateWebhookClient, normalizeKookMessage, type CreateKookClient, type KookClientTransport, } from './ws.js';
-export { kookClient, type KookClientEventMap } from './client.js';
+export { kookWebsocketClientOptions, kookWebhookClientOptions, normalizeKookMessage, type KookClientTransport, } from './ws.js';
+export { type KookClientEventMap } from './client.js';
+export { KookAdapter } from './adapter.js';
 export { checkKookPlatformPermit, kookGroupPermitResolver, normalizeKookSenderForPermit, platformPermit, type KookSenderInfo, } from './platform-permit.js';

package/lib/index.js

@@ -1,6 +1,6 @@
 export { formatInboundContent, formatOutboundKmarkdown, resolveKookConfig, senderDisplayName, KookPermission, } from './protocol.js';
 export { KookWebhookEndpoint, KookWebsocketEndpoint, } from './endpoint.js';
 export { registerKookWebhookRoutes, handleKookWebhookRequest, } from './webhook.js';
-export { defaultCreateClient, defaultCreateWebhookClient, normalizeKookMessage, } from './ws.js';
-export { kookClient } from './client.js';
+export { kookWebsocketClientOptions, kookWebhookClientOptions, normalizeKookMessage, } from './ws.js';
+export { KookAdapter } from './adapter.js';
 export { checkKookPlatformPermit, kookGroupPermitResolver, normalizeKookSenderForPermit, platformPermit, } from './platform-permit.js';

package/lib/outbound.d.ts

@@ -1,7 +1,6 @@
-import { type MessageRef } from '@zhin.js/im-contract';
-import type { EndpointSendRequest } from 'zhin.js/adapter';
+import { type EndpointRecallRequest, 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, locale }: EndpointSendRequest): Promise<string>;
+export declare function sendKookOutbound(client: KookClientTransport, { conversation, payload, locale, signal }: EndpointSendRequest): Promise<string>;
 /** Deletion requires the canonical conversation: KOOK has separate channel/private APIs. */
-export declare function recallKookMessage(client: KookClientTransport, message: MessageRef): Promise<void>;
+export declare function recallKookMessage(client: KookClientTransport, { message, signal }: EndpointRecallRequest): Promise<void>;

package/lib/outbound.js

@@ -1,9 +1,11 @@
 import { readFile } from 'node:fs/promises';
 import { EndpointDeliveryError, isMediaRef } from '@zhin.js/im-contract';
+import { createEndpointOperation } from 'zhin.js/adapter';
 import { formatOutboundKmarkdown } from './protocol.js';
 import { outboundMessages as t } from './i18n.js';
 /** Native cards preserve mixed text/images; SDK's ordinary segments stop at first media. */
-export async function sendKookOutbound(client, { conversation, payload, locale }) {
+export async function sendKookOutbound(client, { conversation, payload, locale, signal }) {
+    const operation = createEndpointOperation({ signal });
     try {
         const items = Array.isArray(payload) ? payload : payload && typeof payload === 'object' ? [payload] : [payload];
         let quote;
@@ -70,14 +72,14 @@ export async function sendKookOutbound(client, { conversation, payload, locale }
                     if (media.kind === 'base64')
                         bytes = Buffer.from(media.value.replace(/^data:[^,]*,/, ''), 'base64');
                     else if (media.kind === 'path')
-                        bytes = await readFile(media.value);
+                        bytes = await operation.prepare(() => readFile(media.value));
                     else {
-                        const response = await fetch(media.value, { signal: AbortSignal.timeout(30_000) });
+                        const response = await operation.prepare(() => fetch(media.value, { signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(30_000)]) : AbortSignal.timeout(30_000) }));
                         if (!response.ok)
                             throw new EndpointDeliveryError('media_download_failed', 'KOOK media download failed', 'rejected');
-                        bytes = Buffer.from(await response.arrayBuffer());
+                        bytes = Buffer.from(await operation.prepare(() => response.arrayBuffer()));
                     }
-                    url = await client.uploadMedia(bytes);
+                    url = await operation.prepare(() => client.uploadMedia(bytes));
                 }
                 if (typeof url !== 'string' || !/^https:\/\//.test(url))
                     throw new EndpointDeliveryError('delivery_unconfirmed', 'KOOK upload returned no media URL', 'unknown');
@@ -94,10 +96,11 @@ export async function sendKookOutbound(client, { conversation, payload, locale }
             }
         }
         const body = hasImage || hasCard ? { __isCard: true, type: 'card', theme: 'secondary', size: 'lg', modules } : formatOutboundKmarkdown(payload, locale);
+        // SDK 1.0.5 implements __isCard and returns the API's msg_id; its declaration still describes Message.Ret.
         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) : '';
+            ? await operation.run(() => client.sendPrivateMsg(conversation.id, body, quote))
+            : await operation.run(() => client.sendChannelMsg(conversation.id, body, quote));
+        const id = result && typeof result === 'object' && 'msg_id' in result && 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;
@@ -113,20 +116,21 @@ export async function sendKookOutbound(client, { conversation, payload, locale }
     }
 }
 /** Deletion requires the canonical conversation: KOOK has separate channel/private APIs. */
-export async function recallKookMessage(client, message) {
+export async function recallKookMessage(client, { message, signal }) {
     if (!message.id.trim())
         throw new EndpointDeliveryError('invalid_message_id', 'KOOK recall requires a message ID', 'rejected');
+    const operation = createEndpointOperation({ signal });
     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);
+            deleted = await operation.run(() => 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);
+            deleted = await operation.run(() => client.recallChannelMsg(message.conversation.id, message.id));
         }
         if (deleted !== true)
             throw new EndpointDeliveryError('platform_rejected', 'KOOK did not confirm message deletion', 'rejected');

package/lib/protocol.d.ts

@@ -93,6 +93,8 @@ export interface KookWebhookFrame {
 }
 export type ResolvedKookConfig = ResolvedKookWebsocketConfig | ResolvedKookWebhookConfig;
 export interface KookInboundMessage {
+    readonly event?: unknown;
+    readonly platformSentAt?: number;
     readonly id: string;
     readonly content: string;
     readonly channelKind: 'private' | 'channel';
@@ -146,6 +148,8 @@ export declare function normalizeKookWebhookEvent(event: KookWebhookEventData, o
 }): KookInboundMessage | null;
 /** Native Card return-val events; routing and actor must come from the click event. */
 export declare function normalizeKookButtonEvent(raw: unknown): {
+    event: unknown;
+    platformSentAt?: number;
     id: string;
     sourceMessageId: string;
     payload: string;