abs-zalo-bot 0.3.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +50 -33
  2. package/package.json +15 -7
package/README.md CHANGED
@@ -1,53 +1,61 @@
1
- # ABS Zalo Bot (Agent Business System)
1
+ # ABS Zalo Agent Engine 🚀 (Agent Business System)
2
2
 
3
- **The Most Powerful Autonomous Zalo Engine for AI Agents & Hermes**
3
+ [![npm version](https://img.shields.io/npm/v/abs-zalo-bot.svg?color=blue)](https://www.npmjs.com/package/abs-zalo-bot)
4
+ [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
5
+ [![Automated Tests](https://img.shields.io/badge/Tests-68%2F68%20Passing-brightgreen.svg)](test/)
6
+ [![AI Agent Ready](https://img.shields.io/badge/AI%20Agent-Hermes%20%7C%20Claude%20Code%20%7C%20Codex-purple.svg)](mcp/)
7
+ [![Model Context Protocol](https://img.shields.io/badge/MCP-Standard%20v1.3.0-blueviolet.svg)](mcp/)
4
8
 
5
- Install once · run from a dashboard button or one command · agents read the repo and know how to operate autonomously.
9
+ **The Free, Transparent & Autonomous Zalo AI Agent Engine for Developers, Hermes, Claude Code, and Multi-Agent Frameworks.**
6
10
 
7
- An enterprise-ready local/VPS Zalo bridge for Hermes, Claude Code, Codex and multi-agent systems:
11
+ Install once · run with 1 command or browser QR · AI Agents connect via Model Context Protocol (MCP) to manage Zalo autonomously, safely, and transparently.
8
12
 
9
- - **Zalo Personal QR Engine**: Realtime listener, group management (kick, promote, transfer owner), interactive polls, message reactions, recall (undo), media upload, and destination digests.
10
- - **Zalo Official Account (OA)**: Enterprise webhook adapter for customer support, lead capture, and AI chatbot automation with strict HMAC verification.
11
- - **Policy Guard & RBAC**: Fail-closed by default. Multi-tiered permissions prevent unauthorized mutations or unapproved outbound side-effects.
12
- - **Unified Control Dashboard**: Human-in-the-loop web UI (`http://127.0.0.1:3871`) for QR scanning, source group allowlisting, and emergency kill-switch.
13
- - **Model Context Protocol (MCP)**: Native stdio MCP server (`abs-zalo-mcp`) providing 15+ specialized AI tools for group administration, user intelligence, and interactive workflows.
13
+ ---
14
+
15
+ ## 🌟 Why ABS Zalo Agent Engine?
14
16
 
15
- > Just want it running for the owner? Read the **[Non-coder quickstart](docs/quickstart-non-coder.md)**.
16
- >
17
- > Handing this repo to Claude Code, Codex, Hermes or any other agent? Read **[AGENTS.md](AGENTS.md)** and **[MCP.md](MCP.md)**.
17
+ | Core Advantage | ABS Zalo Agent Engine | Conventional Bots & Scrapers |
18
+ | :--- | :--- | :--- |
19
+ | **Pricing & Freedom** | **100% Free & Open-Source (MIT)** | Paid licenses / Black-box scripts |
20
+ | **Architecture** | **Dual-Adapter: Personal QR + Official OA (Webhook)** | Single unofficial scraping adapter |
21
+ | **Safety & Privacy** | **Fail-Closed PolicyGuard + Secret Redaction** | No guardrails (high ban/checkpoint risk) |
22
+ | **AI Integration** | **Native Model Context Protocol (MCP Stdio Server)** | Raw HTTP webhooks / Manual glue code |
23
+ | **Code Quality** | **68/68 Automated Unit & Integration Tests** | Little to no test coverage |
24
+ | **Multi-Agent Ready** | **Hermes Agent, Claude Code, OpenAI Codex, Cursor** | Single-system or standalone CLI only |
18
25
 
19
26
  ---
20
27
 
21
28
  ## 🇻🇳 Tóm tắt tiếng Việt
22
29
 
23
- `abs-zalo-bot` là hạ tầng kết nối Zalo toàn diện nhất cho AI Agents và Hermes:
24
-
25
- 1. **Zalo Cá nhân (Personal Engine)**: Quản trị nhóm chuyên sâu (kick thành viên, chuyển nhượng trưởng nhóm, bổ nhiệm/bãi nhiệm phó nhóm), tạo & khoá bình chọn (Polls), thả reaction, thu hồi tin nhắn (Undo), tra cứu thông tin người dùng/nhóm, và tự động thu thập ngữ cảnh (Corpus Listener).
26
- 2. **Zalo OA (Doanh nghiệp)**: Webhook 2 chiều chuẩn xác thực HMAC, quản lý hội thoại khách hàng, hỗ trợ lead generation & CSKH tự động.
27
- 3. **Bảo mật & Phân quyền (RBAC Policy Guard)**: Mặc định `fail-closed`, kiểm soát chặt chẽ quyền hạn trước khi thực thi bất kỳ tác vụ gửi tin hay quản trị nhóm nào.
30
+ `abs-zalo-bot` là hạ tầng **Zalo AI Agent** mã nguồn mở miễn phí, an toàn và minh bạch nhất cho các nhà phát triển và doanh nghiệp:
28
31
 
29
- Cài nhanh: `bash setup.sh` rồi `npm start`, mở `http://127.0.0.1:3871`.
32
+ 1. **Zalo Cá nhân (Personal Engine)**: Quản trị nhóm chuyên sâu (Kick thành viên, chuyển nhượng Trưởng nhóm, bổ nhiệm Phó nhóm), tạo & khoá bình chọn (Polls), thả reaction emoji, thu hồi tin nhắn (Recall/Undo), và tự động ghi nhận ngữ cảnh (Corpus Listener).
33
+ 2. **Zalo Official Account (OA Doanh nghiệp)**: Webhook 2 chiều chuẩn bảo mật HMAC, tự động tiếp nhận khách hàng, hỗ trợ phân loại Lead Generation & CSKH 24/7.
34
+ 3. **Bảo mật & Minh bạch (Fail-Closed Policy Guard)**: Tự động che giấu OTP/thông tin nhạy cảm, chống spam, bảo vệ an toàn tài khoản Zalo.
35
+ 4. **Chuẩn Quốc Tế MCP (Model Context Protocol)**: Kết nối trực tiếp và cấp quyền cho AI Agents (Hermes, Claude Code, Codex, Cursor...) làm việc tự chủ mà không cần viết thêm API wrapper.
30
36
 
31
37
  ---
32
38
 
33
39
  ## ⚡ MCP Tool Surface for AI Agents (`abs-zalo-mcp`)
34
40
 
41
+ Attach `npx abs-zalo-bot` or `node mcp/server.js` to your Agent configuration:
42
+
35
43
  | Category | Tool Name | Description |
36
44
  | :--- | :--- | :--- |
37
- | **Telemetry & Health** | `abs_zalo_status` | Check bridge connection, safety flags & corpus counts |
45
+ | **Telemetry & Health** | `abs_zalo_status` | Check bridge status, safety flags, and message corpus count |
38
46
  | | `abs_zalo_list_groups` | List allowlisted source & destination groups |
39
- | | `abs_zalo_recent_messages` | Read captured message streams with rich metadata |
47
+ | | `abs_zalo_recent_messages` | Read captured message streams with full metadata |
40
48
  | | `abs_zalo_corpus_summary` | Get aggregated inventory of users, groups, and logs |
41
49
  | **Group Administration** | `abs_zalo_kick_member` | Remove a member from a group (Admin/Owner required) |
42
50
  | | `abs_zalo_transfer_owner` | Transfer group ownership (Owner required) |
43
51
  | | `abs_zalo_add_deputy` | Promote a member to Group Deputy / Admin |
44
52
  | | `abs_zalo_remove_deputy` | Demote a Group Deputy back to regular member |
45
- | | `abs_zalo_invite_member` | Invite a user into a group |
53
+ | | `abs_zalo_invite_member` | Invite / add a user into a group |
46
54
  | **Interaction & Polls** | `abs_zalo_create_poll` | Create interactive polls with custom options |
47
55
  | | `abs_zalo_lock_poll` | Lock / close an active voting poll |
48
56
  | | `abs_zalo_react_message` | Send emoji reactions to messages (`/:heart`, `/:like`, etc.) |
49
57
  | | `abs_zalo_undo_message` | Recall / undo a previously sent message |
50
- | **Discovery & Search** | `abs_zalo_get_user_info` | Fetch public user profile by userId |
58
+ | **Discovery & Intel** | `abs_zalo_get_user_info` | Fetch public user profile by userId |
51
59
  | | `abs_zalo_get_group_info` | Fetch group settings and metadata |
52
60
  | | `abs_zalo_find_user` | Lookup user profile by phone number |
53
61
  | | `abs_zalo_list_friends` | List all friends of the account |
@@ -55,28 +63,37 @@ Cài nhanh: `bash setup.sh` rồi `npm start`, mở `http://127.0.0.1:3871`.
55
63
 
56
64
  ---
57
65
 
58
- ## 🚀 Quickstart & Verification
66
+ ## 🚀 Quickstart
59
67
 
68
+ ### 1. Global Installation (via npm)
60
69
  ```bash
61
- # 1. Install dependencies
62
- npm ci
70
+ npm install -g abs-zalo-bot
71
+ ```
63
72
 
64
- # 2. Run system doctor & verify tests (68 tests passing)
65
- npm run doctor
73
+ ### 2. Run with Node / NPM
74
+ ```bash
75
+ # Clone repository
76
+ git clone https://github.com/teddiesloco/abs-zalo-bot.git
77
+ cd abs-zalo-bot
78
+
79
+ # Install & Run tests
80
+ npm ci
66
81
  npm test
67
82
 
68
- # 3. Start the daemon (Port 3871)
83
+ # Start the daemon
69
84
  npm start
70
-
71
- # 4. Attach MCP Server to Hermes or Claude Desktop
72
- node mcp/server.js
73
85
  ```
74
86
 
87
+ ### 3. Open Control Dashboard
88
+ Open `http://127.0.0.1:3871` in your browser to scan QR code, configure group policies, and manage your AI Agent bridge.
89
+
90
+ ---
91
+
75
92
  ## 🔒 Security & Policy Boundaries
76
93
 
77
94
  - **Side-effect control**: Every outbound message and administrative action is audited through `PolicyGuard`.
78
- - **Credential isolation**: All session cookies and tokens are kept in private local storage; never exposed over prompts or logs.
95
+ - **Credential isolation**: Session cookies and tokens are kept in private local storage; never exposed over prompts or logs.
79
96
  - **Fail-closed default**: Inbound events are listener-only until explicitly allowlisted.
80
97
 
81
98
  ---
82
- *Built with ❤️ by ABS (Agent Business System).*
99
+ *Built with ❤️ by ABS (Agent Business System) for the Global & Vietnamese AI Agent Community.*
package/package.json CHANGED
@@ -1,21 +1,29 @@
1
1
  {
2
2
  "name": "abs-zalo-bot",
3
- "version": "0.3.0",
3
+ "version": "0.3.1",
4
4
  "type": "module",
5
- "description": "ABS Zalo Engine for AI Agents & Hermes. Personal QR & Official OA adapters, group administration, polls, reactions, fail-closed policy guard.",
5
+ "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.",
6
6
  "author": "teddiesloco",
7
7
  "license": "MIT",
8
8
  "keywords": [
9
9
  "zalo",
10
+ "zalo-agent",
10
11
  "zalo-bot",
11
- "zca-js",
12
- "chatbot",
13
- "messaging",
14
12
  "ai-agent",
13
+ "ai-agents",
14
+ "hermes-agent",
15
+ "claude-code",
16
+ "codex",
15
17
  "mcp",
18
+ "model-context-protocol",
19
+ "zca-js",
20
+ "chatbot",
21
+ "lead-generation",
16
22
  "vietnam",
17
23
  "official-account",
18
- "personal-qr"
24
+ "personal-qr",
25
+ "autonomous-agent",
26
+ "open-source"
19
27
  ],
20
28
  "homepage": "https://github.com/teddiesloco/abs-zalo-bot#readme",
21
29
  "repository": {
@@ -37,7 +45,7 @@
37
45
  "LICENSE"
38
46
  ],
39
47
  "bin": {
40
- "zalo-personal-mcp": "./mcp/server.js"
48
+ "zalo-personal-mcp": "mcp/server.js"
41
49
  },
42
50
  "scripts": {
43
51
  "start": "node src/cli.js serve",