@controlflow-ai/daemon 0.1.2 → 0.1.4

package/src/lark/ws-daemon.ts

@@ -10,13 +10,22 @@ export type LarkEventCallback = (event: {
   storeResult: StoreInboundEventResult;
 }) => void | Promise<void>;
 
+export type LarkWebSocketLifecycleCallback = (event: {
+  appId: string;
+  type: 'ready' | 'reconnecting' | 'reconnected' | 'error';
+  error?: string;
+}) => void;
+
 export interface StartLarkDaemonOptions {
   appId: string;
   appSecret: string;
   db: Database;
   onEvent?: LarkEventCallback;
+  onLifecycle?: LarkWebSocketLifecycleCallback;
   logger?: Partial<Pick<Console, 'info' | 'warn' | 'error'>>;
   loggerLevel?: Lark.LoggerLevel;
+  handshakeTimeoutMs?: number;
+  pingTimeoutSec?: number;
 }
 
 export interface LarkDaemonHandle {
@@ -26,6 +35,44 @@ export interface LarkDaemonHandle {
 }
 
 const SUPPORTED_EVENTS = ['im.message.receive_v1', 'card.action.trigger'] as const;
+const silentLarkLogger = {
+  error() {},
+  warn() {},
+  info() {},
+  debug() {},
+  trace() {},
+};
+
+function nestedString(value: unknown, path: string[]): string | null {
+  let current = value;
+  for (const key of path) {
+    if (!current || typeof current !== 'object') return null;
+    current = (current as Record<string, unknown>)[key];
+  }
+  return typeof current === 'string' && current.length > 0 ? current : null;
+}
+
+export function stableLarkEventId(eventName: string, data: unknown): string | null {
+  const headerId = nestedString(data, ['header', 'event_id'])
+    ?? nestedString(data, ['event_id']);
+  if (headerId) return headerId;
+  const derivedId = nestedString(data, ['message', 'message_id'])
+    ?? nestedString(data, ['message', 'open_message_id'])
+    ?? nestedString(data, ['open_message_id']);
+  if (derivedId) return `${eventName}:${derivedId}`;
+  const operatorId = nestedString(data, ['operator', 'operator_id', 'open_id']);
+  if (operatorId) return `${eventName}:${operatorId}:${nestedString(data, ['token']) ?? ''}`;
+  return null;
+}
+
+export function buildLarkEventRawBody(eventName: string, data: unknown): string {
+  const eventId = stableLarkEventId(eventName, data);
+  return JSON.stringify({
+    schema: '2.0',
+    header: eventId ? { event_id: eventId, event_type: eventName } : { event_type: eventName },
+    event: data,
+  });
+}
 
 /**
  * Start a Lark WSClient that subscribes to im.message.receive_v1 +
@@ -45,7 +92,7 @@ export function startLarkDaemon(options: StartLarkDaemonOptions): LarkDaemonHand
   const handlers: Record<string, (data: unknown) => Promise<unknown>> = {};
   for (const eventName of SUPPORTED_EVENTS) {
     handlers[eventName] = async (data) => {
-      const rawBody = JSON.stringify({ schema: '2.0', header: { event_type: eventName }, event: data });
+      const rawBody = buildLarkEventRawBody(eventName, data);
       try {
         const storeResult = await storeInboundEvent(options.db, { appId: options.appId, rawBody });
         if (storeResult.duplicate) {
@@ -75,6 +122,24 @@ export function startLarkDaemon(options: StartLarkDaemonOptions): LarkDaemonHand
     appId: options.appId,
     appSecret: options.appSecret,
     loggerLevel: options.loggerLevel ?? Lark.LoggerLevel.warn,
+    handshakeTimeoutMs: options.handshakeTimeoutMs ?? 15_000,
+    wsConfig: { pingTimeout: options.pingTimeoutSec ?? 10 },
+    onReady: () => {
+      options.onLifecycle?.({ appId: options.appId, type: 'ready' });
+      log.info?.(`[lark/${options.appId}] WSClient ready`);
+    },
+    onReconnecting: () => {
+      options.onLifecycle?.({ appId: options.appId, type: 'reconnecting' });
+      log.warn?.(`[lark/${options.appId}] WSClient reconnecting`);
+    },
+    onReconnected: () => {
+      options.onLifecycle?.({ appId: options.appId, type: 'reconnected' });
+      log.info?.(`[lark/${options.appId}] WSClient reconnected`);
+    },
+    onError: (err) => {
+      options.onLifecycle?.({ appId: options.appId, type: 'error', error: err.message });
+      log.error?.(`[lark/${options.appId}] WSClient error: ${err.message}`);
+    },
   });
 
   wsClient.start({ eventDispatcher });
@@ -103,35 +168,96 @@ export function createLarkApiClient(appId: string, appSecret: string): Lark.Clie
   return new Lark.Client({
     appId,
     appSecret,
-    loggerLevel: Lark.LoggerLevel.warn,
+    loggerLevel: Lark.LoggerLevel.fatal,
+    logger: silentLarkLogger,
   });
 }
 
-export interface SendTextMessageInput {
+export type LarkReceiveIdType = 'chat_id' | 'open_id' | 'union_id' | 'email' | 'user_id';
+
+export interface LarkMentionTarget {
+  openId: string;
+  displayName?: string | null;
+}
+
+interface SendMessageBaseInput {
   client: Lark.Client;
-  receiveIdType: 'chat_id' | 'open_id' | 'union_id' | 'email' | 'user_id';
+  receiveIdType: LarkReceiveIdType;
   receiveId: string;
   text: string;
+  mention?: LarkMentionTarget | null;
 }
 
+export interface SendTextMessageInput extends SendMessageBaseInput {}
+
+export interface SendCardMessageInput extends SendMessageBaseInput {}
+
 export interface SendTextMessageResult {
   messageId?: string;
   raw: unknown;
 }
 
-export async function sendTextMessage(input: SendTextMessageInput): Promise<SendTextMessageResult> {
+export interface LarkMessageCreatePayload {
+  receive_id: string;
+  msg_type: 'text' | 'interactive';
+  content: string;
+}
+
+function escapeLarkText(value: string): string {
+  return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+function larkMentionSuffix(mention: LarkMentionTarget | null | undefined, tag: 'text' | 'card'): string {
+  if (!mention?.openId) return '';
+  const idAttribute = tag === 'text' ? 'user_id' : 'id';
+  return `\n\n<at ${idAttribute}="${mention.openId}">${escapeLarkText(mention.displayName ?? '')}</at>`;
+}
+
+function larkMessageBody(input: Pick<SendMessageBaseInput, 'text' | 'mention'>, tag: 'text' | 'card'): string {
+  return `${input.text}${larkMentionSuffix(input.mention, tag)}`;
+}
+
+export function buildLarkTextMessagePayload(input: Pick<SendTextMessageInput, 'receiveId' | 'text' | 'mention'>): LarkMessageCreatePayload {
+  return {
+    receive_id: input.receiveId,
+    msg_type: 'text',
+    content: JSON.stringify({ text: larkMessageBody(input, 'text') }),
+  };
+}
+
+export function buildLarkMentionCardPayload(input: Pick<SendCardMessageInput, 'receiveId' | 'text' | 'mention'>): LarkMessageCreatePayload {
+  return {
+    receive_id: input.receiveId,
+    msg_type: 'interactive',
+    content: JSON.stringify({
+      config: { wide_screen_mode: true },
+      elements: [
+        {
+          tag: 'markdown',
+          content: larkMessageBody(input, 'card'),
+        },
+      ],
+    }),
+  };
+}
+
+async function createLarkMessage(input: SendMessageBaseInput, payload: LarkMessageCreatePayload): Promise<SendTextMessageResult> {
   const response = await input.client.im.message.create({
     params: { receive_id_type: input.receiveIdType },
-    data: {
-      receive_id: input.receiveId,
-      msg_type: 'text',
-      content: JSON.stringify({ text: input.text }),
-    },
+    data: payload,
   });
   const messageId = (response?.data as { message_id?: string } | undefined)?.message_id;
   return { messageId, raw: response };
 }
 
+export async function sendTextMessage(input: SendTextMessageInput): Promise<SendTextMessageResult> {
+  return createLarkMessage(input, buildLarkTextMessagePayload(input));
+}
+
+export async function sendCardMessage(input: SendCardMessageInput): Promise<SendTextMessageResult> {
+  return createLarkMessage(input, buildLarkMentionCardPayload(input));
+}
+
 export interface AddMessageReactionInput {
   client: Lark.Client;
   messageId: string;