@softtynet/zca-js 2.2.7 → 2.2.8
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.
- package/README.md +159 -179
- package/dist/cjs/update.cjs +8 -6
- package/dist/update.js +8 -6
- package/package.json +12 -9
- package/CODE_OF_CONDUCT.md +0 -163
- package/CONTRIBUTING.md +0 -470
- package/SECURITY.md +0 -83
package/README.md
CHANGED
|
@@ -1,54 +1,72 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @softtynet/zca-js — Softtynet Zalo API SDK for Node.js & Bun
|
|
2
2
|
|
|
3
|
-
>
|
|
4
|
-
|
|
5
|
-
>
|
|
6
|
-
|
|
3
|
+
<p align="left">
|
|
4
|
+
<a href="https://www.npmjs.com/package/@softtynet/zca-js"><img src="https://img.shields.io/npm/v/@softtynet/zca-js.svg?label=%40softtynet%2Fzca-js&color=0068ff" alt="npm version" /></a>
|
|
5
|
+
<a href="https://github.com/softtyos/zca-js"><img src="https://img.shields.io/badge/Maintained%20by-Softtynet%20Co.%2C%20Ltd.-0a7cff" alt="Maintained by Softtynet" /></a>
|
|
6
|
+
<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License: MIT" /></a>
|
|
7
|
+
</p>
|
|
8
|
+
|
|
9
|
+
**`@softtynet/zca-js`** là bộ thư viện Zalo API nâng cao dành cho Node.js / TypeScript / Bun, được phát triển, tối ưu hoá và duy trì bởi **Softtynet Co., Ltd.** nhằm đáp ứng các bài toán tích hợp chuyên sâu: **Đồng bộ dữ liệu đa thiết bị (Offline Catch-up & Mobile Backup Sync `ZDB4.0`)**, **Tín hiệu Gọi Thoại & Gọi Video (Voice / Video Call Signaling)**, và **Xử lý WebSocket thời gian thực độ tin cậy cao**.
|
|
7
10
|
|
|
8
11
|
> [!WARNING]
|
|
9
|
-
>
|
|
12
|
+
> Đây là thư viện tương tác không chính thức thông qua giao thức Zalo Web / Zalo PC dành cho tài khoản cá nhân. Vui lòng sử dụng có trách nhiệm và tuân thủ quy định an toàn tài khoản.
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## Mục lục
|
|
17
|
+
|
|
18
|
+
- [Điểm nổi bật trên phiên bản Softtynet (`@softtynet/zca-js`)](#-điểm-nổi-bật-trên-phiên-bản-softtynet-softtynetzca-js)
|
|
19
|
+
- [Cài đặt](#-cài-đặt)
|
|
20
|
+
- [Tài liệu chuyên sâu](#-tài-liệu-chuyên-sâu)
|
|
21
|
+
- [Hướng dẫn sử dụng nhanh](#-hướng-dẫn-sử-dụng-nhanh)
|
|
22
|
+
- [1. Đăng nhập & Lưu phiên](#1-đăng-nhập--lưu-phiên)
|
|
23
|
+
- [2. Lắng nghe tin nhắn thời gian thực](#2-lắng-nghe-tin-nhắn-thời-gian-thực)
|
|
24
|
+
- [3. Đồng bộ bù tin nhắn khi Offline (Catch-up Sync)](#3-đồng-bộ-bù-tin-nhắn-khi-offline-catch-up-sync)
|
|
25
|
+
- [4. Đồng bộ lịch sử sao lưu từ Điện thoại (`ZDB4.0`)](#4-đồng-bộ-lịch-sử-sao-lưu-từ-điện-thoại-zdb40)
|
|
26
|
+
- [5. Khởi tạo Cuộc gọi Thoại & Gọi Video](#5-khởi-tạo-cuộc-gọi-thoại--gọi-video)
|
|
27
|
+
- [6. Gửi tin nhắn & Sticker](#6-gửi-tin-nhắn--sticker)
|
|
28
|
+
- [Kiểm định & Chạy thử nghiệm](#-kiểm-định--chạy-thử-nghiệm)
|
|
29
|
+
- [Nguồn gốc & Ghi nhận (Credits & Attribution)](#-nguồn-gốc--ghi-nhận-credits--attribution)
|
|
30
|
+
- [Giấy phép (License)](#-giấy-phép-license)
|
|
10
31
|
|
|
11
32
|
---
|
|
12
33
|
|
|
13
|
-
##
|
|
14
|
-
|
|
15
|
-
-
|
|
16
|
-
|
|
17
|
-
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
- [Support Us](#support-us)
|
|
29
|
-
|
|
30
|
-
## Installation
|
|
34
|
+
## 🚀 Điểm nổi bật trên phiên bản Softtynet (`@softtynet/zca-js`)
|
|
35
|
+
|
|
36
|
+
So với phiên bản cộng đồng tiêu chuẩn, **`@softtynet/zca-js`** bổ sung các phân hệ cốt lõi đã được kiểm định trực tiếp trên máy chủ Zalo thật:
|
|
37
|
+
|
|
38
|
+
| Phân hệ | Tính năng trên `@softtynet/zca-js` |
|
|
39
|
+
| :--- | :--- |
|
|
40
|
+
| **Đồng bộ bù khi Offline (Catch-up Sync)** | Hỗ trợ [`api.preloadConversations()`](src/apis/preloadConversations.ts) (`cmd 10053`), kéo hàng đợi tin nhắn cá nhân & nhóm qua [`api.listener.requestOldMessages()`](src/apis/listen.ts) (`cmd 510` / `511`, cả `subCmd 0` & `1`), kèm cờ phân trang `hasMore`, tách biệt sự kiện thu hồi `undo` và đồng bộ trạng thái đã đọc `unread_cleared` (`cmd 504` / `524`). |
|
|
41
|
+
| **Đồng bộ sao lưu từ Điện thoại (`ZDB4.0`)** | Hỗ trợ trọn vẹn chu trình [`api.requestSyncFromPhone()`](src/apis/requestSyncFromPhone.ts) (`cmd 12000`), [`api.cancelPullMobile()`](src/apis/cancelPullMobile.ts) (`cmd 12700`), sự kiện `sync_event` (`user_confirm`, `syncmsg_info`, `transfer_after_login`), tải gói `.db.crypt` qua [`api.getSyncData()`](src/apis/getSyncData.ts) và giải mã RSA-2048 PKCS#1 v1.5 + AES-256-CBC đa khối 64KB + đọc mục lục SQLite (`parseZdbHeader`). |
|
|
42
|
+
| **Ánh xạ ID ẩn danh (Noised / Global ID)** | Hỗ trợ [`api.getNoisedIds()`](src/apis/getNoisedIds.ts) (`cmd 12390` kèm cơ chế tự động fallback sang `zwid.api.zalo.me`) và [`api.decryptGids()`](src/apis/decryptGids.ts) (`cmd 12054`) để ánh xạ tên file SQLite `3_<me>_<peer>.db` về User ID / Group ID thật. |
|
|
43
|
+
| **Gọi Thoại & Gọi Video (Signaling 2 bước)** | Hỗ trợ [`api.sendVoiceCall()`](src/apis/sendVoiceCall.ts) (`cmd 11300` + `11301`), [`api.cancelVoiceCall()`](src/apis/cancelVoiceCall.ts) (`cmd 11305`), [`api.endVoiceCall()`](src/apis/endVoiceCall.ts) (`cmd 11306`) và sự kiện `call_event` chuẩn giao thức C++ `ZaloCall` cho cả **Gọi Thoại (`CallType.Audio = 1`)** lẫn **Gọi Video (`CallType.Video = 3`, H.264)**. |
|
|
44
|
+
| **Độ ổn định & Bảo vệ bộ nhớ** | Tự động giải phóng bộ nhớ `uploadCallbacks` sau 5 phút trong [`uploadAttachment`](src/apis/uploadAttachment.ts), xử lý phản hồi rỗng hợp lệ (`error_code === 0, data === ""`) và bảo toàn độ chính xác chuỗi UID 19 chữ số. |
|
|
45
|
+
|
|
46
|
+
---
|
|
47
|
+
|
|
48
|
+
## 📦 Cài đặt
|
|
31
49
|
|
|
32
50
|
```bash
|
|
33
|
-
|
|
51
|
+
npm install @softtynet/zca-js
|
|
52
|
+
# hoặc dùng Bun
|
|
53
|
+
bun add @softtynet/zca-js
|
|
34
54
|
```
|
|
35
55
|
|
|
36
|
-
###
|
|
56
|
+
### Cấu hình `imageMetadataGetter` (Khi gửi ảnh từ đường dẫn file)
|
|
37
57
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
Example of custom `imageMetadataGetter` using `sharp`:
|
|
58
|
+
Từ kiến trúc V2, thư viện tách rời phụ thuộc xử lý ảnh để giữ dung lượng gọn nhẹ. Nếu ứng dụng của bạn gửi ảnh/GIF từ file nội bộ, hãy truyền hàm `imageMetadataGetter` (ví dụ dùng `sharp`):
|
|
41
59
|
|
|
42
60
|
```bash
|
|
43
|
-
|
|
61
|
+
npm install sharp
|
|
44
62
|
```
|
|
45
63
|
|
|
46
|
-
```
|
|
47
|
-
import { Zalo } from "zca-js";
|
|
64
|
+
```ts
|
|
65
|
+
import { Zalo } from "@softtynet/zca-js";
|
|
48
66
|
import sharp from "sharp";
|
|
49
67
|
import fs from "node:fs";
|
|
50
68
|
|
|
51
|
-
async function imageMetadataGetter(filePath) {
|
|
69
|
+
async function imageMetadataGetter(filePath: string) {
|
|
52
70
|
const data = await fs.promises.readFile(filePath);
|
|
53
71
|
const metadata = await sharp(data).metadata();
|
|
54
72
|
return {
|
|
@@ -58,80 +76,75 @@ async function imageMetadataGetter(filePath) {
|
|
|
58
76
|
};
|
|
59
77
|
}
|
|
60
78
|
|
|
61
|
-
const zalo = new Zalo({
|
|
62
|
-
imageMetadataGetter,
|
|
63
|
-
});
|
|
79
|
+
const zalo = new Zalo({ imageMetadataGetter });
|
|
64
80
|
```
|
|
65
81
|
|
|
66
82
|
---
|
|
67
83
|
|
|
68
|
-
##
|
|
84
|
+
## 📚 Tài liệu chuyên sâu
|
|
69
85
|
|
|
70
|
-
- [
|
|
71
|
-
- [
|
|
72
|
-
- [
|
|
86
|
+
- **[Hướng dẫn Tích hợp: Đồng bộ Tin nhắn Đa Thiết bị (`ZDB4.0`) & Gọi Thoại / Video](docs/INTEGRATION_GUIDE_SYNC_AND_CALL.md)** — Tài liệu đầy đủ kèm sơ đồ kiến trúc và code mẫu tích hợp thực tế của Softtynet.
|
|
87
|
+
- **[Kế hoạch & Hướng dẫn Dịch ngược Zalo bằng REA (`morluto/rea`)](docs/REA_REVERSE_ENGINEERING_PLAN.md)** — Tài liệu quy trình phân tích tĩnh Binary C++ (`ZaloCall`, `libzdatabase.dylib`) và ASAR.
|
|
88
|
+
- **[API Reference Cơ bản](https://zca-js.tdung.com)** — Tra cứu danh mục các API cơ bản.
|
|
73
89
|
|
|
74
90
|
---
|
|
75
91
|
|
|
76
|
-
##
|
|
92
|
+
## ⚡ Hướng dẫn sử dụng nhanh
|
|
77
93
|
|
|
78
|
-
###
|
|
94
|
+
### 1. Đăng nhập & Lưu phiên
|
|
79
95
|
|
|
80
|
-
```
|
|
81
|
-
import { Zalo } from "zca-js";
|
|
96
|
+
```ts
|
|
97
|
+
import { Zalo } from "@softtynet/zca-js";
|
|
82
98
|
|
|
83
|
-
const zalo = new Zalo();
|
|
99
|
+
const zalo = new Zalo({ selfListen: true });
|
|
84
100
|
const api = await zalo.loginQR();
|
|
101
|
+
console.log("Đã đăng nhập với UID:", api.getOwnId());
|
|
85
102
|
```
|
|
86
103
|
|
|
87
|
-
###
|
|
104
|
+
### 2. Lắng nghe tin nhắn thời gian thực
|
|
88
105
|
|
|
89
|
-
```
|
|
90
|
-
import { Zalo, ThreadType } from "zca-js";
|
|
106
|
+
```ts
|
|
107
|
+
import { Zalo, ThreadType } from "@softtynet/zca-js";
|
|
91
108
|
|
|
92
|
-
const zalo = new Zalo();
|
|
109
|
+
const zalo = new Zalo({ selfListen: true });
|
|
93
110
|
const api = await zalo.loginQR();
|
|
94
111
|
|
|
95
112
|
api.listener.on("message", (message) => {
|
|
96
113
|
const isPlainText = typeof message.data.content === "string";
|
|
114
|
+
if (!isPlainText) return;
|
|
97
115
|
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
}
|
|
103
|
-
break;
|
|
104
|
-
}
|
|
105
|
-
case ThreadType.Group: {
|
|
106
|
-
if (isPlainText) {
|
|
107
|
-
// received plain text group message
|
|
108
|
-
}
|
|
109
|
-
break;
|
|
110
|
-
}
|
|
116
|
+
if (message.type === ThreadType.User) {
|
|
117
|
+
console.log(`[Cá nhân] ${message.data.dName}: ${message.data.content}`);
|
|
118
|
+
} else if (message.type === ThreadType.Group) {
|
|
119
|
+
console.log(`[Nhóm ${message.threadId}] ${message.data.dName}: ${message.data.content}`);
|
|
111
120
|
}
|
|
112
121
|
});
|
|
113
122
|
|
|
114
|
-
api.listener.start();
|
|
123
|
+
api.listener.start({ retryOnClose: true });
|
|
115
124
|
```
|
|
116
125
|
|
|
117
126
|
> [!IMPORTANT]
|
|
118
|
-
>
|
|
127
|
+
> Mỗi tài khoản Zalo chỉ duy trì một kết nối WebSocket Web tại một thời điểm. Nếu bạn mở thêm tab Zalo Web trên trình duyệt, kết nối WebSocket cũ sẽ nhận sự kiện `duplicate_connection`.
|
|
119
128
|
|
|
120
|
-
###
|
|
129
|
+
### 3. Đồng bộ bù tin nhắn khi Offline (Catch-up Sync)
|
|
121
130
|
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
#### 1. Catch Up Missed Messages After Reconnect / Restart
|
|
125
|
-
```javascript
|
|
126
|
-
import { Zalo, ThreadType } from "zca-js";
|
|
131
|
+
```ts
|
|
132
|
+
import { ThreadType } from "@softtynet/zca-js";
|
|
127
133
|
|
|
134
|
+
// 1. Lấy nhanh các tin nhắn mới nhất & danh sách đã đọc qua HTTP (cmd 10053)
|
|
128
135
|
const preload = await api.preloadConversations();
|
|
129
|
-
console.log(`Preloaded ${preload.messages.length}
|
|
136
|
+
console.log(`Preloaded: ${preload.messages.length} tin nhắn, ${preload.unreadCleared.length} trạng thái đã đọc`);
|
|
130
137
|
|
|
138
|
+
// 2. Nhận tin nhắn từ hàng đợi WebSocket (cmd 510 & 511)
|
|
131
139
|
api.listener.on("old_messages", (messages, type, hasMore) => {
|
|
132
|
-
console.log(`
|
|
140
|
+
console.log(`Nhận ${messages.length} tin nhắn cũ (type=${type}, hasMore=${hasMore})`);
|
|
141
|
+
if (hasMore && messages.length > 0) {
|
|
142
|
+
const lastMsgId = messages[messages.length - 1].data.msgId;
|
|
143
|
+
api.listener.requestOldMessages(type, lastMsgId);
|
|
144
|
+
}
|
|
133
145
|
});
|
|
134
146
|
|
|
147
|
+
// 3. Kích hoạt kéo hàng đợi ngay khi nhận khoá giải mã WebSocket
|
|
135
148
|
api.listener.on("cipher_key", () => {
|
|
136
149
|
api.listener.requestOldMessages(ThreadType.User);
|
|
137
150
|
api.listener.requestOldMessages(ThreadType.Group);
|
|
@@ -140,155 +153,122 @@ api.listener.on("cipher_key", () => {
|
|
|
140
153
|
api.listener.start({ retryOnClose: true });
|
|
141
154
|
```
|
|
142
155
|
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
156
|
+
### 4. Đồng bộ lịch sử sao lưu từ Điện thoại (`ZDB4.0`)
|
|
157
|
+
|
|
158
|
+
```ts
|
|
159
|
+
import fs from "node:fs";
|
|
160
|
+
import {
|
|
161
|
+
SyncEventType,
|
|
162
|
+
decryptWithPrivateKey,
|
|
163
|
+
deriveZdbAesKey,
|
|
164
|
+
decryptZdbBuffer,
|
|
165
|
+
parseZdbHeader,
|
|
166
|
+
} from "@softtynet/zca-js";
|
|
146
167
|
|
|
147
168
|
let privateKey = "";
|
|
148
169
|
|
|
149
170
|
api.listener.on("sync_event", async (event) => {
|
|
150
171
|
if (event.type === SyncEventType.USER_CONFIRM) {
|
|
151
|
-
console.log("
|
|
172
|
+
console.log("Người dùng đã bấm xác nhận trên điện thoại, đang chờ tải gói sao lưu...");
|
|
152
173
|
} else if (event.type === SyncEventType.SYNCMSG_INFO) {
|
|
153
174
|
const res = await api.getSyncData({ ...event.data, savePath: "./sync_data" });
|
|
154
175
|
if (res.success && res.data && privateKey) {
|
|
155
176
|
const rawRsa = decryptWithPrivateKey(privateKey, res.data.encrypted_key);
|
|
156
177
|
const aesKey = deriveZdbAesKey(rawRsa);
|
|
157
|
-
|
|
178
|
+
const zdbPlain = decryptZdbBuffer(fs.readFileSync(res.data.file_path), aesKey);
|
|
179
|
+
const toc = parseZdbHeader(zdbPlain);
|
|
180
|
+
console.log(`Giải mã thành công ZDB4.0 (${toc.entries.length} hội thoại SQLite):`, toc.entries.slice(0, 5));
|
|
158
181
|
}
|
|
159
182
|
}
|
|
160
183
|
});
|
|
161
184
|
|
|
162
|
-
api.listener.on("
|
|
163
|
-
const session = await api.requestSyncFromPhone();
|
|
185
|
+
api.listener.on("cipher_key", async () => {
|
|
186
|
+
const session = await api.requestSyncFromPhone({ pcName: "Web" });
|
|
164
187
|
privateKey = session.privateKey;
|
|
165
|
-
console.log("
|
|
188
|
+
console.log("Vui lòng mở điện thoại và bấm 'Đồng bộ ngay' trên thông báo Zalo!");
|
|
166
189
|
});
|
|
167
|
-
|
|
168
|
-
api.listener.start();
|
|
169
190
|
```
|
|
170
191
|
|
|
171
|
-
###
|
|
192
|
+
### 5. Khởi tạo Cuộc gọi Thoại & Gọi Video
|
|
172
193
|
|
|
173
|
-
```
|
|
174
|
-
import { CallType } from "zca-js";
|
|
194
|
+
```ts
|
|
195
|
+
import { CallType } from "@softtynet/zca-js";
|
|
175
196
|
|
|
176
|
-
|
|
177
|
-
const call = await api.sendVoiceCall("target_user_id", { callType: CallType.Audio });
|
|
178
|
-
console.log("Ringing callId:", call.callId, "session:", call.sessId);
|
|
179
|
-
|
|
180
|
-
// Cancel ringing or end an active call
|
|
181
|
-
await api.cancelVoiceCall("target_user_id", call.callId);
|
|
182
|
-
```
|
|
197
|
+
const targetUid = "5249661060655759359"; // Chuỗi UID 19 chữ số
|
|
183
198
|
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
const zalo = new Zalo();
|
|
190
|
-
const api = await zalo.loginQR();
|
|
199
|
+
// Gọi Video (CallType.Video = 3, tự động đính kèm H.264 payload 97)
|
|
200
|
+
const videoCall = await api.sendVoiceCall(targetUid, {
|
|
201
|
+
callType: CallType.Video,
|
|
202
|
+
});
|
|
203
|
+
console.log("Đang đổ chuông Video:", videoCall.callId, videoCall.rtpServer);
|
|
191
204
|
|
|
192
|
-
//
|
|
193
|
-
api.
|
|
194
|
-
|
|
195
|
-
if (message.isSelf || !isPlainText) return;
|
|
196
|
-
|
|
197
|
-
switch (message.type) {
|
|
198
|
-
case ThreadType.User: {
|
|
199
|
-
api.sendMessage(
|
|
200
|
-
{
|
|
201
|
-
msg: "echo: " + message.data.content,
|
|
202
|
-
quote: message.data, // the message to reply to (optional)
|
|
203
|
-
},
|
|
204
|
-
message.threadId,
|
|
205
|
-
message.type, // ThreadType.User
|
|
206
|
-
);
|
|
207
|
-
break;
|
|
208
|
-
}
|
|
209
|
-
case ThreadType.Group: {
|
|
210
|
-
api.sendMessage(
|
|
211
|
-
{
|
|
212
|
-
msg: "echo: " + message.data.content,
|
|
213
|
-
quote: message.data, // the message to reply to (optional)
|
|
214
|
-
},
|
|
215
|
-
message.threadId,
|
|
216
|
-
message.type, // ThreadType.Group
|
|
217
|
-
);
|
|
218
|
-
break;
|
|
219
|
-
}
|
|
220
|
-
}
|
|
205
|
+
// Huỷ cuộc gọi khi đang đổ chuông
|
|
206
|
+
await api.cancelVoiceCall(targetUid, videoCall.callId, {
|
|
207
|
+
callType: CallType.Video,
|
|
221
208
|
});
|
|
222
209
|
|
|
223
|
-
|
|
210
|
+
// Hoặc gọi Thoại (CallType.Audio = 1)
|
|
211
|
+
const audioCall = await api.sendVoiceCall(targetUid, {
|
|
212
|
+
callType: CallType.Audio,
|
|
213
|
+
});
|
|
214
|
+
await api.cancelVoiceCall(targetUid, audioCall.callId);
|
|
224
215
|
```
|
|
225
216
|
|
|
226
|
-
###
|
|
227
|
-
|
|
228
|
-
```
|
|
229
|
-
|
|
230
|
-
|
|
217
|
+
### 6. Gửi tin nhắn & Sticker
|
|
218
|
+
|
|
219
|
+
```ts
|
|
220
|
+
// Trả lời tin nhắn văn bản
|
|
221
|
+
await api.sendMessage(
|
|
222
|
+
{
|
|
223
|
+
msg: "Xin chào từ hệ thống Softtynet!",
|
|
224
|
+
quote: message.data,
|
|
225
|
+
},
|
|
226
|
+
message.threadId,
|
|
227
|
+
message.type,
|
|
228
|
+
);
|
|
229
|
+
|
|
230
|
+
// Tìm và gửi Sticker
|
|
231
|
+
const stickerIds = await api.getStickers("xin chào");
|
|
232
|
+
if (stickerIds.length > 0) {
|
|
231
233
|
const stickerObject = await api.getStickersDetail(stickerIds[0]);
|
|
232
|
-
api.sendMessageSticker(
|
|
233
|
-
|
|
234
|
-
message.threadId,
|
|
235
|
-
message.type, // ThreadType.User or ThreadType.Group
|
|
236
|
-
);
|
|
237
|
-
});
|
|
234
|
+
await api.sendMessageSticker(stickerObject, message.threadId, message.type);
|
|
235
|
+
}
|
|
238
236
|
```
|
|
239
237
|
|
|
240
238
|
---
|
|
241
239
|
|
|
242
|
-
##
|
|
243
|
-
|
|
244
|
-
See [examples](examples) folder for more details.
|
|
245
|
-
|
|
246
|
-
---
|
|
240
|
+
## 🧪 Kiểm định & Chạy thử nghiệm
|
|
247
241
|
|
|
248
|
-
|
|
242
|
+
Dự án đi kèm bộ kiểm định 2 lớp trong thư mục [`test/`](test):
|
|
249
243
|
|
|
250
|
-
|
|
244
|
+
1. **Kiểm định tự động (Offline / Unit Verification Suite)**:
|
|
245
|
+
```bash
|
|
246
|
+
npm run test:verify
|
|
247
|
+
```
|
|
248
|
+
Kiểm tra tự động toàn bộ 6 hạng mục: `preloadConversations`, `requestSyncFromPhone` / `pullMobile` / `cancelPullMobile`, `getNoisedIds` / `decryptGids`, giải mã `RSA-2048` + `ZDB4.0` đa khối 64KB, `sendVoiceCall` (Audio & Video) / `cancelVoiceCall` / `endVoiceCall`, và các sự kiện WebSocket (`510`, `511`, `504`, `601`).
|
|
251
249
|
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
| [**n8n-nodes-zalo-tools**](https://github.com/ChickenAI/zalo-node) | N8N node for personal Zalo account. |
|
|
257
|
-
| [**Zalo-F12**](https://github.com/ElectroHeavenVN/Zalo-F12) | A collection of JavaScript code snippets to paste into DevTools to change how Zalo Web/PC works. |
|
|
258
|
-
| [**Zalo-F12-Tools**](https://github.com/JustKemForFun/Zalo-F12-Tools) | Toggle hidden modes for Zalo Web. |
|
|
250
|
+
2. **Kiểm định trực tiếp trên tài khoản Zalo thật (Live Verification Suite)**:
|
|
251
|
+
```bash
|
|
252
|
+
# Chạy toàn bộ 6 bước (Quét QR -> Preload -> ZNoise -> OldMessages -> Đồng bộ ZDB4.0 từ ĐT -> Voice/Video Call)
|
|
253
|
+
npm run test:live
|
|
259
254
|
|
|
260
|
-
|
|
255
|
+
# Chỉ test nhanh Gọi Thoại + Gọi Video tới 1 UID bạn bè
|
|
256
|
+
npm run test:live -- --only-call --call <UID_BAN_BE>
|
|
257
|
+
```
|
|
261
258
|
|
|
262
259
|
---
|
|
263
260
|
|
|
264
|
-
##
|
|
265
|
-
|
|
266
|
-
We welcome contributions from the community! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details on how to:
|
|
267
|
-
|
|
268
|
-
- 🐛 Report bugs and issues
|
|
269
|
-
- ✨ Suggest new features
|
|
270
|
-
- 🔧 Submit code contributions
|
|
271
|
-
- 📚 Improve documentation
|
|
272
|
-
- 🧪 Add or improve tests
|
|
273
|
-
- 🔒 Report security vulnerabilities
|
|
261
|
+
## 🤝 Nguồn gốc & Ghi nhận (Credits & Attribution)
|
|
274
262
|
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
---
|
|
263
|
+
Dự án **`@softtynet/zca-js`** được phát triển, nâng cấp và duy trì bởi **Softtynet Co., Ltd.** ([`softtyos/zca-js`](https://github.com/softtyos/zca-js)), kế thừa nền tảng mã nguồn mở từ dự án gốc:
|
|
278
264
|
|
|
279
|
-
|
|
265
|
+
- **Dự án gốc**: [RFS-ADRENO/zca-js](https://github.com/RFS-ADRENO/zca-js)
|
|
266
|
+
- **Tác giả nền tảng gốc**: RFS-ADRENO, truong9c2208, JustKemForFun cùng các thành viên đóng góp từ cộng đồng mã nguồn mở.
|
|
280
267
|
|
|
281
|
-
|
|
268
|
+
Chúng tôi trân trọng cảm ơn các tác giả của dự án gốc đã xây dựng nền tảng ban đầu cho cộng đồng JavaScript/TypeScript.
|
|
282
269
|
|
|
283
270
|
---
|
|
284
271
|
|
|
285
|
-
##
|
|
272
|
+
## 📄 Giấy phép (License)
|
|
286
273
|
|
|
287
|
-
|
|
288
|
-
- 🔄 **Share** with your network to help us grow
|
|
289
|
-
- 💡 **Contribute** your ideas and code
|
|
290
|
-
- ☕ **A coffee**:
|
|
291
|
-
- [Buy Me a Coffee](https://ko-fi.com/grosse)
|
|
292
|
-
- [Paypal](https://www.paypal.com/paypalme/dungto213)
|
|
293
|
-
- [VietQR](https://github.com/user-attachments/assets/e1f319d6-9d11-4082-8248-55b55e645caa)
|
|
294
|
-
- [Momo](https://me.momo.vn/gMIMulsaUqsbf6iAiXt3)
|
|
274
|
+
Phát hành theo giấy phép [MIT License](LICENSE).
|
package/dist/cjs/update.cjs
CHANGED
|
@@ -3,10 +3,10 @@
|
|
|
3
3
|
var semver = require('semver');
|
|
4
4
|
var utils = require('./utils.cjs');
|
|
5
5
|
|
|
6
|
-
const VERSION = "2.2.
|
|
7
|
-
const NPM_REGISTRY = "https://registry.npmjs.org/zca-js";
|
|
6
|
+
const VERSION = "2.2.7";
|
|
7
|
+
const NPM_REGISTRY = "https://registry.npmjs.org/@softtynet/zca-js";
|
|
8
8
|
async function checkUpdate(ctx) {
|
|
9
|
-
var _a, _b;
|
|
9
|
+
var _a, _b, _c;
|
|
10
10
|
if (!ctx.options.checkUpdate)
|
|
11
11
|
return;
|
|
12
12
|
const _options = Object.assign({}, (utils.isBun
|
|
@@ -22,12 +22,14 @@ async function checkUpdate(ctx) {
|
|
|
22
22
|
const data = await response.json().catch(() => null);
|
|
23
23
|
if (!data)
|
|
24
24
|
return;
|
|
25
|
-
const latestVersion = data["dist-tags"].latest;
|
|
25
|
+
const latestVersion = (_c = data["dist-tags"]) === null || _c === void 0 ? void 0 : _c.latest;
|
|
26
|
+
if (!latestVersion)
|
|
27
|
+
return;
|
|
26
28
|
if (semver.compare(VERSION, latestVersion) === -1) {
|
|
27
|
-
utils.logger(ctx).info(`A new version of zca-js is available: ${latestVersion}`);
|
|
29
|
+
utils.logger(ctx).info(`A new version of @softtynet/zca-js is available: ${latestVersion}`);
|
|
28
30
|
}
|
|
29
31
|
else {
|
|
30
|
-
utils.logger(ctx).info("zca-js is up to date");
|
|
32
|
+
utils.logger(ctx).info("@softtynet/zca-js is up to date");
|
|
31
33
|
}
|
|
32
34
|
}
|
|
33
35
|
|
package/dist/update.js
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
import { compare } from "semver";
|
|
2
2
|
import { isBun, logger } from "./utils.js";
|
|
3
|
-
const VERSION = "2.2.
|
|
4
|
-
const NPM_REGISTRY = "https://registry.npmjs.org/zca-js";
|
|
3
|
+
const VERSION = "2.2.7";
|
|
4
|
+
const NPM_REGISTRY = "https://registry.npmjs.org/@softtynet/zca-js";
|
|
5
5
|
export async function checkUpdate(ctx) {
|
|
6
|
-
var _a, _b;
|
|
6
|
+
var _a, _b, _c;
|
|
7
7
|
if (!ctx.options.checkUpdate)
|
|
8
8
|
return;
|
|
9
9
|
const _options = Object.assign({}, (isBun
|
|
@@ -19,11 +19,13 @@ export async function checkUpdate(ctx) {
|
|
|
19
19
|
const data = await response.json().catch(() => null);
|
|
20
20
|
if (!data)
|
|
21
21
|
return;
|
|
22
|
-
const latestVersion = data["dist-tags"].latest;
|
|
22
|
+
const latestVersion = (_c = data["dist-tags"]) === null || _c === void 0 ? void 0 : _c.latest;
|
|
23
|
+
if (!latestVersion)
|
|
24
|
+
return;
|
|
23
25
|
if (compare(VERSION, latestVersion) === -1) {
|
|
24
|
-
logger(ctx).info(`A new version of zca-js is available: ${latestVersion}`);
|
|
26
|
+
logger(ctx).info(`A new version of @softtynet/zca-js is available: ${latestVersion}`);
|
|
25
27
|
}
|
|
26
28
|
else {
|
|
27
|
-
logger(ctx).info("zca-js is up to date");
|
|
29
|
+
logger(ctx).info("@softtynet/zca-js is up to date");
|
|
28
30
|
}
|
|
29
31
|
}
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@softtynet/zca-js",
|
|
3
|
-
"version": "2.2.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "2.2.8",
|
|
4
|
+
"description": "Bộ thư viện Zalo API nâng cao phát triển bởi Softtynet (Đồng bộ tin nhắn đa thiết bị ZDB4.0, Catch-up Sync, Voice & Video Call Signaling)",
|
|
5
5
|
"main": "dist/index.js",
|
|
6
6
|
"type": "module",
|
|
7
7
|
"exports": {
|
|
@@ -19,7 +19,6 @@
|
|
|
19
19
|
"build": "npm run build:clean && npm run build:esm && npm run build:cjs",
|
|
20
20
|
"test:verify": "npx tsx test/verify_upgrades.ts",
|
|
21
21
|
"test:live": "npx tsx test/verify_live.ts",
|
|
22
|
-
"test:feat": "npm run test/feat.ts",
|
|
23
22
|
"prettier": "prettier --write .",
|
|
24
23
|
"lint": "eslint .",
|
|
25
24
|
"lint:fix": "eslint . --fix",
|
|
@@ -27,21 +26,25 @@
|
|
|
27
26
|
},
|
|
28
27
|
"repository": {
|
|
29
28
|
"type": "git",
|
|
30
|
-
"url": "git+https://github.com/
|
|
29
|
+
"url": "git+https://github.com/softtyos/zca-js.git"
|
|
31
30
|
},
|
|
32
|
-
"homepage": "https://github.com/
|
|
31
|
+
"homepage": "https://github.com/softtyos/zca-js",
|
|
33
32
|
"bugs": {
|
|
34
|
-
"url": "https://github.com/
|
|
33
|
+
"url": "https://github.com/softtyos/zca-js/issues"
|
|
35
34
|
},
|
|
36
35
|
"engines": {
|
|
37
36
|
"node": ">=18.0.0"
|
|
38
37
|
},
|
|
39
38
|
"keywords": [
|
|
40
|
-
"chatbot",
|
|
41
39
|
"zalo",
|
|
42
|
-
"api"
|
|
40
|
+
"zalo-api",
|
|
41
|
+
"zca-js",
|
|
42
|
+
"softtynet",
|
|
43
|
+
"zalo-sync",
|
|
44
|
+
"zalo-call",
|
|
45
|
+
"chatbot"
|
|
43
46
|
],
|
|
44
|
-
"author": "RFS-ADRENO
|
|
47
|
+
"author": "Softtynet Co., Ltd. (Based on zca-js by RFS-ADRENO)",
|
|
45
48
|
"license": "MIT",
|
|
46
49
|
"dependencies": {
|
|
47
50
|
"crypto-js": "^4.2.0",
|
package/CODE_OF_CONDUCT.md
DELETED
|
@@ -1,163 +0,0 @@
|
|
|
1
|
-
# Code of Conduct
|
|
2
|
-
|
|
3
|
-
## Our Pledge
|
|
4
|
-
|
|
5
|
-
We as members, contributors, and leaders pledge to make participation in our
|
|
6
|
-
community a harassment-free experience for everyone, regardless of age, body
|
|
7
|
-
size, visible or invisible disability, ethnicity, sex characteristics, gender
|
|
8
|
-
identity and expression, level of experience, education, socio-economic status,
|
|
9
|
-
nationality, personal appearance, race, religion, or sexual identity
|
|
10
|
-
and orientation.
|
|
11
|
-
|
|
12
|
-
We pledge to act and interact in ways that contribute to an open, welcoming,
|
|
13
|
-
diverse, inclusive, and healthy community.
|
|
14
|
-
|
|
15
|
-
## Our Standards
|
|
16
|
-
|
|
17
|
-
Examples of behavior that contributes to a positive environment for our
|
|
18
|
-
community include:
|
|
19
|
-
|
|
20
|
-
* Demonstrating empathy and kindness toward other people
|
|
21
|
-
* Being respectful of differing opinions, viewpoints, and experiences
|
|
22
|
-
* Giving and gracefully accepting constructive feedback
|
|
23
|
-
* Accepting responsibility and apologizing to those affected by our mistakes,
|
|
24
|
-
and learning from the experience
|
|
25
|
-
* Focusing on what is best not just for us as individuals, but for the
|
|
26
|
-
overall community
|
|
27
|
-
|
|
28
|
-
Examples of unacceptable behavior include:
|
|
29
|
-
|
|
30
|
-
* The use of sexualized language or imagery, and sexual attention or
|
|
31
|
-
advances of any kind
|
|
32
|
-
* Trolling, insulting or derogatory comments, and personal or political attacks
|
|
33
|
-
* Public or private harassment
|
|
34
|
-
* Publishing others' private information, such as a physical or email
|
|
35
|
-
address, without their explicit permission
|
|
36
|
-
* Other conduct which could reasonably be considered inappropriate in a
|
|
37
|
-
professional setting
|
|
38
|
-
|
|
39
|
-
## Enforcement Responsibilities
|
|
40
|
-
|
|
41
|
-
Community leaders are responsible for clarifying and enforcing our standards of
|
|
42
|
-
acceptable behavior and will take appropriate and fair corrective action in
|
|
43
|
-
response to any behavior that they deem inappropriate, threatening, offensive,
|
|
44
|
-
or harmful.
|
|
45
|
-
|
|
46
|
-
Community leaders have the right and responsibility to remove, edit, or reject
|
|
47
|
-
comments, commits, code, wiki edits, issues, and other contributions that are
|
|
48
|
-
not aligned to this Code of Conduct, and will communicate reasons for moderation
|
|
49
|
-
decisions when appropriate.
|
|
50
|
-
|
|
51
|
-
## Scope
|
|
52
|
-
|
|
53
|
-
This Code of Conduct applies within all community spaces, and also applies when
|
|
54
|
-
an individual is officially representing the community in public spaces.
|
|
55
|
-
Examples of representing our community include using an official e-mail address,
|
|
56
|
-
posting via an official social media account, or acting as an appointed
|
|
57
|
-
representative at an online or offline event.
|
|
58
|
-
|
|
59
|
-
## Enforcement
|
|
60
|
-
|
|
61
|
-
Instances of abusive, harassing, or otherwise unacceptable behavior may be
|
|
62
|
-
reported to the community leaders responsible for enforcement through:
|
|
63
|
-
- **GitHub Issues**: Create a private issue with the `[CONDUCT]` label
|
|
64
|
-
- **GitHub Discussions**: Use the "Community" category for general concerns
|
|
65
|
-
- **Direct Contact**: Reach out to any team member through GitHub
|
|
66
|
-
- **Team Members**:
|
|
67
|
-
- [@RFS-ADRENO](https://github.com/RFS-ADRENO)
|
|
68
|
-
- [@truong9c2208](https://github.com/truong9c2208)
|
|
69
|
-
- [@JustKemForFun](https://github.com/JustKemForFun)
|
|
70
|
-
|
|
71
|
-
All complaints will be reviewed and investigated promptly and fairly by the team.
|
|
72
|
-
|
|
73
|
-
All community leaders are obligated to respect the privacy and security of the
|
|
74
|
-
reporter of any incident.
|
|
75
|
-
|
|
76
|
-
## Enforcement Guidelines
|
|
77
|
-
|
|
78
|
-
Community leaders will follow these Community Impact Guidelines in determining
|
|
79
|
-
the consequences for any action they deem in violation of this Code of Conduct:
|
|
80
|
-
|
|
81
|
-
### 1. Correction
|
|
82
|
-
|
|
83
|
-
**Community Impact**: Use of inappropriate language or other behavior deemed
|
|
84
|
-
unprofessional or unwelcome in the community.
|
|
85
|
-
|
|
86
|
-
**Consequence**: A private, written warning from community leaders, providing
|
|
87
|
-
clarity around the nature of the violation and an explanation of why the
|
|
88
|
-
behavior was inappropriate. A public apology may be requested.
|
|
89
|
-
|
|
90
|
-
### 2. Warning
|
|
91
|
-
|
|
92
|
-
**Community Impact**: A violation through a single incident or series
|
|
93
|
-
of actions.
|
|
94
|
-
|
|
95
|
-
**Consequence**: A warning with consequences for continued behavior. No
|
|
96
|
-
interaction with the people involved, including unsolicited interaction with
|
|
97
|
-
those enforcing the Code of Conduct, for a specified period of time. This
|
|
98
|
-
includes avoiding interactions in community spaces as well as external channels
|
|
99
|
-
like social media. Violating these terms may lead to a temporary or
|
|
100
|
-
permanent ban.
|
|
101
|
-
|
|
102
|
-
### 3. Temporary Ban
|
|
103
|
-
|
|
104
|
-
**Community Impact**: A serious violation of community standards, including
|
|
105
|
-
sustained inappropriate behavior.
|
|
106
|
-
|
|
107
|
-
**Consequence**: A temporary ban from any sort of interaction or public
|
|
108
|
-
communication with the community for a specified period of time. No public or
|
|
109
|
-
private interaction with the people involved, including unsolicited interaction
|
|
110
|
-
with those enforcing the Code of Conduct, is allowed during this period.
|
|
111
|
-
Violating these terms may lead to a permanent ban.
|
|
112
|
-
|
|
113
|
-
### 4. Permanent Ban
|
|
114
|
-
|
|
115
|
-
**Community Impact**: Demonstrating a pattern of violation of community
|
|
116
|
-
standards, including sustained inappropriate behavior, harassment of an
|
|
117
|
-
individual, or aggression toward or disparagement of classes of individuals.
|
|
118
|
-
|
|
119
|
-
**Consequence**: A permanent ban from any sort of public interaction within
|
|
120
|
-
the community.
|
|
121
|
-
|
|
122
|
-
## Attribution
|
|
123
|
-
|
|
124
|
-
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
|
|
125
|
-
version 2.0, available at
|
|
126
|
-
https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
|
|
127
|
-
|
|
128
|
-
Community Impact Guidelines were inspired by [Mozilla's code of conduct
|
|
129
|
-
enforcement ladder](https://github.com/mozilla/diversity).
|
|
130
|
-
|
|
131
|
-
[homepage]: https://www.contributor-covenant.org
|
|
132
|
-
|
|
133
|
-
For answers to common questions about this code of conduct, see the FAQ at
|
|
134
|
-
https://www.contributor-covenant.org/faq. Translations are available at
|
|
135
|
-
https://www.contributor-covenant.org/translations.
|
|
136
|
-
|
|
137
|
-
## Special Considerations for zca-js
|
|
138
|
-
|
|
139
|
-
Given that zca-js is an unofficial API library for Zalo, we have additional
|
|
140
|
-
guidelines specific to our project:
|
|
141
|
-
|
|
142
|
-
### Responsible Usage
|
|
143
|
-
|
|
144
|
-
* **Respect Zalo's Terms of Service**: While this is an unofficial library,
|
|
145
|
-
users should be aware of and respect Zalo's terms of service
|
|
146
|
-
* **Account Safety**: Do not encourage or provide guidance on circumventing
|
|
147
|
-
Zalo's security measures
|
|
148
|
-
* **Privacy**: Respect user privacy and do not share personal information
|
|
149
|
-
obtained through the API
|
|
150
|
-
* **Rate Limiting**: Encourage responsible usage that doesn't overload Zalo's
|
|
151
|
-
servers
|
|
152
|
-
|
|
153
|
-
### Technical Discussions
|
|
154
|
-
|
|
155
|
-
* **Security**: When discussing security-related topics, use appropriate
|
|
156
|
-
channels and follow responsible disclosure practices
|
|
157
|
-
* **Bugs and Issues**: Report bugs and issues through proper channels
|
|
158
|
-
* **Documentation**: Help improve documentation and examples for the community
|
|
159
|
-
|
|
160
|
-
---
|
|
161
|
-
|
|
162
|
-
**Note**: This Code of Conduct is a living document and may be updated as our
|
|
163
|
-
community grows and evolves.
|
package/CONTRIBUTING.md
DELETED
|
@@ -1,470 +0,0 @@
|
|
|
1
|
-
# Contributing to zca-js
|
|
2
|
-
|
|
3
|
-
Thank you for your interest in contributing to zca-js! This project is maintained by the community and we welcome all contributions.
|
|
4
|
-
|
|
5
|
-
## Table of Contents
|
|
6
|
-
|
|
7
|
-
- [Code of Conduct](#code-of-conduct)
|
|
8
|
-
- [Getting Started](#getting-started)
|
|
9
|
-
- [Development Setup](#development-setup)
|
|
10
|
-
- [How to Contribute](#how-to-contribute)
|
|
11
|
-
- [Pull Request Process](#pull-request-process)
|
|
12
|
-
- [Code Style Guidelines](#code-style-guidelines)
|
|
13
|
-
- [Testing Guidelines](#testing-guidelines)
|
|
14
|
-
- [Documentation Guidelines](#documentation-guidelines)
|
|
15
|
-
- [Security Guidelines](#security-guidelines)
|
|
16
|
-
- [Release Process](#release-process)
|
|
17
|
-
- [Getting Help](#getting-help)
|
|
18
|
-
|
|
19
|
-
## Code of Conduct
|
|
20
|
-
|
|
21
|
-
This project adheres to our [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you agree to abide by these rules.
|
|
22
|
-
|
|
23
|
-
## Getting Started
|
|
24
|
-
|
|
25
|
-
### Prerequisites
|
|
26
|
-
|
|
27
|
-
- Node.js >= 18.0.0
|
|
28
|
-
- Bun (recommended) or npm
|
|
29
|
-
- Git
|
|
30
|
-
|
|
31
|
-
### Fork and Clone
|
|
32
|
-
|
|
33
|
-
1. Fork this repository
|
|
34
|
-
2. Clone your fork:
|
|
35
|
-
```bash
|
|
36
|
-
git clone https://github.com/YOUR_USERNAME/zca-js.git
|
|
37
|
-
cd zca-js
|
|
38
|
-
```
|
|
39
|
-
3. Add upstream remote:
|
|
40
|
-
```bash
|
|
41
|
-
git remote add upstream https://github.com/RFS-ADRENO/zca-js.git
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
## Development Setup
|
|
45
|
-
|
|
46
|
-
### Install Dependencies
|
|
47
|
-
|
|
48
|
-
```bash
|
|
49
|
-
# Using Bun (recommended)
|
|
50
|
-
bun install
|
|
51
|
-
|
|
52
|
-
# Or using npm
|
|
53
|
-
npm install
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
### Build Project
|
|
57
|
-
|
|
58
|
-
```bash
|
|
59
|
-
# Build both ESM and CJS
|
|
60
|
-
bun run build
|
|
61
|
-
|
|
62
|
-
# Build ESM only
|
|
63
|
-
bun run build:esm
|
|
64
|
-
|
|
65
|
-
# Build CJS only
|
|
66
|
-
bun run build:cjs
|
|
67
|
-
```
|
|
68
|
-
|
|
69
|
-
### Run Tests
|
|
70
|
-
|
|
71
|
-
```bash
|
|
72
|
-
# Run feature tests
|
|
73
|
-
bun run test:feat
|
|
74
|
-
|
|
75
|
-
# Run specific test file
|
|
76
|
-
bun run test/test.ts
|
|
77
|
-
```
|
|
78
|
-
|
|
79
|
-
### Code Formatting
|
|
80
|
-
|
|
81
|
-
```bash
|
|
82
|
-
# Format code with Prettier
|
|
83
|
-
bun run prettier
|
|
84
|
-
```
|
|
85
|
-
|
|
86
|
-
## How to Contribute
|
|
87
|
-
|
|
88
|
-
### Types of Contributions
|
|
89
|
-
|
|
90
|
-
We welcome the following types of contributions:
|
|
91
|
-
|
|
92
|
-
- 🐛 **Bug Reports**: Report bugs and issues
|
|
93
|
-
- ✨ **Feature Requests**: Suggest new features
|
|
94
|
-
- 🔧 **Code Contributions**: Fix bugs and add features
|
|
95
|
-
- 📚 **Documentation**: Improve docs and examples
|
|
96
|
-
- 🧪 **Tests**: Add or improve tests
|
|
97
|
-
- 🔒 **Security**: Report security vulnerabilities
|
|
98
|
-
- 🌐 **Translations**: Translate docs to other languages
|
|
99
|
-
|
|
100
|
-
### Before You Start
|
|
101
|
-
|
|
102
|
-
1. **Check existing issues**: Search for existing issues before creating new ones
|
|
103
|
-
2. **Discuss major changes**: Create an issue to discuss major changes
|
|
104
|
-
3. **Follow the roadmap**: Check the current roadmap and priorities
|
|
105
|
-
|
|
106
|
-
## Pull Request Process
|
|
107
|
-
|
|
108
|
-
### Creating a Pull Request
|
|
109
|
-
|
|
110
|
-
1. **Create a feature branch**:
|
|
111
|
-
```bash
|
|
112
|
-
git checkout -b feature/your-feature-name
|
|
113
|
-
# or
|
|
114
|
-
git checkout -b fix/your-bug-fix
|
|
115
|
-
```
|
|
116
|
-
|
|
117
|
-
2. **Make your changes**:
|
|
118
|
-
- Follow code style guidelines
|
|
119
|
-
- Add tests for new functionality
|
|
120
|
-
- Update documentation if needed
|
|
121
|
-
|
|
122
|
-
3. **Test your changes**:
|
|
123
|
-
```bash
|
|
124
|
-
bun run build
|
|
125
|
-
bun run test:feat
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
4. **Commit your changes**:
|
|
129
|
-
```bash
|
|
130
|
-
git add .
|
|
131
|
-
git commit -m "feat: add new API method for group management"
|
|
132
|
-
```
|
|
133
|
-
|
|
134
|
-
5. **Push to your fork**:
|
|
135
|
-
```bash
|
|
136
|
-
git push origin feature/your-feature-name
|
|
137
|
-
```
|
|
138
|
-
|
|
139
|
-
6. **Create a Pull Request**:
|
|
140
|
-
- Use the provided PR template
|
|
141
|
-
- Link related issues
|
|
142
|
-
- Provide clear description of changes
|
|
143
|
-
|
|
144
|
-
### PR Review Process
|
|
145
|
-
|
|
146
|
-
1. **Automated checks** must pass
|
|
147
|
-
2. **Code review** by at least one maintainer
|
|
148
|
-
3. **Security review** for security-related changes
|
|
149
|
-
4. **Documentation review** for API changes
|
|
150
|
-
5. **Final approval** before merge
|
|
151
|
-
|
|
152
|
-
## Code Style Guidelines
|
|
153
|
-
|
|
154
|
-
### TypeScript Guidelines
|
|
155
|
-
|
|
156
|
-
- Use TypeScript strict mode
|
|
157
|
-
- Prefer interfaces over types for object shapes
|
|
158
|
-
- Use meaningful variable and function names
|
|
159
|
-
- Add JSDoc comments for public APIs
|
|
160
|
-
- Use async/await over Promises when possible
|
|
161
|
-
|
|
162
|
-
### Code Organization
|
|
163
|
-
|
|
164
|
-
The project follows a modular structure for better maintainability and organization:
|
|
165
|
-
|
|
166
|
-
```
|
|
167
|
-
zca-js/
|
|
168
|
-
├── src/ # Source code directory
|
|
169
|
-
│ ├── apis/ # API methods (100+ files)
|
|
170
|
-
│ │ ├── sendMessage.ts # Core messaging functionality
|
|
171
|
-
│ │ ├── login.ts # Authentication methods
|
|
172
|
-
│ │ ├── loginQR.ts # QR code login
|
|
173
|
-
│ │ ├── listen.ts # Event listening
|
|
174
|
-
│ │ ├── sendVideo.ts # Video sending
|
|
175
|
-
│ │ ├── sendVoice.ts # Voice sending
|
|
176
|
-
│ │ ├── sendSticker.ts # Sticker sending
|
|
177
|
-
│ │ ├── createGroup.ts # Group management
|
|
178
|
-
│ │ ├── addReaction.ts # Message reactions
|
|
179
|
-
│ │ ├── uploadAttachment.ts # File uploads
|
|
180
|
-
│ │ └── ... # 90+ other API methods
|
|
181
|
-
│ ├── models/ # TypeScript interfaces and types
|
|
182
|
-
│ │ ├── Message.ts # Message interface
|
|
183
|
-
│ │ ├── Attachment.ts # File attachment types
|
|
184
|
-
│ │ ├── Reaction.ts # Reaction types
|
|
185
|
-
│ │ ├── FriendEvent.ts # Friend event types
|
|
186
|
-
│ │ ├── GroupEvent.ts # Group event types
|
|
187
|
-
│ │ ├── Typing.ts # Typing indicators
|
|
188
|
-
│ │ ├── SeenMessage.ts # Message seen events
|
|
189
|
-
│ │ ├── DeliveredMessage.ts # Message delivery events
|
|
190
|
-
│ │ ├── Undo.ts # Undo functionality
|
|
191
|
-
│ │ ├── Enum.ts # Enumerations
|
|
192
|
-
│ │ └── index.ts # Model exports
|
|
193
|
-
│ ├── Errors/ # Error handling
|
|
194
|
-
│ │ ├── ZaloApiError.ts # Custom API error class
|
|
195
|
-
│ │ └── index.ts # Error exports
|
|
196
|
-
│ ├── context.ts # Context management and state
|
|
197
|
-
│ ├── utils.ts # Utility functions and helpers
|
|
198
|
-
│ ├── zalo.ts # Main Zalo class implementation
|
|
199
|
-
│ ├── update.ts # Update checking functionality
|
|
200
|
-
│ └── index.ts # Public API exports
|
|
201
|
-
├── examples/ # Usage examples
|
|
202
|
-
│ └── echobot.ts # Echo bot example
|
|
203
|
-
├── test/ # Test files
|
|
204
|
-
│ ├── feat.ts # Feature tests
|
|
205
|
-
│ ├── feat.test.ts # Feature test suite
|
|
206
|
-
│ ├── test.ts # General tests
|
|
207
|
-
│ └── a.png # Test assets
|
|
208
|
-
├── .github/ # GitHub configuration
|
|
209
|
-
│ └── ISSUE_TEMPLATE/ # Issue templates
|
|
210
|
-
├── .dev/ # Development tools (developer generated)
|
|
211
|
-
├── dist/ # Build output (generated)
|
|
212
|
-
├── node_modules/ # Dependencies (generated)
|
|
213
|
-
├── package.json # Project configuration
|
|
214
|
-
├── tsconfig.json # TypeScript configuration
|
|
215
|
-
├── rollup.config.js # Build configuration
|
|
216
|
-
├── README.md # Project documentation
|
|
217
|
-
├── CONTRIBUTING.md # Contribution guidelines
|
|
218
|
-
├── SECURITY.md # Security policy
|
|
219
|
-
├── CODE_OF_CONDUCT.md # Community guidelines
|
|
220
|
-
└── LICENSE # MIT License
|
|
221
|
-
```
|
|
222
|
-
|
|
223
|
-
### Key Directories Explained
|
|
224
|
-
|
|
225
|
-
- **`src/apis/`**: Contains all API method implementations (~100 files)
|
|
226
|
-
|
|
227
|
-
- **`src/models/`**: TypeScript interfaces and type definitions
|
|
228
|
-
- Core data structures for messages, events, and API responses
|
|
229
|
-
- Ensures type safety across the application
|
|
230
|
-
|
|
231
|
-
- **`src/Errors/`**: Custom error handling
|
|
232
|
-
- `ZaloApiError.ts`: Handles API-specific errors
|
|
233
|
-
- Provides consistent error handling across the library
|
|
234
|
-
|
|
235
|
-
- **`examples/`**: Usage examples and demonstrations
|
|
236
|
-
- `echobot.ts`: Complete example of a Zalo bot implementation
|
|
237
|
-
|
|
238
|
-
- **`test/`**: Test suites and test assets
|
|
239
|
-
- Feature tests for core functionality
|
|
240
|
-
- Integration tests for API methods
|
|
241
|
-
|
|
242
|
-
### Naming Conventions
|
|
243
|
-
|
|
244
|
-
- **Files**: camelCase (e.g., `sendMessage.ts`)
|
|
245
|
-
- **Classes**: PascalCase (e.g., `ZaloApiError`)
|
|
246
|
-
- **Functions**: camelCase (e.g., `sendMessage`)
|
|
247
|
-
- **Constants**: UPPER_SNAKE_CASE (e.g., `API_BASE_URL`)
|
|
248
|
-
- **Interfaces**: PascalCase with `I` prefix (e.g., `IMessage`)
|
|
249
|
-
|
|
250
|
-
### Error Handling
|
|
251
|
-
|
|
252
|
-
```typescript
|
|
253
|
-
// Good
|
|
254
|
-
try {
|
|
255
|
-
const result = await api.sendMessage(message);
|
|
256
|
-
return result;
|
|
257
|
-
} catch (error) {
|
|
258
|
-
if (error instanceof ZaloApiError) {
|
|
259
|
-
throw error;
|
|
260
|
-
}
|
|
261
|
-
throw new ZaloApiError(`Failed to send message: ${error.message}`);
|
|
262
|
-
}
|
|
263
|
-
|
|
264
|
-
// Bad
|
|
265
|
-
try {
|
|
266
|
-
const result = await api.sendMessage(message);
|
|
267
|
-
return result;
|
|
268
|
-
} catch (error) {
|
|
269
|
-
console.error(error);
|
|
270
|
-
return null;
|
|
271
|
-
}
|
|
272
|
-
```
|
|
273
|
-
|
|
274
|
-
## Testing Guidelines
|
|
275
|
-
|
|
276
|
-
### Test Structure
|
|
277
|
-
|
|
278
|
-
```typescript
|
|
279
|
-
describe('API Method', () => {
|
|
280
|
-
beforeEach(() => {
|
|
281
|
-
// Setup
|
|
282
|
-
});
|
|
283
|
-
|
|
284
|
-
afterEach(() => {
|
|
285
|
-
// Cleanup
|
|
286
|
-
});
|
|
287
|
-
|
|
288
|
-
it('should handle success case', async () => {
|
|
289
|
-
// Test implementation
|
|
290
|
-
});
|
|
291
|
-
|
|
292
|
-
it('should handle error case', async () => {
|
|
293
|
-
// Test error handling
|
|
294
|
-
});
|
|
295
|
-
});
|
|
296
|
-
```
|
|
297
|
-
|
|
298
|
-
### Testing Best Practices
|
|
299
|
-
|
|
300
|
-
- Test both success and failure scenarios
|
|
301
|
-
- Mock external dependencies
|
|
302
|
-
- Use descriptive test names
|
|
303
|
-
- Keep tests independent
|
|
304
|
-
- Test edge cases and error conditions
|
|
305
|
-
|
|
306
|
-
### Running Tests
|
|
307
|
-
|
|
308
|
-
```bash
|
|
309
|
-
# Run all tests
|
|
310
|
-
bun run test:feat
|
|
311
|
-
|
|
312
|
-
# Run specific test
|
|
313
|
-
bun run test/test.ts
|
|
314
|
-
|
|
315
|
-
# Run with coverage (if available)
|
|
316
|
-
bun run test:coverage
|
|
317
|
-
```
|
|
318
|
-
|
|
319
|
-
## Documentation Guidelines
|
|
320
|
-
|
|
321
|
-
### API Documentation
|
|
322
|
-
|
|
323
|
-
- Document all public methods with JSDoc
|
|
324
|
-
- Include parameter types and descriptions
|
|
325
|
-
- Provide usage examples
|
|
326
|
-
- Document error conditions
|
|
327
|
-
|
|
328
|
-
```typescript
|
|
329
|
-
/**
|
|
330
|
-
* Sends a message to a specific thread
|
|
331
|
-
* @param message - The message object containing content and metadata
|
|
332
|
-
* @param threadId - The ID of the thread to send the message to
|
|
333
|
-
* @param threadType - The type of thread (User or Group)
|
|
334
|
-
* @returns Promise<Message> - The sent message object
|
|
335
|
-
* @throws {ZaloApiError} When the API request fails
|
|
336
|
-
* @example
|
|
337
|
-
* ```typescript
|
|
338
|
-
* const message = await api.sendMessage(
|
|
339
|
-
* { msg: "Hello, world!" },
|
|
340
|
-
* "123456789",
|
|
341
|
-
* ThreadType.User
|
|
342
|
-
* );
|
|
343
|
-
* ```
|
|
344
|
-
*/
|
|
345
|
-
async sendMessage(message: IMessage, threadId: string, threadType: ThreadType): Promise<Message>
|
|
346
|
-
```
|
|
347
|
-
|
|
348
|
-
### README Updates
|
|
349
|
-
|
|
350
|
-
- Update README.md for new features
|
|
351
|
-
- Add examples for new APIs
|
|
352
|
-
- Update installation instructions if needed
|
|
353
|
-
- Keep the table of contents updated
|
|
354
|
-
|
|
355
|
-
## Security Guidelines
|
|
356
|
-
|
|
357
|
-
### Security Best Practices
|
|
358
|
-
|
|
359
|
-
- Never commit sensitive data (tokens, passwords, etc.)
|
|
360
|
-
- Use environment variables for configuration
|
|
361
|
-
- Validate all user inputs
|
|
362
|
-
- Follow the principle of least privilege
|
|
363
|
-
- Report security issues privately
|
|
364
|
-
|
|
365
|
-
### Security Reporting
|
|
366
|
-
|
|
367
|
-
If you discover a security vulnerability:
|
|
368
|
-
|
|
369
|
-
1. **DO NOT** create a public issue
|
|
370
|
-
2. Use the [SECURITY.md](SECURITY.md) reporting process
|
|
371
|
-
3. Create a private issue with `[SECURITY]` label
|
|
372
|
-
4. Contact team members directly for urgent issues
|
|
373
|
-
|
|
374
|
-
### Code Security
|
|
375
|
-
|
|
376
|
-
```typescript
|
|
377
|
-
// Good - Validate inputs
|
|
378
|
-
function sendMessage(content: string, threadId: string) {
|
|
379
|
-
if (!content || typeof content !== 'string') {
|
|
380
|
-
throw new ZaloApiError('Content must be a non-empty string');
|
|
381
|
-
}
|
|
382
|
-
if (!threadId || typeof threadId !== 'string') {
|
|
383
|
-
throw new ZaloApiError('ThreadId must be a non-empty string');
|
|
384
|
-
}
|
|
385
|
-
// Implementation
|
|
386
|
-
}
|
|
387
|
-
|
|
388
|
-
// Bad - No validation
|
|
389
|
-
function sendMessage(content: any, threadId: any) {
|
|
390
|
-
// Implementation without validation
|
|
391
|
-
}
|
|
392
|
-
```
|
|
393
|
-
|
|
394
|
-
## Release Process
|
|
395
|
-
|
|
396
|
-
### Versioning
|
|
397
|
-
|
|
398
|
-
We follow [Semantic Versioning](https://semver.org/):
|
|
399
|
-
|
|
400
|
-
- **MAJOR**: Breaking changes
|
|
401
|
-
- **MINOR**: New features (backward compatible)
|
|
402
|
-
- **PATCH**: Bug fixes (backward compatible)
|
|
403
|
-
|
|
404
|
-
### Release Checklist
|
|
405
|
-
|
|
406
|
-
- [ ] All tests pass
|
|
407
|
-
- [ ] Documentation is updated
|
|
408
|
-
- [ ] Version is bumped in package.json
|
|
409
|
-
- [ ] Build is successful
|
|
410
|
-
- [ ] Release notes are prepared
|
|
411
|
-
|
|
412
|
-
### Publishing
|
|
413
|
-
|
|
414
|
-
```bash
|
|
415
|
-
# Build the project
|
|
416
|
-
bun run build
|
|
417
|
-
|
|
418
|
-
# Run tests
|
|
419
|
-
bun run test:feat
|
|
420
|
-
|
|
421
|
-
# Publish to npm
|
|
422
|
-
npm publish
|
|
423
|
-
```
|
|
424
|
-
|
|
425
|
-
## Getting Help
|
|
426
|
-
|
|
427
|
-
### Communication Channels
|
|
428
|
-
|
|
429
|
-
- **GitHub Issues**: For bug reports and feature requests
|
|
430
|
-
- **GitHub Discussions**: For questions and general discussion
|
|
431
|
-
- **Pull Requests**: For code contributions
|
|
432
|
-
- **Security Issues**: Use `[SECURITY]` label
|
|
433
|
-
|
|
434
|
-
### Team Members
|
|
435
|
-
|
|
436
|
-
- [@RFS-ADRENO](https://github.com/RFS-ADRENO)
|
|
437
|
-
- [@truong9c2208](https://github.com/truong9c2208)
|
|
438
|
-
- [@JustKemForFun](https://github.com/JustKemForFun)
|
|
439
|
-
|
|
440
|
-
### Resources
|
|
441
|
-
|
|
442
|
-
- [API Documentation](https://zca-js.tdung.com)
|
|
443
|
-
- [Examples](examples/)
|
|
444
|
-
- [Security Policy](SECURITY.md)
|
|
445
|
-
- [Code of Conduct](CODE_OF_CONDUCT.md)
|
|
446
|
-
|
|
447
|
-
## Special Considerations for zca-js
|
|
448
|
-
|
|
449
|
-
### Unofficial API Library
|
|
450
|
-
|
|
451
|
-
> [!IMPORTANT]
|
|
452
|
-
> ⚠️ zca-js is an unofficial API library for Zalo. Please be aware of:
|
|
453
|
-
|
|
454
|
-
- **Account Risk**: Using this API may result in account suspension
|
|
455
|
-
- **Terms of Service**: Respect Zalo's ToS in your contributions
|
|
456
|
-
- **Rate Limiting**: Be mindful of API usage limits
|
|
457
|
-
- **Privacy**: Protect user privacy and data
|
|
458
|
-
|
|
459
|
-
### Responsible Development
|
|
460
|
-
|
|
461
|
-
- Test changes thoroughly before submitting
|
|
462
|
-
- Avoid introducing features that could harm users
|
|
463
|
-
- Consider the impact on Zalo's infrastructure
|
|
464
|
-
- Document any risks or limitations
|
|
465
|
-
|
|
466
|
-
---
|
|
467
|
-
|
|
468
|
-
**Thank you for contributing to zca-js!** 🚀
|
|
469
|
-
|
|
470
|
-
Your contributions help make this library better for the entire community.
|
package/SECURITY.md
DELETED
|
@@ -1,83 +0,0 @@
|
|
|
1
|
-
# Security Policy
|
|
2
|
-
|
|
3
|
-
## Supported Versions
|
|
4
|
-
|
|
5
|
-
We actively maintain and provide security updates for the following versions:
|
|
6
|
-
|
|
7
|
-
| Version | Supported |
|
|
8
|
-
| ------- | ------------------ |
|
|
9
|
-
| 2.0.x | :white_check_mark: |
|
|
10
|
-
| 1.x.x | :x: |
|
|
11
|
-
| < 1.0 | :x: |
|
|
12
|
-
|
|
13
|
-
## Reporting a Vulnerability
|
|
14
|
-
|
|
15
|
-
We take security vulnerabilities seriously. If you discover a security vulnerability in zca-js, please follow these steps:
|
|
16
|
-
|
|
17
|
-
### 1. **DO NOT** create a public GitHub issue
|
|
18
|
-
Security vulnerabilities should be reported privately to prevent potential exploitation.
|
|
19
|
-
|
|
20
|
-
### 2. Report the vulnerability
|
|
21
|
-
Send an email to the maintainers with the following information:
|
|
22
|
-
- **Subject**: `[SECURITY] zca-js vulnerability report`
|
|
23
|
-
- **Description**: Detailed description of the vulnerability
|
|
24
|
-
- **Steps to reproduce**: Clear steps to reproduce the issue
|
|
25
|
-
- **Impact assessment**: Potential impact of the vulnerability
|
|
26
|
-
- **Suggested fix** (if available): Any suggestions for fixing the issue
|
|
27
|
-
|
|
28
|
-
### 3. Response timeline
|
|
29
|
-
- **Initial response**: Within 48 hours
|
|
30
|
-
- **Status update**: Within 1 week
|
|
31
|
-
- **Resolution**: As soon as possible, typically within 30 days
|
|
32
|
-
|
|
33
|
-
## Security Considerations
|
|
34
|
-
|
|
35
|
-
### Important Warnings
|
|
36
|
-
|
|
37
|
-
⚠️ **This is an unofficial API library** that simulates browser interactions with Zalo Web. Please be aware of the following security considerations:
|
|
38
|
-
|
|
39
|
-
1. **Account Risk**: Using this API may result in your Zalo account being locked or banned. Use at your own risk.
|
|
40
|
-
|
|
41
|
-
2. **Authentication**: The library handles sensitive authentication data. Ensure proper security measures when storing or transmitting this information.
|
|
42
|
-
|
|
43
|
-
3. **Rate Limiting**: Respect Zalo's rate limits to avoid triggering security measures.
|
|
44
|
-
|
|
45
|
-
4. **Data Privacy**: Be mindful of user privacy and comply with relevant data protection regulations.
|
|
46
|
-
|
|
47
|
-
### Best Practices
|
|
48
|
-
|
|
49
|
-
1. **Environment Variables**: Store sensitive configuration in environment variables, not in code
|
|
50
|
-
2. **HTTPS Only**: Always use HTTPS when transmitting data
|
|
51
|
-
3. **Input Validation**: Validate all inputs before processing
|
|
52
|
-
4. **Error Handling**: Implement proper error handling to avoid information disclosure
|
|
53
|
-
5. **Regular Updates**: Keep the library updated to the latest version
|
|
54
|
-
|
|
55
|
-
### Known Limitations
|
|
56
|
-
|
|
57
|
-
- This library is not officially supported by Zalo
|
|
58
|
-
- API endpoints and behavior may change without notice
|
|
59
|
-
- No guarantee of service availability or stability
|
|
60
|
-
- May break with Zalo Web updates
|
|
61
|
-
|
|
62
|
-
## Security Updates
|
|
63
|
-
|
|
64
|
-
Security updates will be released as patch versions (e.g., 2.0.1, 2.0.2) and will be clearly marked in the changelog.
|
|
65
|
-
|
|
66
|
-
## Contact Information
|
|
67
|
-
|
|
68
|
-
For security-related issues, please contact:
|
|
69
|
-
- **GitHub Issues**: Create a private issue with the `[SECURITY]` label
|
|
70
|
-
- **GitHub Discussions**: Use the "Security" category for general security questions
|
|
71
|
-
- **Team Members**:
|
|
72
|
-
- [@RFS-ADRENO](https://github.com/RFS-ADRENO)
|
|
73
|
-
- [@truong9c2208](https://github.com/truong9c2208)
|
|
74
|
-
- [@JustKemForFun](https://github.com/JustKemForFun)
|
|
75
|
-
- **Alternative**: Contact any team member through GitHub for urgent security matters
|
|
76
|
-
|
|
77
|
-
## Acknowledgments
|
|
78
|
-
|
|
79
|
-
We appreciate security researchers and community members who responsibly disclose vulnerabilities. Contributors will be acknowledged in our security advisories unless they prefer to remain anonymous.
|
|
80
|
-
|
|
81
|
-
---
|
|
82
|
-
|
|
83
|
-
**Note**: This security policy is subject to change. Please check back regularly for updates.
|