Contributing

How to contribute to MarzbanSDK — reporting bugs, submitting PRs, and development setup.

Thank you for your interest in contributing to MarzbanSDK! All contributions are welcome — bug fixes, features, documentation improvements, and test coverage.

Reporting issues

Open an issue on GitHub and include:

A clear description of the problem.
Steps to reproduce (code snippet or minimal repo link preferred).
Expected vs. actual behaviour.
SDK version (npm list marzban-sdk).

Development setup

git clone https://github.com/Ilmar7786/marzban-sdk.git
cd marzban-sdk
npm install

Available scripts

Command	Description
`npm run build`	Compile TypeScript → `dist/` (ESM + CJS)
`npm test`	Run the full test suite once with Vitest
`npm run test:watch`	Run tests in watch mode
`npm run test:coverage`	Run tests with a coverage report
`npm run lint`	Run ESLint
`npm run codegen`	Regenerate the API client from `openapi/` using Kubb

Testing

The SDK is covered by Vitest. Tests live next to the code they cover as src/**/*.test.ts.

npm test              # run once
npm run test:watch    # watch mode while developing
npm run test:coverage # run with a coverage report

Hand-written code is held at 100% coverage — statements, branches, functions, and lines. Generated code (src/gen/, produced from the OpenAPI spec) and type-only files are excluded from coverage on purpose.

Every feature and bug fix must come with tests, and npm run test:coverage must stay green.

Build & verify

npm run build
npm run test:coverage

Both must pass before submitting a PR.

Submitting a pull request

Fork the repository and create a new branch:
```
git checkout -b feat/your-feature
```
Make your changes.
Add or update tests in src/**/*.test.ts.
Run npm run test:coverage and npm run build.

Commit using Conventional Commits (enforced by commitlint):

feat: add pagination to getUsers
fix: handle missing token in AuthManager
docs: add NestJS integration example

Push and open a PR against the main branch.

Commit message format

type(scope?): short description

Optional body.

BREAKING CHANGE: description  ← for major version bumps

Types: feat, fix, docs, refactor, test, chore, perf, build.

Code style

All code is in TypeScript with strict mode enabled.
ESLint + Prettier enforce style — run npm run lint before committing.
No unnecessary — prefer proper generics or unknown.
No comments that explain what the code does — only why when it's non-obvious.

Regenerating the API client

The src/gen/ directory is auto-generated from the OpenAPI spec. Do not edit it manually:

# Update the spec in openapi/ first, then:
npm run codegen

If you're fixing a bug in a generated file, fix the template or the spec instead.

Questions

Start a discussion in GitHub Discussions or open an issue.

On this page