dsh-caduceus 0.1.1 → 0.5.1

package/dist/transport/normalize.js

@@ -1,48 +1,151 @@
-const MENTION_PATTERN = /<at[^>]*>.*?<\/at>/g;
-/** Message types the v0.1 surface handles (attachments are v0.2). */
-const SUPPORTED_MESSAGE_TYPES = new Set(['text']);
+/**
+ * Pure normalization of a Feishu `im.message.receive_v1` payload.
+ *
+ * The topic identity is the whole point of this module: the bridge keys
+ * sessions by `(chatId, threadId)`, and the bot must answer in the same topic
+ * (design doc A6). Feishu puts the topic id in `thread_id`; older/related
+ * shapes only carry `root_id`, so the rule is:
+ *
+ *     threadId = message.thread_id ?? message.root_id
+ *
+ * Non-human senders (`sender.sender_type !== 'user'`) are dropped FIRST, before
+ * any other judgement: a bot/app event (e.g. an app self-improvement notice)
+ * must never become a session prompt or a fallback title. Feishu events from
+ * humans carry `sender_type: 'user'`; a missing sender_type is treated as
+ * non-human on purpose (fail closed).
+ *
+ * Mention open ids are preserved so the bridge can enforce the group @ gate.
+ *
+ * @module dsh-caduceus/transport/normalize
+ */
+import { stripLeadingMentions } from '../mentions.js';
+const AT_TAG_PATTERN = /<at[^>]*>(.*?)<\/at>/gs;
+/** Message types the surface can process (attachments included). */
+const KNOWN_MESSAGE_TYPES = new Set(['text', 'image', 'file', 'post']);
+function restoreMentions(text, rawMentions, botOpenId) {
+    text = text.replace(AT_TAG_PATTERN, (_match, inner) => ` @${inner.trim().replace(/^@/, '')} `);
+    text = text.replace(/\r\n?/g, '\n');
+    const entries = rawMentions
+        .map((mention) => ({ key: mention.key, name: mention.name, openId: mention.id?.open_id }))
+        .filter((entry) => entry.key !== undefined || entry.name !== undefined || entry.openId !== undefined);
+    if (entries.length === 0)
+        return stripLeadingMentions(text.trim()).trim();
+    for (const entry of entries) {
+        const own = botOpenId !== undefined && botOpenId.length > 0 && entry.openId === botOpenId;
+        if (!own)
+            continue;
+        if (entry.key !== undefined && entry.key.length > 0)
+            text = text.split(entry.key).join(' ');
+        if (entry.name !== undefined && entry.name.length > 0)
+            text = text.split(`@${entry.name}`).join(' ');
+    }
+    const replaceable = entries
+        .filter((entry) => entry.name !== undefined && entry.name.length > 0 && entry.key !== undefined)
+        .sort((left, right) => (right.key?.length ?? 0) - (left.key?.length ?? 0));
+    for (const entry of replaceable) {
+        text = text.split(entry.key).join(`@${entry.name}`);
+    }
+    return text.replace(/[ \t]{2,}/g, ' ').trim();
+}
+function postParts(parsed) {
+    const attachments = [];
+    const texts = [];
+    if (typeof parsed.title === 'string' && parsed.title.trim().length > 0) {
+        texts.push(parsed.title.trim());
+    }
+    const flatten = (value) => {
+        if (!Array.isArray(value))
+            return;
+        for (const item of value) {
+            if (Array.isArray(item)) {
+                flatten(item);
+                continue;
+            }
+            if (typeof item !== 'object' || item === null)
+                continue;
+            const block = item;
+            if (block.tag === 'text' && typeof block.text === 'string')
+                texts.push(block.text);
+            if ((block.tag === 'img' || block.tag === 'image') &&
+                typeof block.image_key === 'string' &&
+                block.image_key.length > 0) {
+                attachments.push({ kind: 'image', fileKey: block.image_key });
+            }
+        }
+    };
+    flatten(parsed.content);
+    return { text: texts.join(' '), attachments };
+}
 /**
  * Normalize one raw event.
  *
  * @returns the normalized message, or `undefined` for unsupported/malformed
- *   payloads or empty text.
+ *   payloads or empty text. Unsupported message types return a message with
+ *   `unsupportedType` so the bridge can reply and react explicitly.
  */
-export function normalizeMessageEvent(raw) {
-    // Priority #1: only human messages may enter a session.
+export function normalizeMessageEvent(raw, botOpenId) {
     const senderType = raw.sender?.sender_type;
     if (senderType !== 'user')
         return undefined;
     const message = raw.message;
-    if (!SUPPORTED_MESSAGE_TYPES.has(message.message_type))
-        return undefined;
-    let text;
-    try {
-        const parsed = JSON.parse(message.content);
-        if (typeof parsed.text !== 'string')
-            return undefined;
-        text = parsed.text;
-    }
-    catch {
-        return undefined;
-    }
-    text = text.replace(MENTION_PATTERN, ' ').replace(/\r\n?/g, '\n').trim();
-    if (text.length === 0)
-        return undefined;
     const threadId = firstNonEmpty(message.thread_id, message.root_id);
     const rootId = firstNonEmpty(message.root_id);
     const mentions = (message.mentions ?? [])
         .map((mention) => mention.id?.open_id)
         .filter((openId) => typeof openId === 'string' && openId.length > 0);
-    return {
+    const base = () => ({
         messageId: message.message_id,
         chatId: message.chat_id,
         chatType: message.chat_type === 'group' ? 'group' : 'p2p',
         senderOpenId: raw.sender?.sender_id?.open_id ?? '',
         ...(mentions.length === 0 ? {} : { mentions }),
-        text,
         ...(threadId === undefined ? {} : { threadId }),
         ...(rootId === undefined ? {} : { rootId }),
         createdAt: Number(message.create_time) || 0,
+    });
+    let parsed;
+    try {
+        parsed = JSON.parse(message.content);
+    }
+    catch {
+        return undefined;
+    }
+    if (!KNOWN_MESSAGE_TYPES.has(message.message_type)) {
+        return { ...base(), text: '', unsupportedType: message.message_type };
+    }
+    let text = '';
+    let attachments = [];
+    if (message.message_type === 'image') {
+        if (typeof parsed.image_key !== 'string' || parsed.image_key.length === 0)
+            return undefined;
+        attachments = [{ kind: 'image', fileKey: parsed.image_key }];
+    }
+    else if (message.message_type === 'file') {
+        if (typeof parsed.file_key !== 'string' || parsed.file_key.length === 0)
+            return undefined;
+        attachments = [{
+                kind: 'file',
+                fileKey: parsed.file_key,
+                ...(typeof parsed.file_name === 'string' && parsed.file_name.length > 0
+                    ? { fileName: parsed.file_name }
+                    : {}),
+            }];
+    }
+    else if (message.message_type === 'post') {
+        const parts = postParts(parsed);
+        text = parts.text;
+        attachments = parts.attachments;
+    }
+    else {
+        text = typeof parsed.text === 'string' ? parsed.text : '';
+    }
+    text = restoreMentions(text, message.mentions ?? [], botOpenId);
+    if (text.length === 0 && attachments.length === 0)
+        return undefined;
+    return {
+        ...base(),
+        text,
+        ...(attachments.length === 0 ? {} : { attachments }),
     };
 }
 function firstNonEmpty(...values) {
@@ -52,3 +155,25 @@ function firstNonEmpty(...values) {
     }
     return undefined;
 }
+/** Normalize Feishu's card click into the transport's CardAction. */
+export function normalizeCardAction(raw) {
+    const operatorOpenId = raw.operator?.open_id ?? raw.open_id ?? '';
+    const messageId = raw.context?.open_message_id ?? raw.open_message_id ?? '';
+    const chatId = raw.context?.open_chat_id ?? raw.open_chat_id ?? '';
+    const value = raw.action?.value;
+    if (operatorOpenId.length === 0 || messageId.length === 0)
+        return undefined;
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const rawForm = raw.action?.form_value;
+    const formValue = typeof rawForm === 'object' && rawForm !== null
+        ? Object.fromEntries(Object.entries(rawForm).filter((entry) => typeof entry[1] === 'string'))
+        : undefined;
+    return {
+        operatorOpenId,
+        messageId,
+        chatId,
+        value,
+        ...(formValue === undefined || Object.keys(formValue).length === 0 ? {} : { formValue }),
+    };
+}

package/dist/transport/reliable.d.ts

@@ -1,6 +1,6 @@
 import { type LoggerLike } from '../logger.js';
 import type { FeishuApi } from './feishu-api.js';
-import type { FeishuCard, InboundMessage, ReplyOptions, ReplyPayload, SendOptions, SentMessage, Transport } from './types.js';
+import type { CardAction, FeishuCard, InboundMessage, ReplyOptions, ReplyPayload, SendOptions, SentMessage, Transport } from './types.js';
 export interface ReliableTransportOptions {
     readonly logger?: LoggerLike;
     /** Idempotency-key factory (injectable for deterministic tests). */
@@ -16,8 +16,10 @@ export declare class ReliableTransport implements Transport {
     start(): Promise<void>;
     stop(): Promise<void>;
     onMessage(handler: (message: InboundMessage) => void): void;
+    onCardAction(handler: (action: CardAction) => void): void;
     /** Forward the bot open id when the underlying API resolved one. */
     getBotOpenId(): string | undefined;
+    refreshBotOpenId(): Promise<string | undefined>;
     getBotName(): string | undefined;
     getConnectionStatus(): {
         readonly ready: boolean;
@@ -30,6 +32,12 @@ export declare class ReliableTransport implements Transport {
     };
     sendText(chatId: string, text: string, options?: SendOptions): Promise<SentMessage>;
     sendCard(chatId: string, card: FeishuCard, options?: SendOptions): Promise<SentMessage>;
+    addReaction(messageId: string, emojiType: string): Promise<string>;
+    removeReaction(messageId: string, reactionId: string): Promise<void>;
+    downloadResource(messageId: string, fileKey: string, type: 'image' | 'file', maxBytes: number): Promise<{
+        readonly bytes: Uint8Array;
+        readonly contentType?: string;
+    }>;
     updateCard(messageId: string, card: FeishuCard): Promise<void>;
     reply(chatId: string, messageId: string, payload: ReplyPayload, options?: ReplyOptions): Promise<SentMessage>;
 }

package/dist/transport/reliable.js

@@ -37,10 +37,16 @@ export class ReliableTransport {
     onMessage(handler) {
         this.api.onMessage(handler);
     }
+    onCardAction(handler) {
+        this.api.onCardAction?.(handler);
+    }
     /** Forward the bot open id when the underlying API resolved one. */
     getBotOpenId() {
         return this.api.getBotOpenId?.();
     }
+    refreshBotOpenId() {
+        return this.api.refreshBotOpenId?.() ?? Promise.resolve(this.api.getBotOpenId?.());
+    }
     getBotName() {
         return this.api.getBotName?.();
     }
@@ -94,6 +100,15 @@ export class ReliableTransport {
             uuid: options.uuid ?? this.uuidFactory(),
         }));
     }
+    addReaction(messageId, emojiType) {
+        return this.api.addReaction(messageId, emojiType);
+    }
+    removeReaction(messageId, reactionId) {
+        return this.api.removeReaction(messageId, reactionId);
+    }
+    downloadResource(messageId, fileKey, type, maxBytes) {
+        return this.api.downloadResource(messageId, fileKey, type, maxBytes);
+    }
     async updateCard(messageId, card) {
         assertUpdateMulti(card);
         await this.#recordVoid('卡片', () => this.api.patchCard(messageId, card));

package/dist/transport/types.d.ts

@@ -46,6 +46,26 @@ export interface InboundMessage {
     readonly rootId?: string;
     /** Unix epoch milliseconds from Feishu; `0` when the event omitted it. */
     readonly createdAt: number;
+    /** Image/file attachments carried by this message. */
+    readonly attachments?: readonly InboundAttachment[];
+    /** Set for message types caduceus cannot process (audio/video/sticker/...). */
+    readonly unsupportedType?: string;
+}
+/** One inbound attachment reference (image/file message or post image). */
+export interface InboundAttachment {
+    readonly kind: 'image' | 'file';
+    readonly fileKey: string;
+    readonly fileName?: string;
+    readonly mediaType?: string;
+}
+/** One interactive-card button click, normalized for the bridge. */
+export interface CardAction {
+    readonly operatorOpenId: string;
+    readonly messageId: string;
+    readonly chatId: string;
+    readonly value: Record<string, unknown>;
+    /** Feishu form fields submitted with the action (`action.form_value`). */
+    readonly formValue?: Readonly<Record<string, string>>;
 }
 /** A created message. */
 export interface SentMessage {
@@ -110,11 +130,22 @@ export interface Transport {
     sendText(chatId: string, text: string, options?: SendOptions): Promise<SentMessage>;
     sendCard(chatId: string, card: FeishuCard, options?: SendOptions): Promise<SentMessage>;
     updateCard(messageId: string, card: FeishuCard): Promise<void>;
+    /** Add one emoji reaction; resolves the reaction id. */
+    addReaction(messageId: string, emojiType: string): Promise<string>;
+    /** Remove one reaction previously added by this bot. */
+    removeReaction(messageId: string, reactionId: string): Promise<void>;
+    /** Download a message resource (image/file), enforcing a byte limit. */
+    downloadResource(messageId: string, fileKey: string, type: 'image' | 'file', maxBytes: number): Promise<{
+        readonly bytes: Uint8Array;
+        readonly contentType?: string;
+    }>;
     /**
      * The bot's own open id when known (needed for the group @ gate). Optional:
      * fake transports may omit it, and the real one resolves it lazily.
      */
     getBotOpenId?(): string | undefined;
+    /** Retry bot identity resolution (group @ gate). */
+    refreshBotOpenId?(): Promise<string | undefined>;
     /** Cached bot display name (resolved at startup; no extra API call). */
     getBotName?(): string | undefined;
     /** Long-connection status/start time, when known. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-caduceus",
-  "version": "0.1.1",
+  "version": "0.5.1",
   "description": "Feishu/Lark surface plugin for DeepSeek Harness (dsh): one topic per session, SOUL persona sync, streaming process cards, /status and /doctor.",
   "type": "module",
   "main": "./dist/index.js",