npm package: @hexonet/semantic-release-whmcs
Description: `semantic-release` plugin for auto-publishing on WHMCS marketplace
Author: Kai Schwarz
Latest version: 5.2.12

# semantic-release-whmcs

[![npm version](https://img.shields.io/npm/v/semantic-release-whmcs.svg?style=flat)](https://www.npmjs.com/package/semantic-release-whmcs)
[![node](https://img.shields.io/node/v/semantic-release-whmcs.svg)](https://www.npmjs.com/package/semantic-release-whmcs)
[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)
[![Build Status](https://github.com/centralnicgroup-opensource/rtldev-middleware-semantic-release-whmcs/workflows/Release/badge.svg?branch=master)](https://github.com/centralnicgroup-opensource/rtldev-middleware-semantic-release-whmcs/workflows/Release/badge.svg?branch=master)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/hexonet/node-sdk/blob/master/CONTRIBUTING.md)

[**semantic-release**](https://github.com/semantic-release/semantic-release) plugin to publish a WHMCS product/module version to [WHMCS Marketplace](https://marketplace.whmcs.com).

| Step | Description |
| ---- | ----------- |
| `prepare` | Install OS dependencies required by Puppeteer and Chromium/Chrome (Debian/Ubuntu only). Can be customized via `osDepsCommand`. |
| `verifyConditions` | Verify the presence and the validity of the authentication credentials (set via [environment variables](#environment-variables)) and the product id option configuration. |
| `publish` | Publish product/module version to [WHMCS Marketplace](https://marketplace.whmcs.com) including changelog notes. |

FYI: This module is ESM ready!

## Resources

* [Usage Guide](#usage-guide)
* [Release Notes](https://github.com/centralnicgroup-opensource/rtldev-middleware-semantic-release-whmcs/releases)
* [Development Guide](https://github.com/centralnicgroup-opensource/rtldev-middleware-semantic-release-whmcs/wiki/Development-Guide)

## Usage Guide

### Requirements

* Installed nodejs/npm. We suggest using [nvm](https://github.com/creationix/nvm).
* **OS Dependencies**: On Debian/Ubuntu systems, the `prepare` step installs Chrome (for testing) + required OS packages using `pnpm dlx puppeteer browsers install chrome --install-deps` (falls back to `npx` if `pnpm` is unavailable). You can override the command via `osDepsCommand`.
* Using [semantic-release](https://github.com/semantic-release/semantic-release) in your CI/CD process

### Install

```bash
> npm i @hexonet/semantic-release-whmcs -D
```

### Configuration

The plugin can be loaded in the [**semantic-release** configuration file](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md#configuration). The `prepare` step handles OS dependencies on Debian/Ubuntu (requires `sudo` access for system packages).

```json
{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    [
      "@hexonet/semantic-release-whmcs",
      {
        "osDepsCommand": [
          "pnpm",
          "dlx",
          "puppeteer",
          "browsers",
          "install",
          "chrome",
          "--install-deps"
        ]
      }
    ]
  ]
}
```

With this example product/module versions will be published to the [WHMCS Marketplace](https://marketplace.whmcs.com) including changelog notes.

### WHMCS Marketplace authentication

The WHMCS Marketplace authentication configuration is **required** and can be set via [environment variables](#environment-variables).

If you don't have a WHMCS Marketplace account yet, please create one. The credentials have to be made available in your CI environment via the `WHMCSMP_LOGIN` and  `WHMCSMP_PASSWORD` environment variables. The account must have access to the product(s) you want to publish new versions for.

### WHMCS Marketplace Product ID

The WHMCS Marketplace Product ID configuration is **required**  and can be set via [environment variables](#environment-variables).

The Product ID has to be made available in your CI environment via the `WHMCSMP_PRODUCTID` environment variable.

That said, before you can use this module for publishing new product/module version to the WHMCS Marketplace, this Product has already to exist and as mentioned above, the account you provide here for authentication has to have access to manage that product. You can find the Product ID in the url when being in edit mode e.g. [https://marketplace.whmcs.com/product/**1234**/edit](https://marketplace.whmcs.com/).

### Environment variables

| Variable                       | Description                                               |
| ------------------------------ | --------------------------------------------------------- |
| `WHMCSMP_LOGIN` | **Required.** The email address of the WHMCS Marketplace account to use for authentication. |
| `WHMCSMP_PASSWORD` | **Required.** The password of the WHMCS Marketplace account to use for authentication. |
| `WHMCSMP_PRODUCTID` | **Required.** The product id of the product/module you want to publish versions for. |
| `WHMCSMP_MINVERSION` | **Optional.** The minimum supported WHMCS version. Defaults to 7.10. |
| `PUPPETEER_HEADLESS` | **Optional.** Toggle headless mode on/off. by default true. Values: 1,0. |
| `GH_TOKEN` | **Optional.** GitHub API authentication token to use for syncing versions. |
| `GH_REPO` | **Optional.** GitHub repository name (format: organization/repository) to use for syncing versions. |
| `useCookieExtension` | **Optional.** Use cookies extension when puppeteer is running to avoid cookie banner disruptions. |
| `WHMCS_OS_DEPS_ALWAYS` | **Optional.** Force OS dependency installation in `prepare` even if there is no new release version. Useful for CI experiments. Values: `1` / `true`. |
| `SKIP_OS_DEPS` | **Optional.** Skip OS dependency installation in `prepare`. Values: `1` / `true` (also supported: `skipOsDeps`). |

### Options

| Option | Type | Description |
| --- | --- | --- |
| `skipOsDeps` | Boolean | **Optional.** Skip OS dependency installation in the prepare step. Default: `false`. Useful if you already have dependencies installed or prefer to manage them yourself. |
| `osDepsCommand` | string[] | **Optional.** Command to install dependencies (e.g. `["pnpm", "dlx", "puppeteer", "browsers", "install", "chrome", "--install-deps"]`). <br><br> **Note:** The command is automatically executed with `sudo` and the current `PATH` preserved (via `/bin/bash -c "sudo env PATH=$PATH ..."`), so you do not need to add `sudo` yourself. |

### Routines

Type `./whmcs.js --help` for command reference

## Contributing

Please read [Contribution Guide Lines](https://github.com/centralnicgroup-opensource/rtldev-middleware-semantic-release-whmcs/blob/master/CONTRIBUTING.md) for details on our code of conduct, then address a PR to us.
Contributors are highly welcome.

## Authors

* **Kai Schwarz** - *lead development* - [KaiSchwarz-cnic](https://github.com/KaiSchwarz-cnic)
* **Sebastian Vassiliou** - *development* - [SebastianVassiliou-cnic](https://github.com/SebastianVassiliou-cnic)

## License

This project is licensed under the MIT License - see the [LICENSE](https://github.com/centralnicgroup-opensource/rtldev-middleware-semantic-release-whmcs/blob/master/LICENSE) file for details.

[HEXONET GmbH](https://hexonet.net)