Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
470 lines (361 loc) · 12.8 KB

CONTRIBUTING.md

File metadata and controls

470 lines (361 loc) · 12.8 KB
Raw

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

This project adheres to our Code of Conduct. 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: 
    git clone https://github.com/YOUR_USERNAME/zca-js.git
cd zca-js
  3. Add upstream remote: 
    git remote add upstream https://github.com/RFS-ADRENO/zca-js.git

Development Setup

Install Dependencies

# Using Bun (recommended)
bun install

# Or using npm
npm install

Build Project

# Build both ESM and CJS
bun run build

# Build ESM only
bun run build:esm

# Build CJS only
bun run build:cjs

Run Tests

# Run feature tests
bun run test:feat

# Run specific test file
bun run test/test.ts

Code Formatting

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

    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:

    bun run build
bun run test:feat

  4. Commit your changes:

    git add .
git commit -m "feat: add new API method for group management"

  5. Push to your fork:

    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

// 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

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

# 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
/**
 * 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 reporting process
  3. Create a private issue with [SECURITY] label
  4. Contact team members directly for urgent issues

Code Security

// 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:

  • 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

# 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

Resources

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.