@zhin.js/adapter-dingtalk 1.1.4 → 1.1.6

package/src/endpoint.ts

@@ -1,8 +1,10 @@
-import { Endpoint } from 'zhin.js/adapter';
+import { DingTalkCards, type DingTalkCardCallback } from './cards.js';
+import { DingTalkStream, type DingTalkStreamSocketFactory } from './stream.js';
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
 /**
  * DingTalkEndpoint — lifecycle, outbound, admit, OpenAPI helpers for agent tools.
  */
-import { type EndpointSendRequest } from 'zhin.js/adapter';
+import { Endpoint, type EndpointSendRequest } from 'zhin.js/adapter';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
@@ -30,6 +32,7 @@ export type DingTalkFetch = (
     readonly method?: string;
     readonly headers?: Record<string, string>;
     readonly body?: string;
+    readonly signal?: AbortSignal;
   },
 ) => Promise<{
   readonly ok: boolean;
@@ -40,7 +43,8 @@ export type DingTalkFetch = (
 
 export interface DingTalkEndpointOptions {
   readonly id: CapabilityId;
-  readonly http: HttpHost;
+  readonly http?: HttpHost;
+  readonly createStreamSocket?: DingTalkStreamSocketFactory;
   readonly config: ResolvedDingTalkConfig;
   readonly fetch?: DingTalkFetch;
 }
@@ -100,7 +104,9 @@ export class DingTalkEndpoint extends Endpoint<DingTalkClient> {
   #routeReleases: HttpRouteRegistration[] = [];
   #accessToken: AccessToken = { token: '', expires_in: 0, timestamp: 0 };
   #refreshPromise: Promise<string> | null = null;
-  #sessionWebhooks = new Map<string, string>();
+  #sessionWebhooks = new Map<string, { url: string; expiresAt: number }>();
+  #stream?: DingTalkStream;
+  readonly #cards = new DingTalkCards();
   #open = false;
   #started = false;
 
@@ -111,6 +117,8 @@ export class DingTalkEndpoint extends Endpoint<DingTalkClient> {
     this.#fetch = options.fetch ?? globalThis.fetch;
   }
 
+  get transportState() { return this.#stream?.lifecycle.state ?? (this.#started ? 'open' : 'stopped'); }
+
   /** Used by webhook handler. */
   get isOpen(): boolean {
     return this.#open;
@@ -124,8 +132,13 @@ export class DingTalkEndpoint extends Endpoint<DingTalkClient> {
     if (this.#started) return;
     this.#started = true;
     try {
+      if (this.#options.config.mode === 'stream') {
+        this.#stream = new DingTalkStream(this.config, this.#fetch, (event) => this.admit(event), () => this.#open, this.#options.createStreamSocket, (event, id) => this.admitCard(event, id));
+        await this.#stream.start();
+        return;
+      }
       await this.#refreshAccessToken();
-      this.#routeReleases.push(...registerDingTalkWebhookRoutes(this.#options.http, this));
+      this.#routeReleases.push(...registerDingTalkWebhookRoutes(this.#options.http!, this));
       this.#logger.debug(formatCompact({
         endpoint: this.#options.config.id,
         op: 'webhook',
@@ -148,62 +161,124 @@ export class DingTalkEndpoint extends Endpoint<DingTalkClient> {
 
   async stop(): Promise<void> {
     this.#open = false;
+    await this.#stream?.stop();
     this.#sessionWebhooks.clear();
+    this.#cards.clear();
     for (const release of this.#routeReleases.splice(0)) release();
     this.#started = false;
     this.#logger.debug(formatCompact({ op: 'disconnect' }));
   }
 
   async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
-    const content = formatOutboundBody(payload);
-    const sessionWebhook = this.#sessionWebhooks.get(conversation.id);
-    if (sessionWebhook) {
-      const response = await this.#fetch(sessionWebhook, {
+    try {
+      const card = this.#cards.prepare(this.config, conversation, payload);
+      if (card) {
+        let stage = 'token';
+        let httpStatus: number | undefined;
+        let platformCode: string | number | undefined;
+        try {
+          try { await this.#ensureAccessToken(); } catch (cause) { throw new EndpointDeliveryError('token_unavailable', 'DingTalk card token unavailable', 'not_sent', { cause }); }
+          stage = 'request';
+          const response = await this.#fetch('https://api.dingtalk.com/v1.0/card/instances/createAndDeliver', { method: 'POST', headers: { 'Content-Type': 'application/json', 'x-acs-dingtalk-access-token': this.#accessToken.token }, body: JSON.stringify(card.body), signal: AbortSignal.timeout(30_000) });
+          httpStatus = response.status;
+          stage = 'response';
+          let data: unknown;
+          try { data = await response.json(); } catch {
+            if (response.ok) throw new EndpointDeliveryError('invalid_response', 'DingTalk card response could not be parsed', 'unknown');
+          }
+          if (data && typeof data === 'object') {
+            const code = (data as { code?: unknown; errcode?: unknown }).code ?? (data as { errcode?: unknown }).errcode;
+            // Only bounded protocol codes; never log URLs, messages, response bodies or credentials.
+            if (typeof code === 'number' && Number.isFinite(code)) platformCode = code;
+            else if (typeof code === 'string' && /^[a-zA-Z][a-zA-Z0-9_.-]{0,95}$/.test(code)
+              && ![this.#accessToken.token, this.config.appSecret, this.config.appKey].some(secret => secret && code.includes(secret))) platformCode = code;
+          }
+          if (!response.ok) throw new EndpointDeliveryError('http_error', `DingTalk card HTTP ${response.status}`, response.status >= 400 && response.status < 500 ? 'rejected' : 'unknown');
+          stage = 'delivery';
+          return this.#cards.confirm(card, data);
+        } catch (error) {
+          this.#logger.warn(formatCompact({ op: 'dingtalk_card_delivery_failed', stage, httpStatus, platformCode,
+            code: error instanceof EndpointDeliveryError ? error.code : 'delivery_unconfirmed' }));
+          throw error;
+        }
+      }
+      const content = formatOutboundBody(payload);
+      const session = this.#sessionWebhooks.get(conversation.id);
+      const sessionWebhook = session && session.expiresAt > Date.now() ? session.url : undefined;
+      if (session && !sessionWebhook) this.#sessionWebhooks.delete(conversation.id);
+      if (!sessionWebhook && this.config.mode === 'stream') {
+        throw new EndpointDeliveryError('session_unavailable', 'DingTalk Stream send requires a current inbound session webhook', 'not_sent');
+      }
+      if (sessionWebhook) {
+        const response = await this.#fetch(sessionWebhook, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json; charset=utf-8' },
+          body: JSON.stringify(content),
+          signal: AbortSignal.timeout(30_000),
+        });
+        if (!response.ok) throw new EndpointDeliveryError('http_error', `DingTalk HTTP ${response.status}`, response.status >= 400 && response.status < 500 ? 'rejected' : 'unknown');
+        const data = await response.json() as DingTalkApiResponse;
+        if (typeof data.errcode === 'number' && data.errcode !== 0) {
+          throw new EndpointDeliveryError('platform_rejected', `DingTalk session webhook rejected the outbound request (${data.errcode})`, 'rejected');
+        }
+        this.#logger.debug(formatCompact({
+          op: 'send',
+          endpoint: this.#options.config.id,
+          via: 'sessionWebhook',
+          to: conversation.id,
+        }));
+        if (data.errcode !== 0) throw new EndpointDeliveryError('delivery_unconfirmed', 'Malformed platform response', 'unknown');
+        return requireMessageId(data.msgId);
+      }
+
+      const body: DingTalkSendBody = {
+        ...content,
+        ...(this.#options.config.robotCode
+          ? { robotCode: this.#options.config.robotCode }
+          : {}),
+      };
+      const data = await this.#request('/robot/send', {
         method: 'POST',
-        headers: { 'Content-Type': 'application/json; charset=utf-8' },
-        body: JSON.stringify(content),
+        body: body as unknown as Record<string, unknown>,
       });
-      const data = await response.json() as DingTalkApiResponse;
-      if (data.errcode !== 0) {
-        throw new Error(`Failed to send message via session webhook: ${data.errmsg}`);
+      if (typeof data.errcode === 'number' && data.errcode !== 0) {
+        throw new EndpointDeliveryError('platform_rejected', `DingTalk rejected the outbound request (${data.errcode})`, 'rejected');
       }
-      this.#logger.debug(formatCompact({
-        op: 'send',
-        endpoint: this.#options.config.id,
-        via: 'sessionWebhook',
-        to: conversation.id,
-      }));
-      return (data.msgId as string) || `${Date.now()}`;
+      this.#logger.debug(formatCompact({ op: 'send', to: conversation.id }));
+      if (data.errcode !== 0) throw new EndpointDeliveryError('delivery_unconfirmed', 'Malformed platform response', 'unknown');
+      return requireMessageId(data.msgId);
+    } catch (error) {
+      if (error instanceof EndpointDeliveryError) throw error;
+      throw new EndpointDeliveryError('delivery_unconfirmed', 'Outbound request outcome is unknown', 'unknown', { cause: error });
     }
+  }
 
-    const body: DingTalkSendBody = {
-      ...content,
-      ...(this.#options.config.robotCode
-        ? { robotCode: this.#options.config.robotCode }
-        : {}),
-    };
-    const data = await this.#request('/robot/send', {
-      method: 'POST',
-      body: body as unknown as Record<string, unknown>,
+  async admitCard(event: DingTalkCardCallback, id: string): Promise<void> {
+    if (!this.#open) throw new Error('DingTalk endpoint is closed');
+    const action = this.#cards.resolve(event);
+    await this.emitAccepted('message.receive', {
+      conversation: action.conversation, message: { conversation: action.conversation, id },
+      content: `[action: ${action.payload}]`, segments: [{ type: 'action', data: { id, payload: action.payload, sourceMessageId: action.sourceMessageId } }],
+      sender: { id: action.senderId }, endpointId: this.config.id,
+      metadata: Object.freeze({ eventType: 'card_callback', sourceMessageId: action.sourceMessageId }),
     });
-    if (data.errcode !== 0) {
-      throw new Error(`Failed to send message: ${data.errmsg}`);
-    }
-    this.#logger.debug(formatCompact({ op: 'send', to: conversation.id }));
-    return (data.msgId as string) || `${Date.now()}`;
   }
 
   /** Test / internal: admit a parsed event when open (non-webhook path). */
-  admit(event: DingTalkEvent | DingTalkMessage): void {
+  async admit(event: DingTalkEvent | DingTalkMessage): Promise<void> {
     if (!this.#open) return;
     this.#emitPlatformEvent(event.msgtype || 'event', event);
     if (event.sessionWebhook && event.conversationId) {
-      this.#sessionWebhooks.set(event.conversationId, event.sessionWebhook);
+      const expiresAt = Number.isFinite(event.sessionWebhookExpiredTime) ? event.sessionWebhookExpiredTime! : Date.now() + 300_000;
+      this.#sessionWebhooks.delete(event.conversationId);
+      if (expiresAt > Date.now()) this.#sessionWebhooks.set(event.conversationId, { url: event.sessionWebhook, expiresAt });
+      while (this.#sessionWebhooks.size > 1024) this.#sessionWebhooks.delete(this.#sessionWebhooks.keys().next().value!);
     }
     const conversation = dingtalkInboundConversation(String(this.#options.id), event);
+    this.#cards.remember(conversation, event);
     const chatType = resolveChatType(event.conversationType);
     const permit = normalizeDingtalkSenderForPermit({ isAdmin: event.isAdmin === true });
-    void this.emit('message.receive', {
+    await this.emitAccepted('message.receive', {
       conversation,
       message: { conversation, id: generateMessageId(event) },
       content: formatInboundContent(event),
@@ -223,6 +298,7 @@ export class DingTalkEndpoint extends Endpoint<DingTalkClient> {
         conversationType: event.conversationType,
       }),
     }).catch((err) => {
+      if (this.config.mode === 'stream') throw err;
       this.#logger.warn(formatCompact({
         op: 'dingtalk_gateway_receive_failed',
         conversationId: conversation.id,
@@ -393,10 +469,10 @@ export class DingTalkEndpoint extends Endpoint<DingTalkClient> {
       method,
       headers: { 'Content-Type': 'application/json; charset=utf-8' },
       body: body && method === 'POST' ? JSON.stringify(body) : undefined,
+      signal: AbortSignal.timeout(30_000),
     });
     if (!response.ok) {
-      const text = await response.text().catch(() => '');
-      throw new Error(`DingTalk API error ${response.status}: ${text}`);
+      throw new EndpointDeliveryError('http_error', `DingTalk HTTP ${response.status}`, response.status >= 400 && response.status < 500 ? 'rejected' : 'unknown');
     }
     return await response.json() as DingTalkApiResponse;
   }
@@ -437,3 +513,8 @@ export class DingTalkEndpoint extends Endpoint<DingTalkClient> {
     throw new Error(`Failed to get access token: ${data.errmsg} (${data.errcode})`);
   }
 }
+
+function requireMessageId(value: unknown): string {
+  if (typeof value === 'string' && value.trim().length > 0) return value;
+  throw new EndpointDeliveryError('delivery_unconfirmed', 'Platform did not return a real message ID', 'unknown');
+}

package/src/protocol.ts

@@ -6,29 +6,34 @@
 import { createHmac, timingSafeEqual } from 'node:crypto';
 import type { IncomingMessage } from 'node:http';
 
-import { isMediaRef, type ConversationRef } from '@zhin.js/im-contract';
-import { formatCompact, getLogger } from '@zhin.js/logger';
-
-const logger = getLogger('dingtalk');
+import { EndpointDeliveryError, isMediaRef, type ConversationRef } from '@zhin.js/im-contract';
 
 /** One endpoint config after AdapterIndex expands `plugins.<instanceKey>.endpoints`. */
 export interface DingTalkEndpointConfig {
+  readonly streamProxy?: import('./stream-proxy.js').DingTalkStreamProxy;
   readonly id: string;
   readonly appKey: string;
   readonly appSecret: string;
+  readonly mode?: 'webhook' | 'stream';
   readonly webhookPath?: string;
   readonly robotCode?: string;
   readonly apiBaseUrl?: string;
+  readonly cardTemplateId?: string;
+  readonly cardButtonCount?: number;
 }
 
 export interface ResolvedDingTalkConfig {
+  readonly streamProxy?: import('./stream-proxy.js').DingTalkStreamProxy;
   readonly context: 'dingtalk';
+  readonly mode?: 'webhook' | 'stream';
   readonly id: string;
   readonly appKey: string;
   readonly appSecret: string;
   readonly webhookPath: string;
   readonly robotCode?: string;
   readonly apiBaseUrl: string;
+  readonly cardTemplateId?: string;
+  readonly cardButtonCount?: number;
 }
 
 export interface DingTalkMessage {
@@ -42,6 +47,7 @@ export interface DingTalkMessage {
   readonly senderNick?: string;
   readonly senderCorpId?: string;
   readonly sessionWebhook?: string;
+  readonly sessionWebhookExpiredTime?: number;
   readonly chatbotCorpId?: string;
   readonly chatbotUserId?: string;
   readonly isAdmin?: boolean;
@@ -111,20 +117,28 @@ export interface DingTalkSendBody {
 }
 
 export function resolveDingTalkConfig(config: DingTalkEndpointConfig): ResolvedDingTalkConfig {
+  if (config.streamProxy && (!Number.isInteger(config.streamProxy.port) || config.streamProxy.port < 1 || config.streamProxy.port > 65535
+    || typeof config.streamProxy.serverName !== 'string' || !config.streamProxy.serverName || /[\s/:@?#]/.test(config.streamProxy.serverName))) throw new TypeError('Invalid DingTalk streamProxy port/serverName');
+  if (config.mode !== undefined && !['webhook', 'stream'].includes(config.mode)) throw new TypeError('Invalid DingTalk mode');
   const id = requiredEndpointField(config.id, 'id');
   const appKey = requiredEndpointField(config.appKey, 'appKey');
   const appSecret = requiredEndpointField(config.appSecret, 'appSecret');
   const webhookPath = normalizeWebhookPath(config.webhookPath ?? '/dingtalk/webhook');
   const apiBaseUrl = (config.apiBaseUrl ?? 'https://oapi.dingtalk.com').replace(/\/$/, '');
   const robotCode = config.robotCode;
+  if (config.cardButtonCount !== undefined && (!Number.isInteger(config.cardButtonCount) || config.cardButtonCount < 1 || config.cardButtonCount > 5)) throw new TypeError('cardButtonCount must be 1..5');
   return {
+    ...(config.streamProxy ? { streamProxy: config.streamProxy } : {}),
     context: 'dingtalk',
+    mode: config.mode ?? 'webhook',
     id,
     appKey,
     appSecret,
     webhookPath,
     ...(robotCode ? { robotCode } : {}),
     apiBaseUrl,
+    ...(config.cardTemplateId ? { cardTemplateId: config.cardTemplateId } : {}),
+    cardButtonCount: config.cardButtonCount ?? 2,
   };
 }
 
@@ -233,9 +247,8 @@ export function verifySignature(
  * Segment canonicalization is intentionally not done here: media segments carry
  * the canonical `data.media` MediaRef and nothing else is consulted.
  *
- * 钉钉机器人媒体消息仅支持远程 URL（picture.picURL）：
- * - image 段 kind=url → 直发 picture；
- * - 其余 kind / audio / video / file 段无投递面，warn + 丢弃。
+ * 钉钉机器人图片使用官方 Markdown HTTP(S) 图片链接，保留同载荷文本和图片顺序。
+ * 本地媒体上传、原生引用、音频/视频/文件未接线，在请求前明确拒绝。
  */
 export function formatOutboundBody(payload: unknown): DingTalkSendBody {
   if (typeof payload === 'string') {
@@ -280,33 +293,37 @@ export function formatOutboundBody(payload: unknown): DingTalkSendBody {
         }
         break;
       }
+      case 'reply':
+        throw new EndpointDeliveryError('unsupported_operation', 'DingTalk native quoted replies are not implemented', 'not_sent');
+      case 'share': {
+        if (['audio', 'artist', 'duration', 'config'].some(key => data[key] !== undefined)) {
+          throw new EndpointDeliveryError('unsupported_operation', 'dingtalk rich share metadata is not implemented', 'not_sent');
+        }
+        let url: URL;
+        try { url = new URL(String(data.url ?? '')); } catch { throw new EndpointDeliveryError('invalid_payload', 'DingTalk share requires an HTTP(S) URL', 'not_sent'); }
+        if (!['https:', 'http:'].includes(url.protocol)) throw new EndpointDeliveryError('invalid_payload', 'DingTalk share requires an HTTP(S) URL', 'not_sent');
+        if (media) throw new EndpointDeliveryError('invalid_payload', 'DingTalk accepts one link card per message', 'not_sent');
+        media = { msgtype: 'link', link: { title: String(data.title ?? '链接'), text: String(data.description ?? data.content ?? ''), messageUrl: url.toString(), ...(typeof data.image === 'string' ? { picUrl: data.image } : {}) } };
+        break;
+      }
+      case 'keyboard':
+        throw new EndpointDeliveryError('unsupported_operation', 'DingTalk native keyboard callback requires an interactive card template and is not implemented', 'not_sent');
       case 'image': {
-        if (media) break;
         const ref = data.media;
         if (isMediaRef(ref) && ref.kind === 'url') {
-          media = {
-            msgtype: 'picture',
-            picture: { picURL: ref.value },
-          };
+          let url: URL;
+          try { url = new URL(ref.value); } catch { throw new EndpointDeliveryError('invalid_payload', 'DingTalk image requires an HTTP(S) URL', 'not_sent'); }
+          if (!['https:', 'http:'].includes(url.protocol)) throw new EndpointDeliveryError('invalid_payload', 'DingTalk image requires an HTTP(S) URL', 'not_sent');
+          markdownTitle ??= '消息';
+          textParts.push(`\n![](${ref.value.replace(/[()\s]/g, character => encodeURIComponent(character))})\n`);
           break;
         }
-        logger.warn(formatCompact({
-          op: 'dingtalk_outbound_media_dropped',
-          type: item.type,
-          reason: isMediaRef(ref) ? `unsupported_kind:${ref.kind}` : 'missing_media_ref',
-        }));
-        break;
+        throw new EndpointDeliveryError('unsupported_operation', 'DingTalk image upload is not implemented; use a canonical HTTP(S) URL', 'not_sent');
       }
       case 'audio':
       case 'video':
       case 'file':
-        // 钉钉机器人无音频/视频/文件投递面，warn + 丢弃
-        logger.warn(formatCompact({
-          op: 'dingtalk_outbound_media_dropped',
-          type: item.type,
-          reason: 'undeliverable_msgtype',
-        }));
-        break;
+        throw new EndpointDeliveryError('unsupported_operation', 'DingTalk audio/video/file delivery is not implemented', 'not_sent');
       case 'markdown':
         markdownTitle ??= String(data.title || '消息');
         textParts.push(String(data.content ?? data.text ?? ''));
@@ -329,7 +346,7 @@ export function formatOutboundBody(payload: unknown): DingTalkSendBody {
     }
   }
 
-  if (media) return media;
+  if (media) return media.link && textParts.length ? { ...media, link: { ...media.link, text: [...textParts, media.link.text].filter(Boolean).join('\n') } } : media;
   if (markdownTitle !== undefined) {
     return {
       msgtype: 'markdown',

package/src/stream-proxy.ts

@@ -0,0 +1,20 @@
+import tls from 'node:tls';
+import WebSocket from 'ws';
+import { getLogger } from '@zhin.js/logger';
+
+export interface DingTalkStreamProxy { readonly port: number; readonly serverName: string }
+
+/** Route TCP only. WSS HTTP Host, path, ticket, TLS SNI and peer validation stay original. */
+export function createDingTalkStreamSocket(url: string, proxy?: DingTalkStreamProxy): WebSocket {
+  if (!proxy) return new WebSocket(url);
+  const target = new URL(url);
+  if (target.protocol !== 'wss:' || target.hostname !== proxy.serverName || (target.port && target.port !== '443')) {
+    // The hostname is safe diagnostics; never print URL/query/ticket or SDK errors.
+    getLogger('dingtalk').warn(`Stream proxy rejected gateway hostname: ${target.hostname}`);
+    throw new Error('DingTalk Stream proxy gateway identity changed; update the fixed upstream before retrying');
+  }
+  return new WebSocket(url, {
+    createConnection: (options: import('node:http').ClientRequestArgs) => tls.connect({ ...options as tls.ConnectionOptions, path: undefined, host: '127.0.0.1', port: proxy.port,
+      servername: target.hostname, rejectUnauthorized: true }),
+  });
+}

package/src/stream.ts

@@ -0,0 +1,104 @@
+import { createDingTalkStreamSocket } from './stream-proxy.js';
+import { createEndpointLifecycle } from 'zhin.js/adapter';
+import type { DingTalkFetch } from './endpoint.js';
+import type { DingTalkEvent, ResolvedDingTalkConfig } from './protocol.js';
+
+export const CARD_TOPIC = '/v1.0/card/instances/callback';
+export const ROBOT_TOPIC = '/v1.0/im/bot/messages/get';
+export interface DingTalkStreamSocket {
+  on(event: string, listener: (...args: any[]) => void): unknown;
+  send(data: string): void;
+  terminate(): void;
+  ping(): void;
+}
+export type DingTalkStreamSocketFactory = (url: string) => DingTalkStreamSocket;
+
+/** Official gateway wire contract; reconnect/heartbeat belong to the shared lifecycle. */
+export class DingTalkStream {
+  readonly lifecycle;
+  #active?: AbortController;
+  #socket?: DingTalkStreamSocket;
+  #seen = new Map<string, number>();
+  #pending = new Set<string>();
+  constructor(
+    readonly config: ResolvedDingTalkConfig,
+    readonly fetch: DingTalkFetch,
+    readonly admit: (event: DingTalkEvent) => Promise<void>,
+    readonly isOpen: () => boolean,
+    readonly createSocket: DingTalkStreamSocketFactory = (url) => createDingTalkStreamSocket(url, config.streamProxy),
+    readonly admitCard?: (event: import('./cards.js').DingTalkCardCallback, id: string) => Promise<void>,
+  ) {
+    this.lifecycle = createEndpointLifecycle({ name: config.id, heartbeat: { intervalMs: 30_000, watchdogMisses: 2 } });
+  }
+  async start(): Promise<void> {
+    await this.lifecycle.start(async (handle) => {
+      const controller = new AbortController();
+      this.#active = controller;
+      const transport: { socket?: DingTalkStreamSocket } = {};
+      handle.onForceClose(() => { controller.abort(); transport.socket?.terminate(); });
+      const response = await this.fetch('https://api.dingtalk.com/v1.0/gateway/connections/open', {
+        method: 'POST', headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
+        body: JSON.stringify({ clientId: this.config.appKey, clientSecret: this.config.appSecret,
+          subscriptions: [{ type: 'CALLBACK', topic: ROBOT_TOPIC }, ...(this.admitCard && this.config.cardTemplateId ? [{ type: 'CALLBACK', topic: CARD_TOPIC }] : [])], ua: 'zhin.js' }),
+        signal: AbortSignal.any([controller.signal, AbortSignal.timeout(30_000)]),
+      });
+      if (!response.ok) throw new Error(`DingTalk Stream gateway HTTP ${response.status}`);
+      const gateway = await response.json() as { endpoint?: string; ticket?: string };
+      if (controller.signal.aborted) return;
+      if (!gateway.endpoint || !gateway.ticket) throw new Error('Invalid DingTalk Stream gateway response');
+      const url = new URL(gateway.endpoint);
+      if (url.protocol !== 'wss:') throw new Error('DingTalk Stream requires WSS');
+      url.searchParams.set('ticket', gateway.ticket);
+      const current = this.createSocket(url.toString());
+      transport.socket = current;
+      this.#socket = current;
+      await new Promise<void>((resolve, reject) => {
+        const timer = setTimeout(() => { current.terminate(); reject(new Error('DingTalk Stream connection timeout')); }, 30_000);
+        const clear = () => clearTimeout(timer);
+        controller.signal.addEventListener('abort', clear, { once: true });
+        current.on('open', () => {
+          if (controller.signal.aborted || this.#socket !== current) { current.terminate(); return; }
+          clear(); this.lifecycle.startHeartbeat(() => current.ping()); resolve();
+        });
+        current.on('error', () => { clear(); current.terminate(); reject(new Error('DingTalk Stream transport error')); });
+        current.on('close', () => { clear(); if (this.#socket === current) this.#socket = undefined;
+          handle.notifyClosed('transport closed'); reject(new Error('DingTalk Stream closed before connection')); });
+        current.on('pong', () => { if (!controller.signal.aborted) this.lifecycle.notifyHeartbeatAck(); });
+        current.on('message', (raw: { toString(): string }) => {
+          if (controller.signal.aborted || this.#socket !== current) return;
+          this.lifecycle.notifyHeartbeatAck();
+          let frame: { type?: string; headers?: { topic?: string; messageId?: string }; data?: string };
+          try { frame = JSON.parse(raw.toString()); } catch { return; }
+          if (frame.type === 'SYSTEM') {
+            // REGISTERED is optional; successful WSS handshake already establishes the subscribed transport.
+            if (frame.headers?.topic === 'ping' || frame.headers?.topic === 'disconnect') {
+              current.send(JSON.stringify({ code: 200, headers: frame.headers, message: 'OK', data: frame.data }));
+              if (frame.headers.topic === 'disconnect') current.terminate();
+            }
+            return;
+          }
+          if (frame.type !== 'CALLBACK' || ![ROBOT_TOPIC, ...(this.admitCard && this.config.cardTemplateId ? [CARD_TOPIC] : [])].includes(frame.headers?.topic ?? '') || !frame.headers?.messageId) return;
+          const id = frame.headers.messageId;
+          const ack = () => { if (!controller.signal.aborted && this.#socket === current) current.send(JSON.stringify({ code: 200,
+            headers: { contentType: 'application/json', messageId: id }, message: 'OK', data: JSON.stringify({ response: null }) })); };
+          const now = Date.now();
+          for (const [key, time] of this.#seen) if (now - time > 300_000) this.#seen.delete(key);
+          if (this.#seen.has(id)) { ack(); return; }
+          if (!this.isOpen() || this.#pending.has(id) || this.#pending.size >= 100) return;
+          let event: DingTalkEvent | import('./cards.js').DingTalkCardCallback;
+          try { event = JSON.parse(frame.data ?? ''); } catch { return; }
+          const card = frame.headers.topic === CARD_TOPIC;
+          if (!event || typeof event !== 'object' || (!card && !(event as DingTalkEvent).msgtype)) return;
+          this.#pending.add(id);
+          void (card ? this.admitCard!(event as import('./cards.js').DingTalkCardCallback, id) : this.admit(event as DingTalkEvent)).then(() => {
+            if (controller.signal.aborted) return;
+            this.#seen.set(id, Date.now());
+            while (this.#seen.size > 10_000) this.#seen.delete(this.#seen.keys().next().value!);
+            ack();
+          }).catch(() => { /* no ACK: allow server retry */ }).finally(() => this.#pending.delete(id));
+        });
+      });
+    });
+  }
+  async stop(): Promise<void> { this.#active?.abort(); await this.lifecycle.stop(); this.#socket = undefined; this.#seen.clear(); }
+}

package/src/webhook.ts

@@ -17,7 +17,7 @@ const logger = getLogger('dingtalk');
 export interface DingTalkWebhookHandler {
   readonly config: ResolvedDingTalkConfig;
   readonly isOpen: boolean;
-  admit(event: DingTalkEvent): void;
+  admit(event: DingTalkEvent): void | Promise<void>;
 }
 
 export function registerDingTalkWebhookRoutes(
@@ -62,7 +62,7 @@ export async function handleDingTalkWebhookRequest(
     }
 
     if (event.msgtype && handler.isOpen) {
-      handler.admit(event);
+      await handler.admit(event);
     }
 
     response.writeHead(200, { 'Content-Type': 'application/json' });