@warriorteam/zalo-personal/CONTRIBUTING.md

Unofficial Zalo Personal API for JavaScript - A powerful library for interacting with Zalo personal accounts with URL attachment support, auto-reply, product catalog, and business features

# 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.