abs-zalo-bot 0.7.2 → 0.8.0

package/mcp/server.js

@@ -844,7 +844,8 @@ server.tool(
       "create_note", "change_avatar", "block_member", "unblock_member", "review_pending",
       "group_link_enable", "group_link_disable", "send_card", "send_bank_card",
       "friend_accept", "friend_reject", "friend_request", "friend_request_undo", "friend_remove",
-      "user_block", "user_unblock"
+      "user_block", "user_unblock",
+      "join_group_link", "join_group_invite_box", "get_group_link_info", "get_sticker_detail", "search_stickers"
     ]),
     payload: z.record(z.unknown()).describe("Action-specific fields; inspect bridge docs before invoking."),
     confirm: z.literal(true).describe("Must be true after the operator explicitly confirms the exact side effect."),
@@ -856,6 +857,110 @@ server.tool(
   },
 );
 
+server.tool(
+  "abs_zalo_join_group_link",
+  "Automatically join a Zalo group via invite link (e.g. https://zalo.me/g/...).",
+  {
+    link: z.string().describe("Group invite link or code"),
+    account_id: z.string().optional(),
+  },
+  async ({ link, account_id }) => {
+    try {
+      return ok(await bridge("/api/groups/join-link", { method: "POST", body: { link, account_id } }));
+    } catch (e) {
+      return fail(e);
+    }
+  },
+);
+
+server.tool(
+  "abs_zalo_get_group_link_info",
+  "Inspect group details from an invite link before joining.",
+  {
+    link: z.string().describe("Group invite link or code"),
+    account_id: z.string().optional(),
+  },
+  async ({ link, account_id }) => {
+    try {
+      return ok(await bridge("/api/groups/link-info", { method: "POST", body: { link, account_id } }));
+    } catch (e) {
+      return fail(e);
+    }
+  },
+);
+
+server.tool(
+  "abs_zalo_join_invite_box",
+  "Accept an invitation to join a group.",
+  {
+    group_id: z.string().describe("Target Zalo group ID"),
+    account_id: z.string().optional(),
+  },
+  async ({ group_id, account_id }) => {
+    try {
+      return ok(await bridge("/api/groups/join-invite-box", { method: "POST", body: { group_id, account_id } }));
+    } catch (e) {
+      return fail(e);
+    }
+  },
+);
+
+server.tool(
+  "abs_zalo_get_sticker_detail",
+  "Get text description and image URL of a Zalo sticker by its ID.",
+  {
+    sticker_id: z.number().describe("Numeric sticker ID"),
+    account_id: z.string().optional(),
+  },
+  async ({ sticker_id, account_id }) => {
+    try {
+      return ok(await bridge(`/api/stickers/${encodeURIComponent(sticker_id)}${account_id ? `?account_id=${account_id}` : ""}`));
+    } catch (e) {
+      return fail(e);
+    }
+  },
+);
+
+server.tool(
+  "abs_zalo_search_stickers",
+  "Search Zalo stickers by keyword.",
+  {
+    keyword: z.string().describe("Keyword to search"),
+    account_id: z.string().optional(),
+  },
+  async ({ keyword, account_id }) => {
+    try {
+      return ok(await bridge(`/api/stickers/search?keyword=${encodeURIComponent(keyword)}${account_id ? `&account_id=${account_id}` : ""}`));
+    } catch (e) {
+      return fail(e);
+    }
+  },
+);
+
+server.tool(
+  "abs_zalo_history_range",
+  "Read chat message history across hours (since_hours, up to 168h / 7 days) from local SQLite store to summarize group discussions without calling Zalo API.",
+  {
+    group_id: z.string().describe("Target group or user ID"),
+    since_hours: z.number().optional().describe("Number of hours of history to read (default: 24, max: 168)"),
+    limit: z.number().optional().describe("Number of messages per page (default: 50, max: 100)"),
+    cursor: z.string().optional().describe("Pagination cursor for older messages"),
+    account_id: z.string().optional(),
+  },
+  async ({ group_id, since_hours, limit, cursor, account_id }) => {
+    try {
+      const q = new URLSearchParams();
+      if (since_hours) q.set("since_hours", String(since_hours));
+      if (limit) q.set("limit", String(limit));
+      if (cursor) q.set("cursor", String(cursor));
+      if (account_id) q.set("account_id", String(account_id));
+      return ok(await bridge(`/api/groups/${encodeURIComponent(group_id)}/history-range?${q.toString()}`));
+    } catch (e) {
+      return fail(e);
+    }
+  },
+);
+
 // Backward-compatibility aliases for older prompts
 server.tool("zalo_status", "Alias for abs_zalo_status", {}, async () => bridge("/api/status").then(ok).catch(fail));
 server.tool("zalo_list_groups", "Alias for abs_zalo_list_groups", { account_id: z.string().optional() }, async ({ account_id }) => bridge(`/api/sources${account_id ? `?account_id=${account_id}` : ""}`).then(ok).catch(fail));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "abs-zalo-bot",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "type": "module",
   "description": "ABS Zalo Agent Engine — Free, Transparent & Autonomous Zalo AI Agent Engine for Hermes, Claude Code & Codex. Dual Personal QR + Official OA, Group Administration, Lead Intel, Polls, Reactions & MCP Server.",
   "author": "teddiesloco",

package/src/server.js

@@ -800,6 +800,91 @@ export function createApp({
     }
   });
 
+  app.post("/api/groups/join-link", async (req, res) => {
+    try {
+      const accountId = req.body?.account_id || config.default_account_id;
+      const { link } = req.body || {};
+      if (!link) return res.status(400).json({ ok: false, error: "link_required" });
+      const runtime = hub.getRuntime(accountId);
+      if (!runtime.api) return res.status(400).json({ ok: false, error: "not_connected" });
+      const result = await runtime.joinGroupLink(link);
+      res.json({ ok: true, result });
+    } catch (err) {
+      res.status(500).json({ ok: false, error: String(err?.message || err) });
+    }
+  });
+
+  app.post("/api/groups/link-info", async (req, res) => {
+    try {
+      const accountId = req.body?.account_id || config.default_account_id;
+      const { link } = req.body || {};
+      if (!link) return res.status(400).json({ ok: false, error: "link_required" });
+      const runtime = hub.getRuntime(accountId);
+      if (!runtime.api) return res.status(400).json({ ok: false, error: "not_connected" });
+      const result = await runtime.getGroupLinkInfo(link);
+      res.json({ ok: true, result });
+    } catch (err) {
+      res.status(500).json({ ok: false, error: String(err?.message || err) });
+    }
+  });
+
+  app.post("/api/groups/join-invite-box", async (req, res) => {
+    try {
+      const accountId = req.body?.account_id || config.default_account_id;
+      const { group_id } = req.body || {};
+      if (!group_id) return res.status(400).json({ ok: false, error: "group_id_required" });
+      const runtime = hub.getRuntime(accountId);
+      if (!runtime.api) return res.status(400).json({ ok: false, error: "not_connected" });
+      const result = await runtime.joinGroupInviteBox(group_id);
+      res.json({ ok: true, result });
+    } catch (err) {
+      res.status(500).json({ ok: false, error: String(err?.message || err) });
+    }
+  });
+
+  app.get("/api/stickers/search", async (req, res) => {
+    try {
+      const accountId = req.query?.account_id || config.default_account_id;
+      const keyword = String(req.query?.keyword || "").trim();
+      if (!keyword) return res.status(400).json({ ok: false, error: "keyword_required" });
+      const runtime = hub.getRuntime(accountId);
+      if (!runtime.api) return res.status(400).json({ ok: false, error: "not_connected" });
+      const result = await runtime.searchStickers(keyword);
+      res.json({ ok: true, result });
+    } catch (err) {
+      res.status(500).json({ ok: false, error: String(err?.message || err) });
+    }
+  });
+
+  app.get("/api/stickers/:stickerId", async (req, res) => {
+    try {
+      const accountId = req.query?.account_id || config.default_account_id;
+      const runtime = hub.getRuntime(accountId);
+      if (!runtime.api) return res.status(400).json({ ok: false, error: "not_connected" });
+      const result = await runtime.getStickerDetail(req.params.stickerId);
+      res.json({ ok: true, result });
+    } catch (err) {
+      res.status(500).json({ ok: false, error: String(err?.message || err) });
+    }
+  });
+
+  app.get("/api/groups/:groupId/history-range", async (req, res) => {
+    try {
+      const sinceHours = req.query?.since_hours ? Number(req.query.since_hours) : 24;
+      const limit = req.query?.limit ? Number(req.query.limit) : 50;
+      const cursor = req.query?.cursor || null;
+      const result = store.readHistoryRange({
+        sourceId: req.params.groupId,
+        sinceHours,
+        cursor,
+        limit,
+      });
+      res.json({ ok: true, ...result });
+    } catch (err) {
+      res.status(500).json({ ok: false, error: String(err?.message || err) });
+    }
+  });
+
   app.post("/api/groups/:groupId/link", async (req, res) => {
     try {
       const accountId = req.body?.account_id || config.default_account_id;

package/src/store.js

@@ -710,6 +710,51 @@ export class Store {
     return this.db.prepare(sql).all(...params);
   }
 
+  /**
+   * Đọc dải lịch sử chat theo giờ (sinceHours) từ SQLite nội bộ để phục vụ
+   * tóm tắt thảo luận nhóm mà không cần gọi Zalo API.
+   */
+  readHistoryRange({ sourceId, sinceHours = 24, cursor = null, limit = 50 } = {}) {
+    const hours = Math.min(Math.max(Number(sinceHours) || 24, 1), 168);
+    const lim = Math.min(Math.max(Number(limit) || 50, 1), 100);
+    const sinceIso = new Date(Date.now() - hours * 3600 * 1000).toISOString();
+
+    let sql = `SELECT id, source_id, source_name, sender_display_name, text_redacted, created_at
+      FROM zalo_messages
+      WHERE source_id = ? AND created_at >= ?`;
+    const params = [String(sourceId), sinceIso];
+
+    if (cursor) {
+      sql += ` AND created_at < ?`;
+      params.push(String(cursor));
+    }
+
+    sql += ` ORDER BY created_at DESC LIMIT ?`;
+    params.push(lim + 1);
+
+    const rows = this.db.prepare(sql).all(...params);
+    const hasMore = rows.length > lim;
+    const items = hasMore ? rows.slice(0, lim) : rows;
+    const nextCursor = hasMore && items.length > 0 ? items[items.length - 1].created_at : null;
+
+    // Đảo thứ tự để hiển thị xuôi dòng thời gian (từ cũ đến mới)
+    items.reverse();
+    const formattedLines = items.map((r) => {
+      const timeStr = r.created_at ? r.created_at.slice(0, 16).replace("T", " ") : "";
+      const sender = r.sender_display_name || "Ẩn danh";
+      const text = (r.text_redacted || "").trim();
+      return `[${timeStr}] ${sender}: ${text}`;
+    });
+
+    return {
+      messages: items,
+      text: formattedLines.join("\n"),
+      count: items.length,
+      nextCursor,
+      hasMore,
+    };
+  }
+
   /**
    * Ordered, cursor-based event feed for an authenticated Hermes platform
    * adapter. This intentionally returns only normalized/redacted fields; the

package/src/zalo_attachments.js

@@ -0,0 +1,90 @@
+/**
+ * Phân loại tệp đính kèm tin nhắn Zalo: ảnh, video, âm thanh, tài liệu.
+ *
+ * Khắc phục tình trạng tệp PDF/DOCX bị tải về như ảnh khiến model báo lỗi
+ * "không đọc được ảnh", và tự động chọn định dạng JPG thay vì JXL.
+ */
+
+const MIME_BY_EXT = {
+  ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".png": "image/png", ".gif": "image/gif",
+  ".webp": "image/webp", ".bmp": "image/bmp", ".heic": "image/heic", ".jxl": "image/jxl",
+  ".mp4": "video/mp4", ".mov": "video/quicktime", ".mkv": "video/x-matroska", ".webm": "video/webm",
+  ".mp3": "audio/mpeg", ".m4a": "audio/mp4", ".aac": "audio/aac", ".ogg": "audio/ogg", ".wav": "audio/wav",
+  ".pdf": "application/pdf",
+  ".doc": "application/msword",
+  ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  ".xls": "application/vnd.ms-excel",
+  ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  ".ppt": "application/vnd.ms-powerpoint",
+  ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  ".csv": "text/csv", ".txt": "text/plain", ".md": "text/markdown", ".json": "application/json",
+  ".zip": "application/zip", ".rar": "application/vnd.rar", ".7z": "application/x-7z-compressed",
+};
+
+function extensionOf(value) {
+  const clean = String(value ?? "").split(/[?#]/)[0];
+  const match = /\.([A-Za-z0-9]{1,5})$/.exec(clean);
+  return match ? `.${match[1].toLowerCase()}` : "";
+}
+
+/**
+ * Ưu tiên các định dạng ảnh phổ biến (JPG, PNG, WEBP), loại bỏ bản JXL
+ * nếu đã có bản định dạng đọc được khác trong cùng tin nhắn.
+ */
+export function preferReadableFormats(urls) {
+  const info = urls.map((url) => {
+    const m = /\/gr\/([a-z0-9]+)\/([^/]+)\//i.exec(String(url));
+    return { url, format: (m?.[1] || "").toLowerCase(), group: m?.[2] || "" };
+  });
+  const groupsWithReadable = new Set(
+    info.filter((x) => x.group && x.format && x.format !== "jxl").map((x) => x.group),
+  );
+  return info
+    .filter((x) => !(x.format === "jxl" && groupsWithReadable.has(x.group)))
+    .map((x) => x.url);
+}
+
+function kindOf(mime) {
+  if (mime.startsWith("image/")) return "image";
+  if (mime.startsWith("video/")) return "video";
+  if (mime.startsWith("audio/")) return "audio";
+  return "document";
+}
+
+export function isFileMessage(msgType) {
+  return /file/i.test(String(msgType ?? ""));
+}
+
+export function hasRealMedia(msgType) {
+  return !/(recommended|webchat|chat\.text|poll|ecard|undo|sticker|link)/i.test(String(msgType ?? ""));
+}
+
+export function guessAttachment(url, { name = "", msgType = "" } = {}) {
+  const ext = extensionOf(name) || extensionOf(url);
+  let mime = MIME_BY_EXT[ext] || "";
+  if (!mime) {
+    mime = isFileMessage(msgType) ? "application/octet-stream" : "image/jpeg";
+  }
+  return {
+    url: String(url),
+    name: String(name || "").trim() || (ext ? `file${ext}` : ""),
+    mime,
+    kind: kindOf(mime),
+  };
+}
+
+export function classifyAttachments(msg, urls = []) {
+  const content = msg?.data?.content ?? msg?.content;
+  const msgType = msg?.data?.msgType ?? msg?.msgType ?? "";
+  const title = content && typeof content === "object" ? String(content.title ?? "") : "";
+  const href = content && typeof content === "object" ? String(content.href ?? "") : "";
+
+  if (!hasRealMedia(msgType)) return [];
+  const safeUrls = preferReadableFormats(urls);
+
+  if (isFileMessage(msgType)) {
+    const fileUrl = safeUrls.includes(href) ? href : safeUrls[0];
+    return fileUrl ? [guessAttachment(fileUrl, { name: title, msgType })] : [];
+  }
+  return safeUrls.map((url) => guessAttachment(url, { name: url === href ? title : "", msgType }));
+}

package/src/zalo_mentions.js

@@ -0,0 +1,83 @@
+/**
+ * Đổi "@Tên hiển thị" trong tin bot gửi vào nhóm thành tag Zalo thật.
+ *
+ * Tên phải khớp một người trong danh bạ nhóm và không có dấu hiệu còn tiếp;
+ * hai người trùng tên thì để nguyên dạng chữ để tránh tag nhầm người.
+ */
+
+const NAME_CHAR = /[\p{L}\p{N}_]/u;
+const NAME_CONTINUES = /^ \p{Lu}/u;
+
+function normalize(text) {
+  return String(text || "").toLocaleLowerCase("vi");
+}
+
+/**
+ * @param {string} msg Chữ đã qua bộ dịch Markdown (vị trí tính trên chuỗi này).
+ * @param {{uid: string, name: string}[]} members
+ * @param {{selfUid?: string, continuesInNextChunk?: boolean}} options
+ * @returns {{pos: number, len: number, uid: string}[]}
+ */
+export function findMentions(msg, members, { selfUid = "", continuesInNextChunk = false } = {}) {
+  const text = String(msg ?? "");
+  if (!text.includes("@") || !Array.isArray(members) || !members.length) return [];
+
+  const uidsByName = new Map();
+  for (const member of members) {
+    const uid = String(member?.uid ?? member?.userId ?? member?.id ?? "");
+    const name = String(member?.name ?? member?.displayName ?? member?.dName ?? "").trim();
+    if (!uid || !name || uid === String(selfUid)) continue;
+    const key = normalize(name);
+    const entry = uidsByName.get(key) ?? { length: name.length, uids: new Set() };
+    entry.uids.add(uid);
+    uidsByName.set(key, entry);
+  }
+
+  // Khớp tên dài trước: "@Lương Hải Anh Cnt" không bị khớp nhầm thành "@Lương"
+  const names = [...uidsByName.entries()].sort((a, b) => b[1].length - a[1].length);
+
+  const mentions = [];
+  for (let at = text.indexOf("@"); at !== -1; at = text.indexOf("@", at + 1)) {
+    if (at > 0 && NAME_CHAR.test(text[at - 1])) continue; // a@b trong email
+    const match = names.find(([key, { length }]) => {
+      const after = text.slice(at + 1 + length);
+      return (
+        normalize(text.slice(at + 1, at + 1 + length)) === key &&
+        !NAME_CHAR.test(after[0] ?? "") &&
+        !NAME_CONTINUES.test(after) &&
+        !(continuesInNextChunk && after.trim() === "")
+      );
+    });
+    if (!match) continue;
+    const [, { length, uids }] = match;
+    if (uids.size !== 1) continue;
+    mentions.push({ pos: at, len: length + 1, uid: [...uids][0] });
+    at += length;
+  }
+  return mentions;
+}
+
+/**
+ * Danh bạ thành viên từng nhóm, cache tạm để tối ưu tốc độ gửi tin.
+ */
+export function createMemberDirectory({ fetchMembers, ttlMs = 10 * 60 * 1000, now = Date.now } = {}) {
+  const cache = new Map();
+  return {
+    async get(groupId) {
+      const key = String(groupId);
+      const hit = cache.get(key);
+      if (hit && now() - hit.at < ttlMs) return hit.members;
+      try {
+        const res = typeof fetchMembers === "function" ? await fetchMembers(key) : [];
+        const members = Array.isArray(res) ? res : Array.isArray(res?.members) ? res.members : [];
+        cache.set(key, { at: now(), members });
+        return members;
+      } catch (err) {
+        return hit?.members ?? [];
+      }
+    },
+    clear() {
+      cache.clear();
+    },
+  };
+}

package/src/zalo_runtime.js

@@ -5,6 +5,9 @@ import { EventEmitter } from "node:events";
 import { normalizeInboundMessage, utcNow } from "./schema.js";
 import { stageHermesMedia } from "./hermes_media.js";
 import { buildZaloStyledMessage, splitIntoSafeZaloChunks } from "./zalo_styler.js";
+import { findMentions } from "./zalo_mentions.js";
+import { enrichSticker, stickerRefOf } from "./zalo_stickers.js";
+import { classifyAttachments } from "./zalo_attachments.js";
 
 const PERSONAL_ACTIONS = new Set([
   "send_message", "send_sticker", "send_voice", "send_video", "forward_message", "typing",
@@ -12,7 +15,8 @@ const PERSONAL_ACTIONS = new Set([
   "create_note", "change_avatar", "block_member", "unblock_member", "review_pending",
   "group_link_enable", "group_link_disable", "send_card", "send_bank_card",
   "friend_accept", "friend_reject", "friend_request", "friend_request_undo", "friend_remove",
-  "user_block", "user_unblock"
+  "user_block", "user_unblock",
+  "join_group_link", "join_group_invite_box", "get_group_link_info", "get_sticker_detail", "search_stickers"
 ]);
 
 function required(value, name) {
@@ -475,6 +479,31 @@ export class AccountRuntime extends EventEmitter {
     return this.api.updateGroupSettings(settings, String(groupId));
   }
 
+  async joinGroupLink(link) {
+    if (!this.api?.joinGroupLink) throw new Error("not_connected");
+    return this.api.joinGroupLink(String(link));
+  }
+
+  async getGroupLinkInfo(link) {
+    if (!this.api?.getGroupLinkInfo) throw new Error("not_connected");
+    return this.api.getGroupLinkInfo({ link: String(link) });
+  }
+
+  async joinGroupInviteBox(groupId) {
+    if (!this.api?.joinGroupInviteBox) throw new Error("not_connected");
+    return this.api.joinGroupInviteBox(String(groupId));
+  }
+
+  async getStickerDetail(stickerId) {
+    if (!this.api?.getStickersDetail) throw new Error("not_connected");
+    return this.api.getStickersDetail(Number(stickerId));
+  }
+
+  async searchStickers(keyword) {
+    if (!this.api?.getStickers) throw new Error("not_connected");
+    return this.api.getStickers(String(keyword));
+  }
+
   async performPersonalAction(action, payload = {}) {
     const name = String(action || "").trim();
     if (!PERSONAL_ACTIONS.has(name)) throw new Error("unsupported_personal_action");
@@ -485,6 +514,16 @@ export class AccountRuntime extends EventEmitter {
       case "send_message": {
         if (typeof api.sendMessage !== "function") break;
         let textContent = String(payload.text || "");
+        if (textContent.includes("[[NEW_MESSAGE]]")) {
+          const parts = textContent.split(/\[\[NEW_MESSAGE\]\]/g).map((p) => p.trim()).filter(Boolean);
+          if (parts.length > 1) {
+            let lastRes = null;
+            for (const part of parts) {
+              lastRes = await this.performPersonalAction("send_message", { ...payload, text: part });
+            }
+            return lastRes;
+          }
+        }
         let styles = Array.isArray(payload.styles) ? payload.styles : undefined;
         if (!styles && (payload.styled || payload.parse_markdown || /[*_~#\[]/.test(textContent))) {
           const parsed = buildZaloStyledMessage(textContent);
@@ -494,7 +533,20 @@ export class AccountRuntime extends EventEmitter {
         const message = { msg: textContent.slice(0, 4000) };
         if (!message.msg && !payload.attachment_path) throw new Error("text_or_attachment_required");
         if (payload.quote) message.quote = payload.quote;
-        if (Array.isArray(payload.mentions)) message.mentions = payload.mentions.slice(0, 50);
+        if (Array.isArray(payload.mentions)) {
+          message.mentions = payload.mentions.slice(0, 50);
+        } else if (threadType(payload.thread_type) === 1 && textContent.includes("@") && typeof api.getGroupInfo === "function") {
+          try {
+            const groupInfo = await api.getGroupInfo(target());
+            const mems = groupInfo?.members || groupInfo?.memList || [];
+            if (Array.isArray(mems) && mems.length) {
+              const detected = findMentions(textContent, mems);
+              if (detected.length) message.mentions = detected;
+            }
+          } catch {
+            /* ignore mention fetch failure */
+          }
+        }
         if (payload.attachment_path) message.attachments = controlledAttachment(payload.attachment_path);
         if (styles) message.styles = styles;
         // Plaintext fallback: if Zalo rejects a styled message with a numeric error
@@ -576,6 +628,11 @@ export class AccountRuntime extends EventEmitter {
       case "friend_remove": if (typeof api.removeFriend === "function") return api.removeFriend(required(payload.user_id, "user_id")); break;
       case "user_block": if (typeof api.blockUser === "function") return api.blockUser(required(payload.user_id, "user_id")); break;
       case "user_unblock": if (typeof api.unblockUser === "function") return api.unblockUser(required(payload.user_id, "user_id")); break;
+      case "join_group_link": if (typeof api.joinGroupLink === "function") return api.joinGroupLink(required(payload.link, "link")); break;
+      case "join_group_invite_box": if (typeof api.joinGroupInviteBox === "function") return api.joinGroupInviteBox(required(payload.group_id, "group_id")); break;
+      case "get_group_link_info": if (typeof api.getGroupLinkInfo === "function") return api.getGroupLinkInfo({ link: required(payload.link, "link") }); break;
+      case "get_sticker_detail": if (typeof api.getStickersDetail === "function") return api.getStickersDetail(Number(required(payload.sticker_id, "sticker_id"))); break;
+      case "search_stickers": if (typeof api.getStickers === "function") return api.getStickers(required(payload.keyword, "keyword")); break;
       default: break;
     }
     throw new Error(`provider_action_unavailable:${name}`);

package/src/zalo_stickers.js

@@ -0,0 +1,101 @@
+/**
+ * Đọc và giải mã nhãn dán (sticker) của Zalo.
+ *
+ * Tin sticker Zalo tới dưới dạng `chat.sticker` với nội dung `{id, catId, type}`.
+ * Module này tra cứu chi tiết sticker (`getStickersDetail`) để lấy nhãn chữ và ảnh tĩnh PNG,
+ * giúp các tầng sau (lưu lịch sử, AI vision, tóm tắt) đọc được như tin bình thường.
+ */
+
+const LOOKUP_TIMEOUT_MS = 4000;
+const CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+const CACHE_LIMIT = 500;
+
+export function isStickerMessage(msgType) {
+  return /sticker/i.test(String(msgType ?? ""));
+}
+
+/** Lấy `{id, cateId, type}` của sticker trong một tin, hoặc null. */
+export function stickerRefOf(msg) {
+  const msgType = msg?.data?.msgType ?? msg?.msgType;
+  if (!isStickerMessage(msgType)) return null;
+  const content = msg?.data?.content ?? msg?.content;
+  if (!content || typeof content !== "object") return null;
+  const id = Number(content.id);
+  if (!Number.isFinite(id) || id <= 0) return null;
+  return {
+    id,
+    cateId: Number(content.catId ?? content.cateId) || 0,
+    type: Number(content.type) || 0,
+  };
+}
+
+// Zalo sticker text thường chứa mã nội bộ như [^10751.27703^], cần loại bỏ mã này
+const CODE_LABEL_RE = /^\[\^[\d.]+\^\]$/;
+
+export function stickerText(detail) {
+  const label = String(detail?.text ?? "").trim();
+  return label && !CODE_LABEL_RE.test(label) ? `[Nhãn dán: ${label}]` : "[Nhãn dán]";
+}
+
+export function stickerAttachment(detail) {
+  const url = String(detail?.stickerUrl ?? "").trim();
+  if (!url) return null;
+  return {
+    url,
+    name: `sticker-${detail?.id ?? ""}.png`.replace("-.png", ".png"),
+    mime: "image/png",
+    kind: "image",
+  };
+}
+
+export function createStickerDirectory({
+  fetchDetail,
+  ttlMs = CACHE_TTL_MS,
+  limit = CACHE_LIMIT,
+  timeoutMs = LOOKUP_TIMEOUT_MS,
+  now = Date.now,
+} = {}) {
+  const cache = new Map();
+  return {
+    async get(id) {
+      const key = String(id);
+      const hit = cache.get(key);
+      if (hit && now() - hit.at < ttlMs) return hit.detail;
+      let detail = null;
+      let timer = null;
+      try {
+        detail = await Promise.race([
+          Promise.resolve(typeof fetchDetail === "function" ? fetchDetail(Number(id)) : null),
+          new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error("sticker_lookup_timeout")), timeoutMs);
+          }),
+        ]);
+      } catch {
+        return hit?.detail ?? null;
+      } finally {
+        if (timer) clearTimeout(timer);
+      }
+      const first = Array.isArray(detail) ? detail[0] : detail;
+      if (!first || typeof first !== "object") return hit?.detail ?? null;
+      if (cache.size >= limit) cache.delete(cache.keys().next().value);
+      cache.set(key, { at: now(), detail: first });
+      return first;
+    },
+    clear() {
+      cache.clear();
+    },
+  };
+}
+
+export async function enrichSticker(msg, directory) {
+  const ref = stickerRefOf(msg);
+  if (!ref) return null;
+  const detail = directory ? await directory.get(ref.id) : null;
+  const info = {
+    id: ref.id,
+    text: stickerText(detail),
+    attachment: detail ? stickerAttachment(detail) : null,
+  };
+  if (msg?.data) msg.data.__sticker = info;
+  return info;
+}