@trungdlp/zca-js 1.0.0

package/.prettierrc

@@ -0,0 +1,5 @@
+{
+    "tabWidth": 4,
+    "printWidth": 120,
+    "semi": true
+}

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,163 @@
+# Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement through:
+- **GitHub Issues**: Create a private issue with the `[CONDUCT]` label
+- **GitHub Discussions**: Use the "Community" category for general concerns
+- **Direct Contact**: Reach out to any team member through GitHub
+- **Team Members**:
+  - [@RFS-ADRENO](https://github.com/RFS-ADRENO)
+  - [@truong9c2208](https://github.com/truong9c2208)
+  - [@JustKemForFun](https://github.com/JustKemForFun)
+
+All complaints will be reviewed and investigated promptly and fairly by the team.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.
+
+## Special Considerations for zca-js
+
+Given that zca-js is an unofficial API library for Zalo, we have additional
+guidelines specific to our project:
+
+### Responsible Usage
+
+* **Respect Zalo's Terms of Service**: While this is an unofficial library,
+  users should be aware of and respect Zalo's terms of service
+* **Account Safety**: Do not encourage or provide guidance on circumventing
+  Zalo's security measures
+* **Privacy**: Respect user privacy and do not share personal information
+  obtained through the API
+* **Rate Limiting**: Encourage responsible usage that doesn't overload Zalo's
+  servers
+
+### Technical Discussions
+
+* **Security**: When discussing security-related topics, use appropriate
+  channels and follow responsible disclosure practices
+* **Bugs and Issues**: Report bugs and issues through proper channels
+* **Documentation**: Help improve documentation and examples for the community
+
+---
+
+**Note**: This Code of Conduct is a living document and may be updated as our
+community grows and evolves. 

package/CONTRIBUTING.md

@@ -0,0 +1,470 @@
+# Contributing to zca-js
+
+Thank you for your interest in contributing to zca-js! This project is maintained by the community and we welcome all contributions.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Development Setup](#development-setup)
+- [How to Contribute](#how-to-contribute)
+- [Pull Request Process](#pull-request-process)
+- [Code Style Guidelines](#code-style-guidelines)
+- [Testing Guidelines](#testing-guidelines)
+- [Documentation Guidelines](#documentation-guidelines)
+- [Security Guidelines](#security-guidelines)
+- [Release Process](#release-process)
+- [Getting Help](#getting-help)
+
+## Code of Conduct
+
+This project adheres to our [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you agree to abide by these rules.
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js >= 18.0.0
+- Bun (recommended) or npm
+- Git
+
+### Fork and Clone
+
+1. Fork this repository
+2. Clone your fork:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/zca-js.git
+   cd zca-js
+   ```
+3. Add upstream remote:
+   ```bash
+   git remote add upstream https://github.com/RFS-ADRENO/zca-js.git
+   ```
+
+## Development Setup
+
+### Install Dependencies
+
+```bash
+# Using Bun (recommended)
+bun install
+
+# Or using npm
+npm install
+```
+
+### Build Project
+
+```bash
+# Build both ESM and CJS
+bun run build
+
+# Build ESM only
+bun run build:esm
+
+# Build CJS only
+bun run build:cjs
+```
+
+### Run Tests
+
+```bash
+# Run feature tests
+bun run test:feat
+
+# Run specific test file
+bun run test/test.ts
+```
+
+### Code Formatting
+
+```bash
+# Format code with Prettier
+bun run prettier
+```
+
+## How to Contribute
+
+### Types of Contributions
+
+We welcome the following types of contributions:
+
+- 🐛 **Bug Reports**: Report bugs and issues
+- ✨ **Feature Requests**: Suggest new features
+- 🔧 **Code Contributions**: Fix bugs and add features
+- 📚 **Documentation**: Improve docs and examples
+- 🧪 **Tests**: Add or improve tests
+- 🔒 **Security**: Report security vulnerabilities
+- 🌐 **Translations**: Translate docs to other languages
+
+### Before You Start
+
+1. **Check existing issues**: Search for existing issues before creating new ones
+2. **Discuss major changes**: Create an issue to discuss major changes
+3. **Follow the roadmap**: Check the current roadmap and priorities
+
+## Pull Request Process
+
+### Creating a Pull Request
+
+1. **Create a feature branch**:
+   ```bash
+   git checkout -b feature/your-feature-name
+   # or
+   git checkout -b fix/your-bug-fix
+   ```
+
+2. **Make your changes**:
+   - Follow code style guidelines
+   - Add tests for new functionality
+   - Update documentation if needed
+
+3. **Test your changes**:
+   ```bash
+   bun run build
+   bun run test:feat
+   ```
+
+4. **Commit your changes**:
+   ```bash
+   git add .
+   git commit -m "feat: add new API method for group management"
+   ```
+
+5. **Push to your fork**:
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+6. **Create a Pull Request**:
+   - Use the provided PR template
+   - Link related issues
+   - Provide clear description of changes
+
+### PR Review Process
+
+1. **Automated checks** must pass
+2. **Code review** by at least one maintainer
+3. **Security review** for security-related changes
+4. **Documentation review** for API changes
+5. **Final approval** before merge
+
+## Code Style Guidelines
+
+### TypeScript Guidelines
+
+- Use TypeScript strict mode
+- Prefer interfaces over types for object shapes
+- Use meaningful variable and function names
+- Add JSDoc comments for public APIs
+- Use async/await over Promises when possible
+
+### Code Organization
+
+The project follows a modular structure for better maintainability and organization:
+
+```
+zca-js/
+├── src/                           # Source code directory
+│   ├── apis/                      # API methods (100+ files)
+│   │   ├── sendMessage.ts         # Core messaging functionality
+│   │   ├── login.ts               # Authentication methods
+│   │   ├── loginQR.ts             # QR code login
+│   │   ├── listen.ts              # Event listening
+│   │   ├── sendVideo.ts           # Video sending
+│   │   ├── sendVoice.ts           # Voice sending
+│   │   ├── sendSticker.ts         # Sticker sending
+│   │   ├── createGroup.ts         # Group management
+│   │   ├── addReaction.ts         # Message reactions
+│   │   ├── uploadAttachment.ts    # File uploads
+│   │   └── ...                    # 90+ other API methods
+│   ├── models/                    # TypeScript interfaces and types
+│   │   ├── Message.ts             # Message interface
+│   │   ├── Attachment.ts          # File attachment types
+│   │   ├── Reaction.ts            # Reaction types
+│   │   ├── FriendEvent.ts         # Friend event types
+│   │   ├── GroupEvent.ts          # Group event types
+│   │   ├── Typing.ts              # Typing indicators
+│   │   ├── SeenMessage.ts         # Message seen events
+│   │   ├── DeliveredMessage.ts    # Message delivery events
+│   │   ├── Undo.ts                # Undo functionality
+│   │   ├── Enum.ts                # Enumerations
+│   │   └── index.ts               # Model exports
+│   ├── Errors/                    # Error handling
+│   │   ├── ZaloApiError.ts        # Custom API error class
+│   │   └── index.ts               # Error exports
+│   ├── context.ts                 # Context management and state
+│   ├── utils.ts                   # Utility functions and helpers
+│   ├── zalo.ts                    # Main Zalo class implementation
+│   ├── update.ts                  # Update checking functionality
+│   └── index.ts                   # Public API exports
+├── examples/                      # Usage examples
+│   └── echobot.ts                 # Echo bot example
+├── test/                          # Test files
+│   ├── feat.ts                    # Feature tests
+│   ├── feat.test.ts               # Feature test suite
+│   ├── test.ts                    # General tests
+│   └── a.png                      # Test assets
+├── .github/                       # GitHub configuration
+│   └── ISSUE_TEMPLATE/            # Issue templates
+├── .dev/                          # Development tools (developer generated)
+├── dist/                          # Build output (generated)
+├── node_modules/                  # Dependencies (generated)
+├── package.json                   # Project configuration
+├── tsconfig.json                  # TypeScript configuration
+├── rollup.config.js               # Build configuration
+├── README.md                      # Project documentation
+├── CONTRIBUTING.md                # Contribution guidelines
+├── SECURITY.md                    # Security policy
+├── CODE_OF_CONDUCT.md             # Community guidelines
+└── LICENSE                        # MIT License
+```
+
+### Key Directories Explained
+
+- **`src/apis/`**: Contains all API method implementations (~100 files)
+
+- **`src/models/`**: TypeScript interfaces and type definitions
+  - Core data structures for messages, events, and API responses
+  - Ensures type safety across the application
+
+- **`src/Errors/`**: Custom error handling
+  - `ZaloApiError.ts`: Handles API-specific errors
+  - Provides consistent error handling across the library
+
+- **`examples/`**: Usage examples and demonstrations
+  - `echobot.ts`: Complete example of a Zalo bot implementation
+
+- **`test/`**: Test suites and test assets
+  - Feature tests for core functionality
+  - Integration tests for API methods
+
+### Naming Conventions
+
+- **Files**: camelCase (e.g., `sendMessage.ts`)
+- **Classes**: PascalCase (e.g., `ZaloApiError`)
+- **Functions**: camelCase (e.g., `sendMessage`)
+- **Constants**: UPPER_SNAKE_CASE (e.g., `API_BASE_URL`)
+- **Interfaces**: PascalCase with `I` prefix (e.g., `IMessage`)
+
+### Error Handling
+
+```typescript
+// Good
+try {
+  const result = await api.sendMessage(message);
+  return result;
+} catch (error) {
+  if (error instanceof ZaloApiError) {
+      throw error;
+  }
+  throw new ZaloApiError(`Failed to send message: ${error.message}`);
+}
+
+// Bad
+try {
+  const result = await api.sendMessage(message);
+  return result;
+} catch (error) {
+  console.error(error);
+  return null;
+}
+```
+
+## Testing Guidelines
+
+### Test Structure
+
+```typescript
+describe('API Method', () => {
+  beforeEach(() => {
+    // Setup
+  });
+
+  afterEach(() => {
+    // Cleanup
+  });
+
+  it('should handle success case', async () => {
+    // Test implementation
+  });
+
+  it('should handle error case', async () => {
+    // Test error handling
+  });
+});
+```
+
+### Testing Best Practices
+
+- Test both success and failure scenarios
+- Mock external dependencies
+- Use descriptive test names
+- Keep tests independent
+- Test edge cases and error conditions
+
+### Running Tests
+
+```bash
+# Run all tests
+bun run test:feat
+
+# Run specific test
+bun run test/test.ts
+
+# Run with coverage (if available)
+bun run test:coverage
+```
+
+## Documentation Guidelines
+
+### API Documentation
+
+- Document all public methods with JSDoc
+- Include parameter types and descriptions
+- Provide usage examples
+- Document error conditions
+
+```typescript
+/**
+ * Sends a message to a specific thread
+ * @param message - The message object containing content and metadata
+ * @param threadId - The ID of the thread to send the message to
+ * @param threadType - The type of thread (User or Group)
+ * @returns Promise<Message> - The sent message object
+ * @throws {ZaloApiError} When the API request fails
+ * @example
+ * ```typescript
+ * const message = await api.sendMessage(
+ *   { msg: "Hello, world!" },
+ *   "123456789",
+ *   ThreadType.User
+ * );
+ * ```
+ */
+async sendMessage(message: IMessage, threadId: string, threadType: ThreadType): Promise<Message>
+```
+
+### README Updates
+
+- Update README.md for new features
+- Add examples for new APIs
+- Update installation instructions if needed
+- Keep the table of contents updated
+
+## Security Guidelines
+
+### Security Best Practices
+
+- Never commit sensitive data (tokens, passwords, etc.)
+- Use environment variables for configuration
+- Validate all user inputs
+- Follow the principle of least privilege
+- Report security issues privately
+
+### Security Reporting
+
+If you discover a security vulnerability:
+
+1. **DO NOT** create a public issue
+2. Use the [SECURITY.md](SECURITY.md) reporting process
+3. Create a private issue with `[SECURITY]` label
+4. Contact team members directly for urgent issues
+
+### Code Security
+
+```typescript
+// Good - Validate inputs
+function sendMessage(content: string, threadId: string) {
+  if (!content || typeof content !== 'string') {
+    throw new ZaloApiError('Content must be a non-empty string');
+  }
+  if (!threadId || typeof threadId !== 'string') {
+    throw new ZaloApiError('ThreadId must be a non-empty string');
+  }
+  // Implementation
+}
+
+// Bad - No validation
+function sendMessage(content: any, threadId: any) {
+  // Implementation without validation
+}
+```
+
+## Release Process
+
+### Versioning
+
+We follow [Semantic Versioning](https://semver.org/):
+
+- **MAJOR**: Breaking changes
+- **MINOR**: New features (backward compatible)
+- **PATCH**: Bug fixes (backward compatible)
+
+### Release Checklist
+
+- [ ] All tests pass
+- [ ] Documentation is updated
+- [ ] Version is bumped in package.json
+- [ ] Build is successful
+- [ ] Release notes are prepared
+
+### Publishing
+
+```bash
+# Build the project
+bun run build
+
+# Run tests
+bun run test:feat
+
+# Publish to npm
+npm publish
+```
+
+## Getting Help
+
+### Communication Channels
+
+- **GitHub Issues**: For bug reports and feature requests
+- **GitHub Discussions**: For questions and general discussion
+- **Pull Requests**: For code contributions
+- **Security Issues**: Use `[SECURITY]` label
+
+### Team Members
+
+- [@RFS-ADRENO](https://github.com/RFS-ADRENO)
+- [@truong9c2208](https://github.com/truong9c2208)
+- [@JustKemForFun](https://github.com/JustKemForFun)
+
+### Resources
+
+- [API Documentation](https://tdung.gitbook.io/zca-js)
+- [Examples](examples/)
+- [Security Policy](SECURITY.md)
+- [Code of Conduct](CODE_OF_CONDUCT.md)
+
+## Special Considerations for zca-js
+
+### Unofficial API Library
+
+> [!IMPORTANT]
+> ⚠️ zca-js is an unofficial API library for Zalo. Please be aware of:
+
+- **Account Risk**: Using this API may result in account suspension
+- **Terms of Service**: Respect Zalo's ToS in your contributions
+- **Rate Limiting**: Be mindful of API usage limits
+- **Privacy**: Protect user privacy and data
+
+### Responsible Development
+
+- Test changes thoroughly before submitting
+- Avoid introducing features that could harm users
+- Consider the impact on Zalo's infrastructure
+- Document any risks or limitations
+
+---
+
+**Thank you for contributing to zca-js!** 🚀
+
+Your contributions help make this library better for the entire community. 

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 - 2025 RFS-ADRENO, truong9c2208, JustKemForFun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.