abs-zalo-bot 0.6.0 → 0.7.1

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/abs-zalo-bot.svg?color=blue)](https://www.npmjs.com/package/abs-zalo-bot)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
-[![Automated Tests](https://img.shields.io/badge/Tests-77%2F77%20Passing-brightgreen.svg)](test/)
+[![Automated Tests](https://img.shields.io/badge/Tests-85%2F85%20Passing-brightgreen.svg)](test/)
 [![AI Agent Ready](https://img.shields.io/badge/AI%20Agent-Hermes%20%7C%20Claude%20Code%20%7C%20Codex-purple.svg)](mcp/)
 [![Model Context Protocol](https://img.shields.io/badge/MCP-Standard%20v1.3.0-blueviolet.svg)](mcp/)
 
@@ -46,7 +46,17 @@ Attach `npx abs-zalo-bot` or `node mcp/server.js` to your Agent configuration:
 | | `abs_zalo_list_groups` | List allowlisted source & destination groups |
 | | `abs_zalo_recent_messages` | Read captured message streams with full metadata |
 | | `abs_zalo_corpus_summary` | Get aggregated inventory of users, groups, and logs |
-| **Group Administration** | `abs_zalo_kick_member` | Remove a member from a group (Admin/Owner required) |
+| **Group Administration** | `abs_zalo_rename_group` | Rename group name (Admin/Leader required) |
+| | `abs_zalo_change_group_avatar` | Change group avatar image from URL or file |
+| | `abs_zalo_create_group_note` | Create and pin announcement/note at the top |
+| | `abs_zalo_get_pending_members` | List members waiting for approval to join |
+| | `abs_zalo_review_pending_member` | Approve or reject pending member requests |
+| | `abs_zalo_block_group_member` | Block a member permanently from the group |
+| | `abs_zalo_unblock_group_member` | Unblock a previously blocked member |
+| | `abs_zalo_get_group_link` | Get public group invite link (URL) |
+| | `abs_zalo_set_group_link` | Enable or disable public group join link |
+| | `abs_zalo_update_group_settings` | Configure group permissions (lock chat, pin, etc.) |
+| | `abs_zalo_kick_member` | Remove a member from a group (Admin/Owner required) |
 | | `abs_zalo_transfer_owner` | Transfer group ownership (Owner required) |
 | | `abs_zalo_add_deputy` | Promote a member to Group Deputy / Admin |
 | | `abs_zalo_remove_deputy` | Demote a Group Deputy back to regular member |
@@ -152,7 +162,7 @@ Start MCP with `ABS_ZALO_TOOL_PACK=reader` (default). Move deliberately to `oper
 
 Set `HERMES_ZALO_MEDIA_INGEST=true` only on the private bridge host to stage inbound Zalo attachments for an authenticated Hermes platform plugin. The bridge returns opaque attachment references and serves the staged local file through its authenticated `/v1/hermes/media/:eventId/:attachmentId` endpoint; it never passes provider CDN URLs or Zalo session data to Hermes. Images, documents, audio/voice and video are bounded to 25 MB for images/files and 100 MB for audio/video.
 
-### Hermes Zalo Gateway (0.5)
+### Hermes Zalo Gateway (0.5+)
 
 `hermes-plugin/platforms/zalo` is an installable Hermes gateway adapter. It polls the authenticated local bridge and converts only normalized, approved Zalo events into Hermes `MessageEvent`s; it never handles QR, cookies, sessions or arbitrary `zca-js` calls.
 
@@ -162,6 +172,73 @@ For profile-aware quality, select `gateway_skill = "your-owner-authored-hermes-s
 
 ---
 
+## 🎨 Zalo Rich Text & Auto Styling Engine (Built-in)
+
+`abs-zalo-bot` automatically compiles Markdown syntax and brand color tags into native Zalo TextStyle formatting:
+
+- `# Heading 1`: Large Header (`f_18`) + Bold (`b`) + Ruby Red (`c_db342e`).
+- `## Heading 2`: Header Bold (`b`) + Emerald Green (`c_15a85f`).
+- `### Heading 3`: Header Bold (`b`) + Amber Orange (`c_f27806`).
+- `**bold**`: Zalo Bold (`b`).
+- `*italic*`: Zalo Italic (`i`).
+- `__underline__`: Zalo Underline (`u`).
+- `~~strikethrough~~`: Zalo StrikeThrough (`s`).
+- Color tags: `[RED]...[/RED]` (Ruby Red), `[GREEN]...[/GREEN]` (Emerald Green), `[ORANGE]...[/ORANGE]` (Amber Orange), `[YELLOW]...[/YELLOW]` (Royal Gold) — supports Vietnamese equivalents `[ĐỎ]`, `[XANH]`, `[CAM]`, `[VÀNG]`.
+- **Safe Bubble Chunker (`splitIntoSafeZaloChunks`)**: Automatically breaks long outputs into sequential bubbles <= 650 chars, permanently eliminating Zalo API Error 118 ("Content too long").
+
+---
+
+## 🧠 Hermes Agent Starter Kit (`hermes-plugin/starter-kit/`)
+
+Ready-to-use "Digital Brain" template for Hermes Agent:
+
+1. **`SOUL.md`**: Conversational, warm, Vietnamese executive assistant voice (zero corporate slop, short mobile-optimized sentences, authentic tone).
+2. **`AGENT.md`**: Deterministic AI architecture, safety rules, fail-closed boundaries, mention-only in groups.
+3. **`skills/zalo-customer-care`**: 1-on-1 customer service, empathetic problem diagnosis, and natural lead qualification.
+4. **`skills/zalo-community-admin`**: 24/7 group moderation (new member welcome, FAQ answering, rule pinning, spam defense).
+
+To enable, run 1 command:
+```bash
+cp -R hermes-plugin/starter-kit/skills/* ~/.hermes/skills/
+cat hermes-plugin/starter-kit/SOUL.md >> ~/.hermes/SOUL.md
+```
+
+---
+
+## 🔄 Seamless Zero-Downtime Upgrade (For Existing Users)
+
+If you already installed `abs-zalo-bot` (v0.4.0 or v0.5.0), upgrading to **v0.6.0** takes 5 seconds with **ZERO data loss and NO QR re-scan**:
+
+- **If installed via NPM:**
+  ```bash
+  npm install -g abs-zalo-bot@latest
+  ```
+- **If cloned via Git:**
+  ```bash
+  git pull origin main
+  npm install
+  ```
+- **If running via Docker:**
+  ```bash
+  docker compose pull && docker compose up -d
+  ```
+
+> *Your active login sessions (`data/sessions/`), databases (`data/bridge.sqlite3`), and `.env` settings are 100% preserved. The bot seamlessly reconnects without requesting a new QR scan.*
+
+---
+
+## ⭐ Support & Community Nudge
+
+If ABS Zalo Bot helps your operations or business, please consider starring the repository:
+
+```bash
+# Star via GitHub CLI
+gh repo star teddiesloco/abs-zalo-bot
+```
+Or click Star directly at: **[https://github.com/teddiesloco/abs-zalo-bot](https://github.com/teddiesloco/abs-zalo-bot)** ⭐
+
+---
+
 ## 🔒 Security & Policy Boundaries
 
 - **Side-effect control**: Every outbound message and administrative action is audited through `PolicyGuard`.

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/mcp/server.js

@@ -12,6 +12,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
+import crypto from "node:crypto";
 import {
   capabilityPackSummary,
   canUseToolPack,
@@ -19,6 +20,47 @@ import {
   requiredToolPackForBridgeRequest,
 } from "../src/mcp_capabilities.js";
 
+const PENDING_CONFIRMATION_TTL_MS = 5 * 60 * 1000; // 5 minutes
+const pendingConfirmations = new Map(); // code -> { action, targetKey, expiresAt }
+
+function cleanupExpiredConfirmations() {
+  const now = Date.now();
+  for (const [code, entry] of pendingConfirmations.entries()) {
+    if (now > entry.expiresAt) {
+      pendingConfirmations.delete(code);
+    }
+  }
+}
+
+function requestConfirmation(action, targetKey) {
+  cleanupExpiredConfirmations();
+  const code = crypto.randomBytes(3).toString("hex").toUpperCase();
+  pendingConfirmations.set(code, {
+    action,
+    targetKey,
+    expiresAt: Date.now() + PENDING_CONFIRMATION_TTL_MS,
+  });
+  return {
+    status: "confirmation_required",
+    requires_confirmation: true,
+    action,
+    confirmation_code: code,
+    expires_in_seconds: 300,
+    warning: `⚠️ HÀNH ĐỘNG NHẠY CẢM: Thao tác này có tính phá hủy/ảnh hưởng lớn. Để thực thi, vui lòng gọi lại công cụ kèm tham số confirmation_code="${code}" trong vòng 5 phút (hoặc yêu cầu xác nhận trong chat).`,
+  };
+}
+
+function verifyConfirmation(code, action, targetKey) {
+  cleanupExpiredConfirmations();
+  if (!code || typeof code !== "string") return false;
+  const key = code.trim().toUpperCase();
+  const entry = pendingConfirmations.get(key);
+  if (!entry) return false;
+  if (entry.action !== action || entry.targetKey !== targetKey) return false;
+  pendingConfirmations.delete(key);
+  return true;
+}
+
 const BRIDGE_URL = (process.env.ZALO_BRIDGE_URL || "http://127.0.0.1:3871").replace(/\/$/, "");
 const TOKEN = process.env.DASHBOARD_TOKEN || process.env.ZALO_BRIDGE_TOKEN || "";
 const TOOL_PACK = normalizeToolPack(process.env.ABS_ZALO_TOOL_PACK || "reader");
@@ -270,13 +312,18 @@ server.tool(
 
 server.tool(
   "abs_zalo_kick_member",
-  "Remove a user/member from a group (Requires Group Admin or Owner rights).",
+  "Remove a user/member from a group (Requires Group Admin or Owner rights). Note: Destructive action requires 2-step confirmation.",
   {
     group_id: z.string().describe("Target Zalo group id"),
     user_id: z.string().describe("User ID to kick from group"),
     account_id: z.string().optional(),
+    confirmation_code: z.string().optional().describe("6-char OTP confirmation code. Call without code first to generate OTP."),
   },
-  async ({ group_id, user_id, account_id }) => {
+  async ({ group_id, user_id, account_id, confirmation_code }) => {
+    const targetKey = `${group_id}:${user_id}`;
+    if (!verifyConfirmation(confirmation_code, "kick_member", targetKey)) {
+      return ok(requestConfirmation("kick_member", targetKey));
+    }
     try {
       const data = await bridge(`/api/groups/${encodeURIComponent(group_id)}/kick`, {
         method: "POST",
@@ -291,13 +338,18 @@ server.tool(
 
 server.tool(
   "abs_zalo_transfer_owner",
-  "Transfer group ownership to another member (Requires Group Owner rights).",
+  "Transfer group ownership to another member (Requires Group Owner rights). Note: Destructive action requires 2-step confirmation.",
   {
     group_id: z.string().describe("Target Zalo group id"),
     new_owner_id: z.string().describe("User ID of the new group owner"),
     account_id: z.string().optional(),
+    confirmation_code: z.string().optional().describe("6-char OTP confirmation code. Call without code first to generate OTP."),
   },
-  async ({ group_id, new_owner_id, account_id }) => {
+  async ({ group_id, new_owner_id, account_id, confirmation_code }) => {
+    const targetKey = `${group_id}:${new_owner_id}`;
+    if (!verifyConfirmation(confirmation_code, "transfer_owner", targetKey)) {
+      return ok(requestConfirmation("transfer_owner", targetKey));
+    }
     try {
       const data = await bridge(`/api/groups/${encodeURIComponent(group_id)}/transfer-owner`, {
         method: "POST",
@@ -454,14 +506,19 @@ server.tool(
 
 server.tool(
   "abs_zalo_undo_message",
-  "Undo / recall a sent message on Zalo.",
+  "Undo / recall a sent message on Zalo. Note: Irreversible action requires 2-step confirmation.",
   {
     dest: z.string().describe("Destination / message context"),
     thread_id: z.string().describe("Thread / group ID"),
     thread_type: z.number().optional().default(1).describe("1 for group, 0 for direct"),
     account_id: z.string().optional(),
+    confirmation_code: z.string().optional().describe("6-char OTP confirmation code. Call without code first to generate OTP."),
   },
-  async ({ dest, thread_id, thread_type = 1, account_id }) => {
+  async ({ dest, thread_id, thread_type = 1, account_id, confirmation_code }) => {
+    const targetKey = `${thread_id}:${dest}`;
+    if (!verifyConfirmation(confirmation_code, "undo_message", targetKey)) {
+      return ok(requestConfirmation("undo_message", targetKey));
+    }
     try {
       const data = await bridge("/api/messages/undo", {
         method: "POST",
@@ -671,13 +728,18 @@ server.tool(
 
 server.tool(
   "abs_zalo_block_group_member",
-  "Block a member permanently from joining or chatting in the group.",
+  "Block a member permanently from joining or chatting in the group. Note: Destructive action requires 2-step confirmation.",
   {
     group_id: z.string().describe("Zalo group ID"),
     member_id: z.string().describe("Zalo user ID to block"),
     account_id: z.string().optional(),
+    confirmation_code: z.string().optional().describe("6-char OTP confirmation code. Call without code first to generate OTP."),
   },
-  async ({ group_id, member_id, account_id }) => {
+  async ({ group_id, member_id, account_id, confirmation_code }) => {
+    const targetKey = `${group_id}:${member_id}`;
+    if (!verifyConfirmation(confirmation_code, "block_group_member", targetKey)) {
+      return ok(requestConfirmation("block_group_member", targetKey));
+    }
     try {
       const data = await bridge(`/api/groups/${encodeURIComponent(group_id)}/blocked/add`, {
         method: "POST",

package/package.json

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

@@ -64,7 +64,10 @@ export async function stageHermesMedia(event, { dataDir, fetchImpl = globalThis.
       const declared = Number(response.headers.get("content-length") || 0);
       if (declared > limit) throw new Error("attachment_too_large");
       const id = crypto.createHash("sha256").update(`${event.event_id}|${candidate.url}`).digest("hex").slice(0, 24);
-      const relative = path.join("media", event.event_id, `${id}-${safeName(candidate.name, "attachment")}`);
+      const ext = path.extname(candidate.name) || (candidate.kind === "image" ? ".jpg" : candidate.kind === "audio" ? ".m4a" : candidate.kind === "video" ? ".mp4" : "");
+      const baseCandidateName = safeName(candidate.name, "attachment");
+      const candidateNameWithExt = ext && !baseCandidateName.toLowerCase().endsWith(ext) ? `${baseCandidateName}${ext}` : baseCandidateName;
+      const relative = path.join("media", event.event_id, `${id}-${candidateNameWithExt}`);
       const full = path.resolve(dataDir, relative);
       if (!full.startsWith(`${path.resolve(dataDir, "media")}${path.sep}`)) throw new Error("attachment_path_invalid");
       fs.mkdirSync(path.dirname(full), { recursive: true, mode: 0o700 });
@@ -84,7 +87,7 @@ export async function stageHermesMedia(event, { dataDir, fetchImpl = globalThis.
         });
       }
       if (!bytes) throw new Error("attachment_empty");
-      refs.push({ id, path: relative, name: safeName(candidate.name, "attachment"), kind: candidate.kind, mime: response.headers.get("content-type")?.split(";")[0] || extensionMime(candidate.name, candidate.kind), size: bytes });
+      refs.push({ id, path: relative, name: candidateNameWithExt, kind: candidate.kind, mime: response.headers.get("content-type")?.split(";")[0] || extensionMime(candidateNameWithExt, candidate.kind), size: bytes });
     } catch (err) {
       refs.push({ id: crypto.randomUUID(), name: safeName(candidate.name, "attachment"), kind: candidate.kind || "file", status: "unavailable", error: String(err?.message || err).slice(0, 80) });
     }

package/src/rate_limiter.js

@@ -0,0 +1,139 @@
+/**
+ * ABS Zalo Token Bucket Rate Limiter
+ *
+ * Smooths outbound messages using a token bucket algorithm to prevent
+ * triggering Zalo anti-spam / checkpoint mechanisms while keeping real-time
+ * conversational responses instantaneous (zero delay for the first burst).
+ */
+
+export class RateLimitedError extends Error {
+  constructor(waitMs) {
+    super(
+      `Đang bị giãn nhịp chống spam Zalo, cần chờ ~${Math.ceil(waitMs / 1000)}s. ` +
+        `Vui lòng gửi ít tin hơn hoặc thử lại sau.`
+    );
+    this.name = "RateLimitedError";
+    this.waitMs = waitMs;
+  }
+}
+
+export class RateLimiter {
+  #tokens;
+  #capacity;
+  #refillMs;
+  #maxWaitMs;
+  #last;
+  #hi = [];
+  #lo = [];
+  #timer = null;
+
+  /**
+   * @param {object} opts
+   * @param {number} opts.capacity  Burst capacity (default 5: burst of 5 messages with 0 delay).
+   * @param {number} opts.refillMs  Token regeneration time (default 3000ms = sustainable 20 msg/min).
+   * @param {number} opts.maxWaitMs Max wait before rejecting with RateLimitedError (default 20000ms).
+   */
+  constructor({ capacity = 5, refillMs = 3000, maxWaitMs = 20000 } = {}) {
+    this.#capacity = Math.max(1, capacity);
+    this.#refillMs = Math.max(1, refillMs);
+    this.#maxWaitMs = Math.max(0, maxWaitMs);
+    this.#tokens = this.#capacity;
+    this.#last = Date.now();
+  }
+
+  get queued() {
+    return this.#hi.length + this.#lo.length;
+  }
+
+  get available() {
+    this.#refill();
+    return Math.floor(this.#tokens);
+  }
+
+  #refill() {
+    const now = Date.now();
+    const gained = (now - this.#last) / this.#refillMs;
+    if (gained <= 0) return;
+    this.#tokens = Math.min(this.#capacity, this.#tokens + gained);
+    this.#last = now;
+  }
+
+  /**
+   * Acquire a rate limit slot.
+   *
+   * @param {'high'|'normal'} priority 'high' for immediate conversational replies, 'normal' for bulk/sync.
+   * @returns {Promise<void>} Resolves when granted permission to send.
+   * @throws {RateLimitedError} When queue wait time exceeds maxWaitMs.
+   */
+  acquire(priority = "normal") {
+    this.#refill();
+
+    // Fast path: tokens available and no existing queue -> immediate dispatch (0 latency)
+    if (this.queued === 0 && this.#tokens >= 1) {
+      this.#tokens -= 1;
+      return Promise.resolve();
+    }
+
+    const ahead = priority === "high" ? this.#hi.length : this.queued;
+    const waitMs = Math.max(0, Math.ceil((ahead + 1 - this.#tokens) * this.#refillMs));
+    if (waitMs > this.#maxWaitMs) {
+      return Promise.reject(new RateLimitedError(waitMs));
+    }
+
+    return new Promise((resolve) => {
+      (priority === "high" ? this.#hi : this.#lo).push(resolve);
+      this.#schedule();
+    });
+  }
+
+  #schedule() {
+    if (this.#timer) return;
+    const tick = () => {
+      this.#timer = null;
+      this.#refill();
+      while (this.#tokens >= 1 && this.queued > 0) {
+        const next = this.#hi.shift() ?? this.#lo.shift();
+        this.#tokens -= 1;
+        next();
+      }
+      if (this.queued > 0) {
+        const need = Math.ceil((1 - this.#tokens) * this.#refillMs);
+        this.#timer = setTimeout(tick, Math.max(25, need));
+      }
+    };
+    this.#timer = setTimeout(tick, 25);
+  }
+
+  /** Stop active timers to permit clean process termination. */
+  stop() {
+    if (this.#timer) {
+      clearTimeout(this.#timer);
+      this.#timer = null;
+    }
+    while (this.#hi.length > 0) {
+      const resolve = this.#hi.shift();
+      resolve();
+    }
+    while (this.#lo.length > 0) {
+      const resolve = this.#lo.shift();
+      resolve();
+    }
+  }
+}
+
+/** Methods subject to rate throttling */
+export const THROTTLED_METHODS = new Set([
+  "sendMessage",
+  "sendVoice",
+  "sendVideo",
+  "sendSticker",
+  "sendLink",
+  "sendCard",
+  "uploadAttachment",
+  "forwardMessage",
+  "createPoll",
+  "createNote",
+  "createReminder",
+  "addUserToGroup",
+  "inviteUserToGroups",
+]);

package/src/server.js

@@ -883,7 +883,8 @@ export function createApp({
       if (!dest || !thread_id) return res.status(400).json({ ok: false, error: "dest_and_thread_id_required" });
       const runtime = hub.getRuntime(accountId);
       if (!runtime.api) return res.status(400).json({ ok: false, error: "not_connected" });
-      const result = await runtime.undoMessage(dest, thread_id, thread_type || 1);
+      const resolvedType = thread_type !== undefined ? Number(thread_type) : 0;
+      const result = await runtime.undoMessage(dest, thread_id, resolvedType);
       res.json({ ok: true, result });
     } catch (err) {
       res.status(500).json({ ok: false, error: String(err?.message || err) });

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) {
@@ -325,7 +368,7 @@ export class AccountRuntime extends EventEmitter {
     return this.api.addReaction(icon, dest);
   }
 
-  async undoMessage(dest, threadId, threadType = 1) {
+  async undoMessage(dest, threadId, threadType = 0) {
     if (!this.api?.undo) throw new Error("not_connected");
     return this.api.undo(dest, String(threadId), threadType);
   }
@@ -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

@@ -18,6 +18,84 @@ export const ZALO_STYLES = {
   Indent: "ind_$",
 };
 
+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).
+ */
+export function measureUtf16Length(str) {
+  return typeof str === "string" ? str.length : 0;
+}
+
+/**
+ * Score style priority so essential formatting (Headings, Colors) survives JSON budget cuts.
+ */
+function getStylePriority(st) {
+  switch (st) {
+    case ZALO_STYLES.HeaderLarge:
+    case ZALO_STYLES.HeaderSmall:
+      return 100;
+    case ZALO_STYLES.RubyRed:
+    case ZALO_STYLES.EmeraldGreen:
+    case ZALO_STYLES.AmberOrange:
+    case ZALO_STYLES.RoyalGold:
+      return 80;
+    case ZALO_STYLES.Bold:
+      return 60;
+    case ZALO_STYLES.Underline:
+    case ZALO_STYLES.StrikeThrough:
+      return 40;
+    case ZALO_STYLES.Italic:
+      return 20;
+    default:
+      return 10;
+  }
+}
+
+/**
+ * Cap Zalo styles to prevent exceeding Zalo's JSON style payload ceiling (~256 bytes).
+ * When over budget, lower-priority styles (italic, bold) are pruned first
+ * while preserving high-priority headings and colors.
+ */
+export function capStyles(styles, maxJsonLength = MAX_ZALO_STYLE_JSON_LENGTH) {
+  if (!Array.isArray(styles) || styles.length === 0) return [];
+  if (JSON.stringify(styles).length <= maxJsonLength) return styles;
+
+  // Clone and annotate with original index and priority
+  const items = styles.map((s, idx) => ({
+    style: s,
+    priority: getStylePriority(s.st),
+    idx,
+  }));
+
+  // Sort ascending by priority so lowest priority items are removed first
+  items.sort((a, b) => a.priority - b.priority);
+
+  const retained = new Set(styles);
+  while (items.length > 0 && JSON.stringify(Array.from(retained)).length > maxJsonLength) {
+    const lowest = items.shift();
+    retained.delete(lowest.style);
+  }
+
+  // Restore original ordering by start position
+  return styles.filter((s) => retained.has(s));
+}
+
 /**
  * Split text into chunks safe for Zalo's message length limits.
  * Default max is 650 chars to avoid error 118 (content too long).
@@ -95,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);
@@ -161,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]);
@@ -178,11 +261,13 @@ export function parseMarkdownStyles(input) {
 
 /**
  * Format message into ready-to-send Zalo payload with styles.
+ * Automatically enforces max JSON budget (~250 bytes) for style payload.
  */
-export function buildZaloStyledMessage(text) {
+export function buildZaloStyledMessage(text, { maxStylesJsonLength = MAX_ZALO_STYLE_JSON_LENGTH } = {}) {
   const { text: cleanText, styles } = parseMarkdownStyles(text);
+  const cappedStyles = capStyles(styles, maxStylesJsonLength);
   return {
     msg: cleanText,
-    styles: styles.length > 0 ? styles : undefined,
+    styles: cappedStyles.length > 0 ? cappedStyles : undefined,
   };
 }