pager-duty-js
Version:
PagerDuty API Client
257 lines (188 loc) • 6.9 kB
Markdown
This module provides a set of functions to help **JavaScript** Developers working with PagerDuty to authenticate and access API endpoints using **JavaScript** _promises_.
## Requirements (MacOS/Windows)
* NodeJs
* Minimum: v14.x
* Recommended: **v16.x**
* npm
* Tested on: **v8.12.x**
* PagerDuty API
* REST API **v2**
* Events API **v2**
**Note:** Depending on your Windows setup [windows-build-tools](https://www.npmjs.com/package/windows-build-tools) may need to be installed first. Also, for MacOS users, you should have **xcode-select** or entire Xcode App installed.
### Install
`npm install pager-duty-js --save`
### Uninstall
`npm uninstall pager-duty-js`
### Release notes and versions
[Change log](./CHANGELOG.md)
### Class Constructor
```javascript
{
// Indicates if the HTTP request to the PagerDuty API server should use
// HTTPS (secure) or HTTP (non-secure) protocol
https: true,
// If https is true, then provide client certificate, client key and
// the root CA cert (PagerDuty API uses DigiCert one)
// Client cert and key are optional now
cert: './client.crt',
key: './client.key',
cacert: './ca.crt',
// Indicate the PagerDuty API URL,
// all paths are relative to this one
baseUrl: 'https://api.pagerduty.com',
// HTTP request timeout in milliseconds
timeout: 1000,
// If should use a proxy or not by the HTTP request
// Example:
// proxy: { host: proxy.ip, port: proxy.port }
proxy: false
}
```
**Note:** This package covers some auth methods and secret engines. Check `Coverage and Limitations` section for more details.
* PagerDuty API [reference](https://developer.pagerduty.com/api-reference)
**Production**
```javascript
const PagerDuty = require('pager-duty-js');
const pd = new PagerDuty( {
https: true,
cert: './client.crt',
key: './client.key',
cacert: './digicert-ca.crt',
baseUrl: 'https://api.pagerduty.com',
timeout: 1000,
proxy: false
});
```
**Development**
```javascript
const PagerDuty = require('pager-duty-js');
const pd = new PagerDuty( {
https: true,
baseUrl: 'https://api.pagerduty.com',
timeout: 3000,
proxy: false
});
```
**Alerts**
```javascript
const PagerDuty = require('pager-duty-js');
const pd = new PagerDuty( {
https: true,
cert: './client.crt',
key: './client.key',
cacert: './digicert-ca.crt',
baseUrl: 'https://events.pagerduty.com/v2',
rootPath: 'enqueue',
timeout: 1000,
proxy: false
});
```
**Change**
```javascript
const PagerDuty = require('pager-duty-js');
const pd = new PagerDuty( {
https: true,
cert: './client.crt',
key: './client.key',
cacert: './digicert-ca.crt',
baseUrl: 'https://events.pagerduty.com/v2',
rootPath: 'change/enqueue',
timeout: 1000,
proxy: false
});
```
* Check abilities for a given Rest API Token:
```javascript
const status = await pd.listAbilities(token);
```
* Create a new user through the Rest API:
```javascript
const status = await pd.createUser(token, data, requesterEmail);
```
* List alls teams through the Rest API:
```javascript
const status = await pd.listTeams(token, params);
```
* Trigger an alert through the Events API:
```javascript
const status = await pd.triggerEventAlert(integrationKey, data);
```
This package extends the error stack to differentiate if the exception occurred on the PagerDuty API layer or not. Also, adds a help message from the PagerDuty API docs.
```javascript
try {
pd.function(...);
}
// An exception happened and it was thrown
catch(err) {
if(err.isPagerDutyError) {
// This an error from PagerDuty API
// Check PagerDuty hint on this error
console.log(err.pagerDutyHelpMessage);
}
else {
// Here is still the full Axios error, e.g. err.isAxiosError, err.response, err.request
// This allows handling of network/tls related issues
// Or just re-throw if you don't care
throw err;
}
}
```
Check below docs for more information on specific function groups.
| **Group** | **Link** |
|:---------------------------------------|:--------------:|
| Abilities | [Doc](./docs/Abilities.md) |
| Teams | [Doc](./docs/Teams.md) |
| Users | [Doc](./docs/Users.md) |
| | |
| **Group** | **Link** |
|:---------------------------------------|:--------------:|
| Alert | [Doc](./docs/Alert.md) |
| Change | [Doc](./docs/Change.md) |
| | |
* Check the PagerDuty API rate limits [here](https://developer.pagerduty.com/docs/ZG9jOjExMDI5NTUz-rate-limiting)
The following PagerDuty API groups are currently covered:
* Abilities (Partially)
* Teams (Partially)
* Users (Partially)
* Alert (Full)
* trigger
* acknowledge
* resolve
* Change (Full)
* send
Follow the detailed instructions from this [site](https://developer.pagerduty.com/)
If you want to contribute to the module and make it better, your help is very welcome. You can do so submitting a **Pull Request**. It will be reviewed and merged to main branch if accepted.
If you have found what you believe to be an issue with `pager-duty-js` please do not hesitate to file an issue on the GitHub repository [here](https://github.com/rod4n4m1/pager-duty-js/issues/new?template=bug-report.md).
If you want to see new features or enhancements to the current ones, we would love to hear them. Please submit an issue on the GitHub repository [here](https://github.com/rod4n4m1/pager-duty-js/issues/new?template=new-feature.md).
Written by Rod Anami <rod.anami@kyndryl.com>, June 2022.
* None
This project is licensed under the [Eclipse Public License 2.0](https://opensource.org/licenses/EPL-2.0).
PagerDuty API usage follows the [PagerDuty Developer Agreement](https://developer.pagerduty.com/docs/ZG9jOjExMDI5NTg0-pager-duty-developer-agreement).