abs-zalo-bot 0.7.0 → 0.7.1

package/hermes-plugin/zalo-style-guide.md

@@ -0,0 +1,65 @@
+# Hướng Dẫn Trình Bày & Phong Cách Tin Nhắn Zalo (Zalo Style Guide)
+> **Chuẩn hoá định dạng tin nhắn cho Zalo AI Agent (Amon, Lavie, Coach, Travel & Enterprise Bots).**  
+> Đúc kết từ thực chiến hàng trăm nghìn phiên chat, tối ưu trải nghiệm đọc trên màn hình điện thoại di động và tương thích tuyệt đối với giao thức Zalo API.
+
+---
+
+## 1. Nguyên Tắc Bố Cục & Đọc Nhanh (Mobile-First)
+
+Màn hình Zalo trên di động có chiều ngang hẹp. Mắt người đọc thường quét theo hình chữ F hoặc chữ E:
+* **In đậm nhãn mục:** Luôn in đậm đầu mục để mắt người lướt bắt điểm dừng ngay lập tức:
+  * `- Hiện tại:` / `- Thực trạng:`
+  * `- Phân tích:` / `- Nguyên nhân:`
+  * `- Đề xuất:` / `- Giải pháp:` / `- Bước tiếp theo:`
+* **In đậm từ khoá then chốt:** Những con số quan trọng, thời hạn, tên riêng, hành động chính cần in đậm:
+  * Ví dụ: *Chi phí dự tính **1.500.000đ**, hoàn thành trước **17h00 hôm nay**.*
+* **Khoảng thở giữa các ý:** Tách các đoạn tối đa 2–3 câu, để 1 dòng trống giữa các phần. Không viết khối văn bản đặc quánh (text-wall).
+
+---
+
+## 2. Thể Thức Phân Tầng Danh Sách (Chuẩn Văn Bản Hành Chính)
+
+Tránh lồng bullet 3–4 cấp làm vỡ khung hiển thị Zalo. Chỉ dùng tối đa 2 cấp:
+* **Cấp 1 (Mục chính):** Dùng gạch đầu dòng `- `
+* **Cấp 2 (Mục con chi tiết):** Dùng chấm tròn `• `
+
+**Ví dụ:**
+```markdown
+- Gói Đồng Hành Khởi Đầu:
+  • Thời hạn hỗ trợ: 3 tháng liên tục.
+  • Kênh trao đổi: Nhóm Zalo riêng biệt 24/7.
+- Gói Toàn Diện Doanh Nghiệp:
+  • Thiết lập toàn bộ AI Agent CSKH & Chốt đơn.
+  • Bàn giao mã nguồn và tài sản sở hữu 100%.
+```
+
+---
+
+## 3. Hệ Màu Nhận Diện Editorial Luxury Palette
+
+Hệ thống hỗ trợ cả 3 dạng thẻ màu: tiếng Anh, tiếng Việt có dấu và tiếng Việt không dấu:
+
+| Màu hiển thị | Thẻ hỗ trợ (Không phân biệt hoa/thường) | Mã màu Zalo | Ngữ nghĩa & Tình huống sử dụng |
+| :--- | :--- | :--- | :--- |
+| 🔴 **Đỏ Ruby** | `[RED]`, `[ĐỎ]`, `[do]` | `c_db342e` | Tiêu đề lớn, Băng rôn, Cảnh báo khẩn cấp, Điểm nghẽn rủi ro, Tổng kết quan trọng. |
+| 🟢 **Xanh Lá Ngọc** | `[GREEN]`, `[XANH]` | `c_15a85f` | Đề mục đánh số (1., 2.), Quy trình chuẩn, Tín hiệu tích cực, Checklist hoàn tất. |
+| 🟠 **Cam Hổ Phách** | `[ORANGE]`, `[CAM]` | `c_f27806` | Từ khóa hành động then chốt, Lưu ý thực thi, Cụm từ trong ngoặc kép `""`. |
+| 🟡 **Vàng Hoàng Kim** | `[YELLOW]`, `[VÀNG]`, `[vang]` | `c_f7b503` | Triết lý cốt lõi, Insight sâu sắc, Bài học xương máu, Giá trị nền tảng. |
+
+*Lưu ý:* Luôn đóng thẻ màu bằng `[/RED]`, `[/ĐỎ]`, `[/do]`, v.v.
+
+---
+
+## 4. Những Điều CẤM & Tránh Khi Viết Cho Zalo
+
+1. **TUYỆT ĐỐI KHÔNG DÙNG `---` (Đường kẻ ngang Markdown):**
+   * Trên ứng dụng Zalo di động, thẻ `---` không hiển thị thành đường kẻ mỏng mà biến thành khoảng trống kép rất thô, làm loãng nội dung.
+   * *Giải pháp:* Chỉ cần cách 1 dòng trống đơn thuần là đủ trang nhã. Engine `abs-zalo-bot` đã được tích hợp bộ lọc tự động triệt tiêu `---` thành khoảng trắng sạch.
+2. **Không lạm dụng thẻ màu trên toàn bộ đoạn văn:**
+   * Chỉ bọc màu cho từ ngữ đắt giá (1–5 từ). Bọc nguyên một câu dài bằng màu đỏ hoặc vàng sẽ gây chói mắt và làm mất tính sang trọng.
+3. **Không lo vượt trần Style JSON (Đã có `capStyles` tự động):**
+   * Zalo Web API có giới hạn ngầm mảng style không được vượt quá ~256 bytes JSON.
+   * Engine tự động bảo vệ: Nếu bài viết quá nhiều style, thuật toán sẽ tự động gọt bớt các style phụ (gạch chân, in nghiêng) và bảo tồn 100% Tiêu đề và Thẻ màu. Không bao giờ xảy ra lỗi drop tin ngầm.
+4. **Kỷ luật Sticker & Voice:**
+   * Trong các nhóm thảo luận công việc, quản trị, hoặc hỗ trợ kỹ thuật: Tuyệt đối không tự ý gửi sticker hoạt hình làm phiền người dùng.
+   * Tin nhắn thoại (Voice): Chỉ gửi khi người dùng yêu cầu nghe giọng nói.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "abs-zalo-bot",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "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/zalo_runtime.js

@@ -43,6 +43,9 @@ function controlledAttachment(filePath) {
 }
 
 export class AccountRuntime extends EventEmitter {
+  // Auto-restart constants (exponential back-off, same as 2anh-zalo-bot v1.1.1)
+  static RESTART_DELAYS_MS = [5_000, 15_000, 30_000, 60_000, 120_000, 300_000];
+
   constructor({ accountId, store, policy, onEvent, clientFactory = null }) {
     super();
     this.accountId = String(accountId);
@@ -55,6 +58,9 @@ export class AccountRuntime extends EventEmitter {
     this.loginPromise = null;
     this.lastMessageAt = null;
     this.listenerWired = false;
+    this._listenerStopped = false;
+    this._restartAttempt = 0;
+    this._restartTimer = null;
   }
 
   status() {
@@ -248,7 +254,44 @@ export class AccountRuntime extends EventEmitter {
         /* ignore closed store */
       }
     });
-    this.api.listener.start({ retryOnClose: true });
+    // "closed" = zca-js hit retry limit and gave up entirely. Bot is still "connected"
+    // but deaf. Schedule a listener restart with exponential back-off so the process
+    // self-heals without operator intervention (mirrors 2anh-zalo-bot v1.1.1 fix).
+    this.api.listener.on("closed", (code, reason) => {
+      try {
+        this.store.setHealth(
+          `listener_closed_${this.accountId}`,
+          `code=${code} reason=${String(reason || "").slice(0, 100)} at=${utcNow()}`,
+        );
+        this.emit("listener_down", { reason: `closed:${code}`, at: utcNow() });
+      } catch { /* ignore */ }
+      if (!this._listenerStopped) this.#scheduleListenerRestart();
+    });
+    this.#startListener();
+  }
+
+  #scheduleListenerRestart() {
+    if (this._listenerStopped || this._restartTimer) return;
+    const delays = AccountRuntime.RESTART_DELAYS_MS;
+    const delay = delays[Math.min(this._restartAttempt, delays.length - 1)];
+    this._restartAttempt += 1;
+    console.warn(
+      `[zalo_runtime] 🔁 Listener đóng hoàn toàn — thử mở lại sau ${Math.round(delay / 1000)}s (lần ${this._restartAttempt})`,
+    );
+    this._restartTimer = setTimeout(() => {
+      this._restartTimer = null;
+      this.#startListener();
+    }, delay);
+  }
+
+  #startListener() {
+    if (this._listenerStopped || !this.api?.listener) return;
+    try {
+      this.api.listener.start({ retryOnClose: true });
+    } catch (err) {
+      console.error("[zalo_runtime] không start được listener:", err?.message || err);
+      this.#scheduleListenerRestart();
+    }
   }
 
   async sendText(targetId, text, threadType = 1) {
@@ -335,6 +378,29 @@ export class AccountRuntime extends EventEmitter {
     return this.api.getGroupInfo(String(groupId));
   }
 
+  // getGroupMembersInfo requires a list of member UIDs, NOT a group ID.
+  // Call getGroupInfo first to obtain the member list, then pass member UIDs here.
+  // (mirrors 2anh-zalo-bot v1.2.0 group_members fix)
+  async getGroupMembers(groupId, { limit = 50 } = {}) {
+    if (!this.api?.getGroupInfo || !this.api?.getGroupMembersInfo) throw new Error("not_connected");
+    const info = await this.api.getGroupInfo(String(groupId));
+    const gid = String(groupId);
+    const memberIds = (info?.gridInfoMap?.[gid]?.memVerList || [])
+      .map((entry) => String(entry).replace(/_\d+$/, ""))
+      .filter(Boolean);
+    const lookup = memberIds.slice(0, Math.min(limit, 100));
+    const profiles = lookup.length
+      ? ((await this.api.getGroupMembersInfo(lookup))?.profiles || {})
+      : {};
+    return {
+      total: memberIds.length,
+      members: lookup.map((id) => ({
+        id,
+        displayName: profiles[id]?.displayName || profiles[id]?.zaloName || "",
+      })),
+    };
+  }
+
   async getUserInfo(userId) {
     if (!this.api?.getUserInfo) throw new Error("not_connected");
     return this.api.getUserInfo(String(userId));
@@ -431,7 +497,20 @@ export class AccountRuntime extends EventEmitter {
         if (Array.isArray(payload.mentions)) message.mentions = payload.mentions.slice(0, 50);
         if (payload.attachment_path) message.attachments = controlledAttachment(payload.attachment_path);
         if (styles) message.styles = styles;
-        return api.sendMessage(message, target(), threadType(payload.thread_type));
+        // Plaintext fallback: if Zalo rejects a styled message with a numeric error
+        // code (server-side rejection), retry as plain text to avoid silently losing
+        // the message. Network errors (no code) are NOT retried to avoid duplicates.
+        // (mirrors 2anh-zalo-bot v1.1.1 hermes-bridge.js fix)
+        try {
+          return await api.sendMessage(message, target(), threadType(payload.thread_type));
+        } catch (err) {
+          if (!message.styles || !/^-?\d+$/.test(String(err?.code ?? ""))) throw err;
+          console.warn(
+            `[zalo_runtime] Zalo từ chối tin có style (mã ${err.code}) — gửi lại dạng chữ thường`,
+          );
+          const { styles: _dropped, ...plain } = message;
+          return api.sendMessage(plain, target(), threadType(payload.thread_type));
+        }
       }
       case "send_sticker":
         if (typeof api.sendSticker !== "function") break;
@@ -503,6 +582,9 @@ export class AccountRuntime extends EventEmitter {
   }
 
   async pause() {
+    this._listenerStopped = true;
+    clearTimeout(this._restartTimer);
+    this._restartTimer = null;
     try {
       this.api?.listener?.stop?.();
     } catch {

package/src/zalo_styler.js

@@ -20,6 +20,20 @@ export const ZALO_STYLES = {
 
 export const MAX_ZALO_STYLE_JSON_LENGTH = 250;
 export const MAX_ZALO_UTF16_LENGTH = 2800;
+export const MAX_ZALO_PAYLOAD_BYTES = 3000;
+
+/**
+ * Measure payload volume in UTF-8 bytes (text + style JSON length).
+ * Zalo web servers reject messages where text bytes + style JSON length >= 3,448 bytes.
+ * Keeping under 3,000 bytes ensures 100% safe delivery for Vietnamese text & emoji.
+ */
+export function measurePayloadBytes(msg, styles) {
+  const text = typeof msg === "string" ? msg : String(msg?.msg || msg?.text || "");
+  const textBytes = Buffer.byteLength(text, "utf8");
+  const styleList = styles || msg?.styles;
+  const styleBytes = Array.isArray(styleList) && styleList.length > 0 ? JSON.stringify(styleList).length : 0;
+  return textBytes + styleBytes;
+}
 
 /**
  * Measure string length in UTF-16 code units (Zalo's internal character counter).
@@ -159,6 +173,11 @@ export function parseMarkdownStyles(input) {
 
   for (let line of lines) {
     let hType = 0;
+    // Strip markdown horizontal rules (---, ***, ___) to avoid ugly wide gap in Zalo mobile
+    if (/^\s*[-*_]{3,}\s*$/.test(line)) {
+      line = "";
+    }
+
     if (line.startsWith("# ")) {
       hType = 1;
       line = line.slice(2);
@@ -225,11 +244,11 @@ export function parseMarkdownStyles(input) {
     }
   }
 
-  // 2. Color tags (Vietnamese and English)
-  replaceTag(/\[(?:RED|ĐỎ)\]([\s\S]*?)\[\/(?:RED|ĐỎ)\]/i, [ZALO_STYLES.Bold, ZALO_STYLES.RubyRed]);
+  // 2. Color tags (Vietnamese and English, accented & unaccented)
+  replaceTag(/\[(?:RED|ĐỎ|DO)\]([\s\S]*?)\[\/(?:RED|ĐỎ|DO)\]/i, [ZALO_STYLES.Bold, ZALO_STYLES.RubyRed]);
   replaceTag(/\[(?:GREEN|XANH)\]([\s\S]*?)\[\/(?:GREEN|XANH)\]/i, [ZALO_STYLES.Bold, ZALO_STYLES.EmeraldGreen]);
   replaceTag(/\[(?:ORANGE|CAM)\]([\s\S]*?)\[\/(?:ORANGE|CAM)\]/i, [ZALO_STYLES.Bold, ZALO_STYLES.AmberOrange]);
-  replaceTag(/\[(?:YELLOW|VÀNG)\]([\s\S]*?)\[\/(?:YELLOW|VÀNG)\]/i, [ZALO_STYLES.Bold, ZALO_STYLES.RoyalGold]);
+  replaceTag(/\[(?:YELLOW|VÀNG|VANG)\]([\s\S]*?)\[\/(?:YELLOW|VÀNG|VANG)\]/i, [ZALO_STYLES.Bold, ZALO_STYLES.RoyalGold]);
 
   // 3. Inline markdown tags
   replaceTag(/\*\*([\s\S]*?)\*\*/g, [ZALO_STYLES.Bold]);