abs-zalo-bot 0.6.0 → 0.7.0

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/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.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/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

@@ -325,7 +325,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);
   }

package/src/zalo_styler.js

@@ -18,6 +18,70 @@ export const ZALO_STYLES = {
   Indent: "ind_$",
 };
 
+export const MAX_ZALO_STYLE_JSON_LENGTH = 250;
+export const MAX_ZALO_UTF16_LENGTH = 2800;
+
+/**
+ * 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).
@@ -178,11 +242,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,
   };
 }