mysa-js-sdk/CONTRIBUTING.md

# Contributing to mysa-js-sdk

First off, thank you for considering contributing to `mysa-js-sdk`! Contributions from the community are essential in
making this project better. Whether you want to report a bug, propose new features, improve documentation or submit code
changes, I welcome your input and assistance. This guide will help you get started with contributing.

## Development Environment

This project uses Node.js and npm for development. Make sure you have Node.js 22.4.0 or higher installed.

### Setting Up Your Development Environment

1. Fork the repository on GitHub
2. Clone your fork locally
3. Navigate to the cloned directory
4. Install dependencies using npm:

```bash
npm install
```

### Project Structure

```
mysa-js-sdk/
├── src/                          # Source code
│   ├── api/                      # Main API classes and client
│   │   └── events/               # Event type definitions
│   ├── lib/                      # Utility libraries
│   └── types/                    # TypeScript type definitions
│       ├── mqtt/                 # MQTT message types
│       │   ├── in/               # Incoming MQTT message types
│       │   └── out/              # Outgoing MQTT message types
│       └── rest/                 # REST API types
├── example/                      # Example usage
├── dist/                         # Built JavaScript files (generated)
├── docs/                         # Generated API documentation (generated)
└── node_modules/                 # Dependencies (generated)
```

### Development Workflow

1. Create a new branch for your feature or bug fix
2. Make your changes
3. Run linting checks: `npm run lint` and `npm run style-lint`
4. Build the project: `npm run build`
5. Commit your changes using conventional commit format
6. Push your changes to your fork
7. Create a pull request

### Building

Build the project using [tsup](https://github.com/egoist/tsup):

```bash
npm run build
```

This will generate JavaScript files in the `dist/` directory.

### Documentation

Generate API documentation using TypeDoc:

```bash
npm run build:docs
```

This will generate documentation in the `docs/` directory.

### Environment Variables

To run the [example](example/main.ts), you'll need to provide your Mysa credentials. Create a `.env` file in the project
root:

```
MYSA_USERNAME=your-email@example.com
MYSA_PASSWORD=your-password
```

**Important:** Never commit your `.env` file to the repository!

## Submitting Pull Requests

### Conventional Commits

This repository uses [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/). This means that each commit
message must follow a specific format. The format is as follows:

```
<type>[optional scope]: <description>
```

The `type` must be one of the following:

| Type       | Description                                                                        |
| ---------- | ---------------------------------------------------------------------------------- |
| `feat`     | A new feature.                                                                     |
| `fix`      | A bug fix.                                                                         |
| `docs`     | Documentation only changes.                                                        |
| `test`     | Changes to tests.                                                                  |
| `perf`     | A code change that improves performance.                                           |
| `refactor` | A code change that neither fixes a bug nor adds a feature.                         |
| `style`    | Changes that do not affect the meaning of the code (white-space, formatting, etc). |
| `chore`    | Regular maintenance tasks and updates.                                             |
| `build`    | Changes that affect the build system or external dependencies.                     |
| `ci`       | Changes to CI configuration files and scripts.                                     |
| `revert`   | Reverting a previous commit.                                                       |

The `scope` is optional and should be used to specify the part of the codebase that the commit affects.

The `description` should be a short, concise summary of the changes made in the commit. The description will appear
as-is in the release notes, so make sure it is clear, informative and not too technical.

For example:

```
feat: Added support for dark mode
```

### Semantic Versioning

This repository uses [semantic versioning](https://semver.org/). This means that each release will be versioned
according to the following rules:

- Increment the major version for breaking changes
- Increment the minor version for new features
- Increment the patch version for bug fixes

Releases are automatically generated by [semantic-release](https://github.com/semantic-release/semantic-release) based
on the commit messages. The version number is determined by the type of commits since the last release.

### Coding Standards

This project adheres to a set of coding standards to ensure consistency and maintainability:

1. **TypeScript**: Write all code in TypeScript with proper type annotations.
2. **Documentation**: Use [TSDoc](https://tsdoc.org/) comments for all public APIs.
3. **Clean Code**: Write clear, self-explanatory code with meaningful variable names.
4. **Error Handling**: Properly handle errors and edge cases.

### Code Style

This repository uses [ESLint](https://eslint.org/) and [Prettier](https://prettier.io/) to enforce code style and
formatting. All code must pass both linting checks:

```bash
# Run ESLint
npm run lint

# Run Prettier
npm run style-lint
```

The project is configured with specific rules for:

- Maximum line length
- Indentation (2 spaces)
- Quote style (single quotes)
- Semi-colons (required)
- Trailing commas
- And more

These rules are automatically enforced and cannot be overridden. Please make sure that your code follows these
conventions.

### Pull Request Checklist

Before submitting a pull request, please make sure that:

- Your code follows the coding standards and conventions used in the project
- Your code passes linting checks: `npm run lint`
- Your code passes style checks: `npm run style-lint`
- The documentation has been updated to reflect any changes
- Your commit messages follow the conventional commits format
- The build completes successfully: `npm run build`
- You've verified that your changes work as expected