@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 CHANGED
@@ -1,54 +1,72 @@
1
- # ZCA-JS (Forked Version)
1
+ # @softtynet/zca-js — Softtynet Zalo API SDK for Node.js & Bun
2
2
 
3
- > [!NOTE]
4
- > **This is a forked version of the original [zca-js](https://github.com/RFS-ADRENO/zca-js) project by RFS-ADRENO.** This package (`@softtynet/zca-js`) is maintained separately for quick hotfixes.
5
- >
6
- > This is an unofficial Zalo API for personal account. It work by simulating the browser to interact with Zalo Web.
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
- > Using this API could get your account locked or banned. We are not responsible for any issues that may happen. Use it at your own risk.
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
- ## Table of Contents
14
-
15
- - [Installation](#installation)
16
- - [Migrate to V2](#migrate-to-v2)
17
- - [Documentation](#documentation)
18
- - [Basic Usages](#basic-usages)
19
- - [Login](#login)
20
- - [Listen for new messages](#listen-for-new-messages)
21
- - [Synchronize Messages from Mobile](#synchronize-messages-from-mobile)
22
- - [Send a message](#send-a-message)
23
- - [Get/Send a sticker](#getsend-a-sticker)
24
- - [Example](#example)
25
- - [Projects & Useful Resources](#projects--useful-resources)
26
- - [Contributing](#contributing)
27
- - [License](#license)
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
- bun add zca-js # or npm install zca-js
51
+ npm install @softtynet/zca-js
52
+ # hoặc dùng Bun
53
+ bun add @softtynet/zca-js
34
54
  ```
35
55
 
36
- ### Migrate to V2
56
+ ### Cấu hình `imageMetadataGetter` (Khi gửi ảnh từ đường dẫn file)
37
57
 
38
- Since official version 2.0.0, `zca-js` has removed sharp dependency for image metadata extraction. It now requires users to provide their own `imageMetadataGetter` function when initializing the `Zalo` class if they want to send images/gifs by file path.
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
- bun add sharp # or npm install sharp
61
+ npm install sharp
44
62
  ```
45
63
 
46
- ```javascript
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
- ## Documentation
84
+ ## 📚 Tài liệu chuyên sâu
69
85
 
70
- - [API Documentation](https://zca-js.tdung.com)
71
- - [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)
72
- - [Kế hoạch & Hướng dẫn Dịch ngược Zalo bằng REA (`morluto/rea`)](docs/REA_REVERSE_ENGINEERING_PLAN.md)
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
- ## Basic Usages
92
+ ## ⚡ Hướng dẫn sử dụng nhanh
77
93
 
78
- ### Login
94
+ ### 1. Đăng nhập & Lưu phiên
79
95
 
80
- ```javascript
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
- ### Listen for new messages
104
+ ### 2. Lắng nghe tin nhắn thời gian thực
88
105
 
89
- ```javascript
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
- switch (message.type) {
99
- case ThreadType.User: {
100
- if (isPlainText) {
101
- // received plain text direct message
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
- > Only one web listener can run per account at a time. If you open Zalo in the browser while the listener is active, the listener will be automatically stopped.
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
- ### Synchronize Messages & Offline Catch-up
129
+ ### 3. Đồng bộ bù tin nhắn khi Offline (Catch-up Sync)
121
130
 
122
- `zca-js` supports both **offline message catch-up** (when reconnecting or restarting your app) and **full mobile backup synchronization** (`ZDB4.0`) from the Zalo mobile app:
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} latest messages`);
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(`Received ${messages.length} queued offline messages (type=${type}, hasMore=${hasMore})`);
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
- #### 2. Trigger Mobile Backup Sync (`pull_mobile_msg`)
144
- ```javascript
145
- import { SyncEventType, decryptWithPrivateKey, deriveZdbAesKey, decryptZdbBuffer } from "zca-js";
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("User confirmed sync on phone, waiting for backup upload...");
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
- console.log("Downloaded backup:", res.data.file_path, "AES key length:", aesKey.length);
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("connected", async () => {
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("Please tap 'Sync now' on your phone!");
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
- ### Voice / Video Call Signaling
192
+ ### 5. Khởi tạo Cuộc gọi Thoại & Gọi Video
172
193
 
173
- ```javascript
174
- import { CallType } from "zca-js";
194
+ ```ts
195
+ import { CallType } from "@softtynet/zca-js";
175
196
 
176
- // Ring a user's phone (Audio or Video call)
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
- ### Send a message
185
-
186
- ```javascript
187
- import { Zalo, ThreadType } from "zca-js";
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
- // Echo bot
193
- api.listener.on("message", (message) => {
194
- const isPlainText = typeof message.data.content === "string";
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
- api.listener.start();
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
- ### Get/Send a sticker
227
-
228
- ```javascript
229
- api.getStickers("hello").then(async (stickerIds) => {
230
- // Get the first sticker
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
- stickerObject,
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
- ## Example
243
-
244
- See [examples](examples) folder for more details.
245
-
246
- ---
240
+ ## 🧪 Kiểm định & Chạy thử nghiệm
247
241
 
248
- ## Projects & Useful Resources
242
+ Dự án đi kèm bộ kiểm định 2 lớp trong thư mục [`test/`](test):
249
243
 
250
- <div align="center">
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
- | Repository | Description |
253
- | :--- | :--- |
254
- | [**ZaloDataExtractor**](https://github.com/JustKemForFun/ZaloDataExtractor) | A browser `Extension` to extract IMEI, cookies, and user agent from Zalo Web. |
255
- | [**MultiZlogin**](https://github.com/ChickenAI/multizlogin) | A multi-account Zalo management system that lets you log in to and manage multiple accounts simultaneously, with proxy and webhook integration. |
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
- </div>
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
- ## Contributing
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
- For more information, please read our [Code of Conduct](CODE_OF_CONDUCT.md) and [Security Policy](SECURITY.md) before participating.
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
- ## License
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
- This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
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
- ## **Support Us**
272
+ ## 📄 Giấy phép (License)
286
273
 
287
- - ⭐ **Star our repositories** if you find them useful!
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).
@@ -3,10 +3,10 @@
3
3
  var semver = require('semver');
4
4
  var utils = require('./utils.cjs');
5
5
 
6
- const VERSION = "2.2.0";
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.0";
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.7",
4
- "description": "Unofficial Zalo API for JavaScript",
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/RFS-ADRENO/zca-js.git"
29
+ "url": "git+https://github.com/softtyos/zca-js.git"
31
30
  },
32
- "homepage": "https://github.com/RFS-ADRENO/zca-js",
31
+ "homepage": "https://github.com/softtyos/zca-js",
33
32
  "bugs": {
34
- "url": "https://github.com/RFS-ADRENO/zca-js/issues"
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, truong9c2208, JustKemForFun",
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",
@@ -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.