@trungdlp/zca-js 1.0.0

package/README.md

@@ -0,0 +1,225 @@
+# ZCA-JS
+
+> [!NOTE]
+> This is an unofficial Zalo API for personal account. It work by simulating the browser to interact with Zalo Web.
+
+> [!WARNING]
+> 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.
+
+---
+
+## Table of Contents
+
+-   [Installation](#installation)
+    - [Migrate to V2](#migrate-to-v2)
+-   [Documentation](#documentation)
+-   [Basic Usages](#basic-usages)
+    -   [Login](#login)
+    -   [Listen for new messages](#listen-for-new-messages)
+    -   [Send a message](#send-a-message)
+    -   [Get/Send a sticker](#getsend-a-sticker)
+-   [Example](#example)
+-   [Projects & Useful Resources](#projects--useful-resources)
+-   [Contributing](#contributing)
+-   [License](#license)
+-   [Support Us](#support-us)
+
+## Installation
+
+```bash
+bun add zca-js # or npm install zca-js
+```
+
+### Migrate to V2
+
+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.
+
+Example of custom `imageMetadataGetter` using `sharp`:
+
+```bash
+bun add sharp # or npm install sharp
+```
+
+```javascript
+import { Zalo } from "zca-js";
+import sharp from "sharp";
+import fs from "node:fs";
+
+async function imageMetadataGetter(filePath) {
+    const data = await fs.promises.readFile(filePath);
+    const metadata = await sharp(data).metadata();
+    return {
+        height: metadata.height,
+        width: metadata.width,
+        size: metadata.size || data.length,
+    };
+}
+
+const zalo = new Zalo({
+    imageMetadataGetter,
+});
+```
+
+---
+
+## Documentation
+
+See [API Documentation](https://zca-js.tdung.com) for more details.
+
+---
+
+## Basic Usages
+
+### Login
+
+```javascript
+import { Zalo } from "zca-js";
+
+const zalo = new Zalo();
+const api = await zalo.loginQR();
+```
+
+### Listen for new messages
+
+```javascript
+import { Zalo, ThreadType } from "zca-js";
+
+const zalo = new Zalo();
+const api = await zalo.loginQR();
+
+api.listener.on("message", (message) => {
+    const isPlainText = typeof message.data.content === "string";
+
+    switch (message.type) {
+        case ThreadType.User: {
+            if (isPlainText) {
+                // received plain text direct message
+            }
+            break;
+        }
+        case ThreadType.Group: {
+            if (isPlainText) {
+                // received plain text group message
+            }
+            break;
+        }
+    }
+});
+
+api.listener.start();
+```
+
+> [!IMPORTANT]
+> 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.
+
+### Send a message
+
+```javascript
+import { Zalo, ThreadType } from "zca-js";
+
+const zalo = new Zalo();
+const api = await zalo.loginQR();
+
+// Echo bot
+api.listener.on("message", (message) => {
+    const isPlainText = typeof message.data.content === "string";
+    if (message.isSelf || !isPlainText) return;
+
+    switch (message.type) {
+        case ThreadType.User: {
+            api.sendMessage(
+                {
+                    msg: "echo: " + message.data.content,
+                    quote: message.data, // the message to reply to (optional)
+                },
+                message.threadId,
+                message.type, // ThreadType.User
+            );
+            break;
+        }
+        case ThreadType.Group: {
+            api.sendMessage(
+                {
+                    msg: "echo: " + message.data.content,
+                    quote: message.data, // the message to reply to (optional)
+                },
+                message.threadId,
+                message.type, // ThreadType.Group
+            );
+            break;
+        }
+    }
+});
+
+api.listener.start();
+```
+
+### Get/Send a sticker
+
+```javascript
+api.getStickers("hello").then(async (stickerIds) => {
+    // Get the first sticker
+    const stickerObject = await api.getStickersDetail(stickerIds[0]);
+    api.sendMessageSticker(
+        stickerObject,
+        message.threadId,
+        message.type, // ThreadType.User or ThreadType.Group
+    );
+});
+```
+
+---
+
+## Example
+
+See [examples](examples) folder for more details.
+
+---
+
+## Projects & Useful Resources
+
+<div align="center">
+
+| Repository | Description |
+|    :---    |    :---     |
+| [**ZaloDataExtractor**](https://github.com/JustKemForFun/ZaloDataExtractor) | A browser `Extension` to extract IMEI, cookies, and user agent from Zalo Web. |
+| [**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. |
+| [**n8n-nodes-zalo-tools**](https://github.com/ChickenAI/zalo-node) | N8N node for personal Zalo account. |
+| [**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. |
+| [**Zalo-F12-Tools**](https://github.com/JustKemForFun/Zalo-F12-Tools) | Toggle hidden modes for Zalo Web. |
+
+</div>
+
+---
+
+## Contributing
+
+We welcome contributions from the community! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details on how to:
+
+- 🐛 Report bugs and issues
+- ✨ Suggest new features
+- 🔧 Submit code contributions
+- 📚 Improve documentation
+- 🧪 Add or improve tests
+- 🔒 Report security vulnerabilities
+
+For more information, please read our [Code of Conduct](CODE_OF_CONDUCT.md) and [Security Policy](SECURITY.md) before participating.
+
+---
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+## **Support Us**
+
+- ⭐ **Star our repositories** if you find them useful!  
+- 🔄 **Share** with your network to help us grow  
+- 💡 **Contribute** your ideas and code    
+- ☕ **A coffee**:
+    - [Buy Me a Coffee](https://ko-fi.com/grosse)
+    - [Paypal](https://www.paypal.com/paypalme/dungto213)
+    - [VietQR](https://github.com/user-attachments/assets/e1f319d6-9d11-4082-8248-55b55e645caa)
+    - [Momo](https://me.momo.vn/gMIMulsaUqsbf6iAiXt3)

package/SECURITY.md

@@ -0,0 +1,83 @@
+# Security Policy
+
+## Supported Versions
+
+We actively maintain and provide security updates for the following versions:
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 2.0.x   | :white_check_mark: |
+| 1.x.x   | :x:                |
+| < 1.0   | :x:                |
+
+## Reporting a Vulnerability
+
+We take security vulnerabilities seriously. If you discover a security vulnerability in zca-js, please follow these steps:
+
+### 1. **DO NOT** create a public GitHub issue
+Security vulnerabilities should be reported privately to prevent potential exploitation.
+
+### 2. Report the vulnerability
+Send an email to the maintainers with the following information:
+- **Subject**: `[SECURITY] zca-js vulnerability report`
+- **Description**: Detailed description of the vulnerability
+- **Steps to reproduce**: Clear steps to reproduce the issue
+- **Impact assessment**: Potential impact of the vulnerability
+- **Suggested fix** (if available): Any suggestions for fixing the issue
+
+### 3. Response timeline
+- **Initial response**: Within 48 hours
+- **Status update**: Within 1 week
+- **Resolution**: As soon as possible, typically within 30 days
+
+## Security Considerations
+
+### Important Warnings
+
+⚠️ **This is an unofficial API library** that simulates browser interactions with Zalo Web. Please be aware of the following security considerations:
+
+1. **Account Risk**: Using this API may result in your Zalo account being locked or banned. Use at your own risk.
+
+2. **Authentication**: The library handles sensitive authentication data. Ensure proper security measures when storing or transmitting this information.
+
+3. **Rate Limiting**: Respect Zalo's rate limits to avoid triggering security measures.
+
+4. **Data Privacy**: Be mindful of user privacy and comply with relevant data protection regulations.
+
+### Best Practices
+
+1. **Environment Variables**: Store sensitive configuration in environment variables, not in code
+2. **HTTPS Only**: Always use HTTPS when transmitting data
+3. **Input Validation**: Validate all inputs before processing
+4. **Error Handling**: Implement proper error handling to avoid information disclosure
+5. **Regular Updates**: Keep the library updated to the latest version
+
+### Known Limitations
+
+- This library is not officially supported by Zalo
+- API endpoints and behavior may change without notice
+- No guarantee of service availability or stability
+- May break with Zalo Web updates
+
+## Security Updates
+
+Security updates will be released as patch versions (e.g., 2.0.1, 2.0.2) and will be clearly marked in the changelog.
+
+## Contact Information
+
+For security-related issues, please contact:
+- **GitHub Issues**: Create a private issue with the `[SECURITY]` label
+- **GitHub Discussions**: Use the "Security" category for general security questions
+- **Team Members**: 
+  - [@RFS-ADRENO](https://github.com/RFS-ADRENO)
+  - [@truong9c2208](https://github.com/truong9c2208)
+  - [@JustKemForFun](https://github.com/JustKemForFun)
+- **Alternative**: Contact any team member through GitHub for urgent security matters
+
+## Acknowledgments
+
+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.
+
+---
+
+**Note**: This security policy is subject to change. Please check back regularly for updates. 

package/dist/Errors/ZaloApiError.d.ts

@@ -0,0 +1,4 @@
+export declare class ZaloApiError extends Error {
+    code: number | null;
+    constructor(message: string, code?: number);
+}

package/dist/Errors/ZaloApiError.js

@@ -0,0 +1,7 @@
+export class ZaloApiError extends Error {
+    constructor(message, code) {
+        super(message);
+        this.name = "ZcaApiError";
+        this.code = code || null;
+    }
+}

package/dist/Errors/ZaloApiLoginQRAborted.d.ts

@@ -0,0 +1,4 @@
+import { ZaloApiError } from "./ZaloApiError.js";
+export declare class ZaloApiLoginQRAborted extends ZaloApiError {
+    constructor(message?: string);
+}

package/dist/Errors/ZaloApiLoginQRAborted.js

@@ -0,0 +1,7 @@
+import { ZaloApiError } from "./ZaloApiError.js";
+export class ZaloApiLoginQRAborted extends ZaloApiError {
+    constructor(message = "Operation aborted") {
+        super(message);
+        this.name = "ZaloApiLoginQRAborted";
+    }
+}

package/dist/Errors/ZaloApiLoginQRDeclined.d.ts

@@ -0,0 +1,4 @@
+import { ZaloApiError } from "./ZaloApiError.js";
+export declare class ZaloApiLoginQRDeclined extends ZaloApiError {
+    constructor(message?: string);
+}

package/dist/Errors/ZaloApiLoginQRDeclined.js

@@ -0,0 +1,7 @@
+import { ZaloApiError } from "./ZaloApiError.js";
+export class ZaloApiLoginQRDeclined extends ZaloApiError {
+    constructor(message = "Login QR request declined") {
+        super(message);
+        this.name = "ZaloApiLoginQRDeclined";
+    }
+}

package/dist/Errors/ZaloApiMissingImageMetadataGetter.d.ts

@@ -0,0 +1,4 @@
+import { ZaloApiError } from "./ZaloApiError.js";
+export declare class ZaloApiMissingImageMetadataGetter extends ZaloApiError {
+    constructor();
+}

package/dist/Errors/ZaloApiMissingImageMetadataGetter.js

@@ -0,0 +1,7 @@
+import { ZaloApiError } from "./ZaloApiError.js";
+export class ZaloApiMissingImageMetadataGetter extends ZaloApiError {
+    constructor() {
+        super("Missing `imageMetadataGetter`. Please provide it in the Zalo object options.");
+        this.name = "ZaloApiMissingImageMetadataGetter";
+    }
+}

package/dist/Errors/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./ZaloApiError.js";
+export * from "./ZaloApiMissingImageMetadataGetter.js";
+export * from "./ZaloApiLoginQRAborted.js";
+export * from "./ZaloApiLoginQRDeclined.js";

package/dist/Errors/index.js

@@ -0,0 +1,4 @@
+export * from "./ZaloApiError.js";
+export * from "./ZaloApiMissingImageMetadataGetter.js";
+export * from "./ZaloApiLoginQRAborted.js";
+export * from "./ZaloApiLoginQRDeclined.js";

package/dist/apis/acceptFriendRequest.d.ts

@@ -0,0 +1,2 @@
+export type AcceptFriendRequestResponse = "";
+export declare const acceptFriendRequestFactory: (ctx: import("../context.js").ContextBase, api: import("../apis.js").API) => (friendId: string) => Promise<"">;

package/dist/apis/acceptFriendRequest.js

@@ -0,0 +1,28 @@
+import { ZaloApiError } from "../Errors/ZaloApiError.js";
+import { apiFactory } from "../utils.js";
+export const acceptFriendRequestFactory = apiFactory()((api, ctx, utils) => {
+    const serviceURL = utils.makeURL(`${api.zpwServiceMap.friend[0]}/api/friend/accept`);
+    /**
+     * Accept a friend request from a User
+     *
+     * @param friendId The friend ID to user request is accept
+     *
+     * @throws {ZaloApiError}
+     */
+    return async function acceptFriendRequest(friendId) {
+        const params = {
+            fid: friendId,
+            language: ctx.language,
+        };
+        const encryptedParams = utils.encodeAES(JSON.stringify(params));
+        if (!encryptedParams)
+            throw new ZaloApiError("Failed to encrypt params");
+        const response = await utils.request(serviceURL, {
+            method: "POST",
+            body: new URLSearchParams({
+                params: encryptedParams,
+            }),
+        });
+        return utils.resolve(response);
+    };
+});

package/dist/apis/addGroupBlockedMember.d.ts

@@ -0,0 +1,2 @@
+export type AddGroupBlockedMemberResponse = "";
+export declare const addGroupBlockedMemberFactory: (ctx: import("../context.js").ContextBase, api: import("../apis.js").API) => (memberId: string | string[], groupId: string) => Promise<"">;

package/dist/apis/addGroupBlockedMember.js

@@ -0,0 +1,28 @@
+import { ZaloApiError } from "../Errors/ZaloApiError.js";
+import { apiFactory } from "../utils.js";
+export const addGroupBlockedMemberFactory = apiFactory()((api, _, utils) => {
+    const serviceURL = utils.makeURL(`${api.zpwServiceMap.group[0]}/api/group/blockedmems/add`);
+    /**
+     * Add group blocked member
+     *
+     * @param memberId member id(s)
+     * @param groupId group id
+     *
+     * @throws {ZaloApiError}
+     */
+    return async function addGroupBlockedMember(memberId, groupId) {
+        if (!Array.isArray(memberId))
+            memberId = [memberId];
+        const params = {
+            grid: groupId,
+            members: memberId,
+        };
+        const encryptedParams = utils.encodeAES(JSON.stringify(params));
+        if (!encryptedParams)
+            throw new ZaloApiError("Failed to encrypt params");
+        const response = await utils.request(utils.makeURL(serviceURL, { params: encryptedParams }), {
+            method: "GET",
+        });
+        return utils.resolve(response);
+    };
+});

package/dist/apis/addGroupDeputy.d.ts

@@ -0,0 +1,2 @@
+export type AddGroupDeputyResponse = "";
+export declare const addGroupDeputyFactory: (ctx: import("../context.js").ContextBase, api: import("../apis.js").API) => (memberId: string | string[], groupId: string) => Promise<"">;

package/dist/apis/addGroupDeputy.js

@@ -0,0 +1,30 @@
+import { ZaloApiError } from "../Errors/ZaloApiError.js";
+import { apiFactory } from "../utils.js";
+export const addGroupDeputyFactory = apiFactory()((api, ctx, utils) => {
+    const serviceURL = utils.makeURL(`${api.zpwServiceMap.group[0]}/api/group/admins/add`);
+    /**
+     * Add group deputy
+     *
+     * @param memberId user Id or list of user Ids
+     * @param groupId group Id
+     *
+     * @throws {ZaloApiError}
+     *
+     */
+    return async function addGroupDeputy(memberId, groupId) {
+        if (!Array.isArray(memberId))
+            memberId = [memberId];
+        const params = {
+            grid: groupId,
+            members: memberId,
+            imei: ctx.imei,
+        };
+        const encryptedParams = utils.encodeAES(JSON.stringify(params));
+        if (!encryptedParams)
+            throw new ZaloApiError("Failed to encrypt params");
+        const response = await utils.request(utils.makeURL(serviceURL, { params: encryptedParams }), {
+            method: "GET",
+        });
+        return utils.resolve(response);
+    };
+});

package/dist/apis/addPollOptions.d.ts

@@ -0,0 +1,14 @@
+import type { PollOptions } from "../models/index.js";
+export type AddPollOptionsOption = {
+    voted: boolean;
+    content: string;
+};
+export type AddPollOptionsPayload = {
+    pollId: number;
+    options: AddPollOptionsOption[];
+    votedOptionIds: number[];
+};
+export type AddPollOptionsResponse = {
+    options: PollOptions[];
+};
+export declare const addPollOptionsFactory: (ctx: import("../context.js").ContextBase, api: import("../apis.js").API) => (payload: AddPollOptionsPayload) => Promise<AddPollOptionsResponse>;

package/dist/apis/addPollOptions.js

@@ -0,0 +1,26 @@
+import { ZaloApiError } from "../Errors/ZaloApiError.js";
+import { apiFactory } from "../utils.js";
+export const addPollOptionsFactory = apiFactory()((api, _ctx, utils) => {
+    const serviceURL = utils.makeURL(`${api.zpwServiceMap.group[0]}/api/poll/option/add`);
+    /**
+     * Add new option to poll
+     *
+     * @param payload
+     *
+     * @throws {ZaloApiError}
+     */
+    return async function addPollOptions(payload) {
+        const params = {
+            poll_id: payload.pollId,
+            new_options: JSON.stringify(payload.options),
+            voted_option_ids: payload.votedOptionIds,
+        };
+        const encryptedParams = utils.encodeAES(JSON.stringify(params));
+        if (!encryptedParams)
+            throw new ZaloApiError("Failed to encrypt params");
+        const response = await utils.request(utils.makeURL(serviceURL, { params: encryptedParams }), {
+            method: "GET",
+        });
+        return utils.resolve(response);
+    };
+});

package/dist/apis/addQuickMessage.d.ts

@@ -0,0 +1,11 @@
+import type { QuickMessage, AttachmentSource } from "../models/index.js";
+export type AddQuickMessagePayload = {
+    keyword: string;
+    title: string;
+    media?: AttachmentSource;
+};
+export type AddQuickMessageResponse = {
+    item: QuickMessage;
+    version: number;
+};
+export declare const addQuickMessageFactory: (ctx: import("../context.js").ContextBase, api: import("../apis.js").API) => (addPayload: AddQuickMessagePayload) => Promise<AddQuickMessageResponse>;

package/dist/apis/addQuickMessage.js

@@ -0,0 +1,60 @@
+import { ZaloApiError } from "../Errors/ZaloApiError.js";
+import { apiFactory } from "../utils.js";
+export const addQuickMessageFactory = apiFactory()((api, ctx, utils) => {
+    const serviceURL = utils.makeURL(`${api.zpwServiceMap.quick_message[0]}/api/quickmessage/create`);
+    /**
+     * Add quick message
+     *
+     * @param addPayload - The payload containing data to add the quick message
+     *
+     * @note Zalo might throw an error with code 821 if you have reached the limit of quick messages.
+     *
+     * @throws {ZaloApiError}
+     */
+    return async function addQuickMessage(addPayload) {
+        const isType = !addPayload.media ? 0 : 1;
+        const params = {
+            keyword: addPayload.keyword,
+            message: {
+                title: addPayload.title,
+                params: "",
+            },
+            type: isType,
+            imei: ctx.imei,
+        };
+        if (isType === 1) {
+            if (!addPayload.media)
+                throw new ZaloApiError("Media is required");
+            const uploadMedia = await api.uploadProductPhoto({
+                file: addPayload.media,
+            });
+            const photoId = uploadMedia.photoId;
+            const thumbUrl = uploadMedia.thumbUrl;
+            const normalUrl = uploadMedia.normalUrl;
+            const hdUrl = uploadMedia.hdUrl;
+            params.media = {
+                items: [
+                    {
+                        type: 0,
+                        photoId: photoId,
+                        title: "",
+                        width: "",
+                        height: "",
+                        previewThumb: thumbUrl,
+                        rawUrl: normalUrl || hdUrl,
+                        thumbUrl: thumbUrl,
+                        normalUrl: normalUrl || hdUrl,
+                        hdUrl: hdUrl || normalUrl,
+                    },
+                ],
+            };
+        }
+        const encryptedParams = utils.encodeAES(JSON.stringify(params));
+        if (!encryptedParams)
+            throw new ZaloApiError("Failed to encrypt params");
+        const response = await utils.request(utils.makeURL(serviceURL, { params: encryptedParams }), {
+            method: "GET",
+        });
+        return utils.resolve(response);
+    };
+});

package/dist/apis/addReaction.d.ts

@@ -0,0 +1,18 @@
+import { ThreadType, Reactions } from "../models/index.js";
+export type AddReactionResponse = {
+    msgIds: number[];
+};
+export type CustomReaction = {
+    rType: number;
+    source: number;
+    icon: string;
+};
+export type AddReactionDestination = {
+    data: {
+        msgId: string;
+        cliMsgId: string;
+    };
+    threadId: string;
+    type: ThreadType;
+};
+export declare const addReactionFactory: (ctx: import("../context.js").ContextBase, api: import("../apis.js").API) => (icon: Reactions | CustomReaction, dest: AddReactionDestination) => Promise<AddReactionResponse>;