@nam088/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 "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://tdung.gitbook.io/zca-js) 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.