kmartin-215/node-pagerduty

⛔️ DEPRECATED - PagerDuty v2 API Wrapper for Node

DEPRECATED

Please begin using the official PagerDuty repository located here https://github.com/PagerDuty/pdjs

Installation

npm install --save node-pagerduty

The --save tells NPM to automatically add it to your package.json file

Usage

// Import a module
const pdClient = require('node-pagerduty');

const pdapiToken = 'yourapiTokenGoesHere';
const pd = new pdClient(pdapiToken);

let yourId = 'yourScheduleIdGoesHere';
let yourQs = {
   time_zone: 'UTC',
   since: 'yourSince',
   until: 'yourUntil'
};

// Using it to get things done

pd.schedules.getSchedule(yourId, yourQs)
   .then(res => {
      console.log(res);
   })
   .catch(err => {
      console.log(err);
   });

OAuth Bearer Tokens

This library also supports the usage of Bearer tokens generated by OAuth2. To initialize a new pdClient with a Bearer token simply pass a second argument of Bearer for the token type. The whole call would look something like this:

const pd = new pdClient(pdapiToken, 'Bearer');

Optional Request Parameters

You can override or add to the request options, allowing for things such as proxying or setting a higher timeout for slower connections. This parameter is optional.

const myCustomOptions = {
    "proxy": "https://proxy.example.com",
    "headers": {
        "Proxy-Authorization": "Basic xxxxxxxxxxxx",
        "dont-send-to-proxy": "ok",
        "dont-send-to-dest": "ok"
    },
    "timeout": 10000
};

const pd = new pdClient(pdapiToken, null, myCustomOptions)

Methods

All methods follow the official API documentation.

This is a promise based library: (fullfilled, rejected)

Abilities

https://v2.developer.pagerduty.com/v2/page/api-reference#!/Abilities

abilities.listAbilities()
abilities.testAbility(id)

Add-Ons

https://v2.developer.pagerduty.com/v2/page/api-reference#!/Add-ons

addOns.listAddOns(qs)
addOns.installAddOn(payload)
addOns.deleteAddOn(id)
addOns.getAddOn(id)
addOns.updateAddOn(id, payload)

Analytics

https://developer.pagerduty.com/api-reference/reference/REST/openapiv3.json/paths/~1analytics~1raw~1incidents~1%7Bid%7D/get

analytics.getIncidentData(id)
analytics.getIncidentsData()

Business Services

https://developer.pagerduty.com/api-reference/reference/REST/openapiv3.json/paths/~1business_services/get

businessServices.listBusinessServices(qs)
businessServices.createBusinessService(payload)
businessServices.deleteBusinessService(id)
businessServices.getBusinessService(id)
businessServices.updateBusinessService(id, payload)

Contextual Search

https://api-reference.pagerduty.com/#!/Contextual_Search

contextualSearch.listTags(qs)
contextualSearch.createTag(payload)
contextualSearch.deleteTag(id)
contextualSearch.getTag(id)
contextualSearch.getConnectedEntities(id, entity_type)
contextualSearch.assignTags(entity_type, id, payload)

Escalation Policies

https://v2.developer.pagerduty.com/v2/page/api-reference#!/Escalation_Policies

escalationPolicies.listEscalationPolicies(qs)
escalationPolicies.createEscalationPolicy(from, payload)
escalationPolicies.deleteEscalationPolicy(id)
escalationPolicies.getEscalationPolicy(id, qs)
escalationPolicies.updateEscalationPolicy(id, payload)

Event Rules

Note: Event Rules endpoint does not work with Bearer tokens. Only Token tokens https://v2.developer.pagerduty.com/docs/global-event-rules-api

eventRules.listEventRules()
eventRules.createEventRule(id, payload)
eventRules.deleteEventRule(id)
eventRules.updateEventRule(id, payload)

Extension Schemas

https://v2.developer.pagerduty.com/v2/page/api-reference#!/Extension_Schemas

extensionSchemas.listExtensionSchemas()
extensionSchemas.getExtensionVendor(id)

Extensions

https://v2.developer.pagerduty.com/v2/page/api-reference#!/Extensions

extensions.listExtensions(qs)
extensions.createExtension(payload)
extensions.deleteExtension(id)
extensions.getExtension(id, qs)
extensions.updateExtension(id, payload)

Events

https://v2.developer.pagerduty.com/docs/send-an-event-events-api-v2

events.sendEvent(payload)

Incidents

https://v2.developer.pagerduty.com/v2/page/api-reference#!/Incidents

incidents.listIncidents(qs)
incidents.createIncident(from, payload)
incidents.manageIncident(from, payload)
incidents.mergeIncidents(id, from, payload)
incidents.getIncident(id)
incidents.updateIncident(id, from, payload)
incidents.listAlerts(id, qs)
incidents.manageAlerts(id, from, payload)
incidents.getAlert(id, alert_id)
incidents.updateAlert(id, alert_id, from, payload)
incidents.listLogEntries(id, qs)
incidents.listNotes(id)
incidents.createNote(id, from, payload)
incidents.createStatusUpdate(id, from, payload)
incidents.createResponderRequest(id, from, payload)
incidents.snoozeIncident(id, from, payload)

Priorities

https://v2.developer.pagerduty.com/v2/page/api-reference#!/Priorities

priorities.listPriorities()

Response Plays

https://v2.developer.pagerduty.com/v2/page/api-reference#!/Response_Plays

responsePlays.createResponseReplay(payload)
responsePlays.deleteResponseReplay(id)
responsePlays.getResponseReplay(id)
responsePlays.listResponseReplay(qs)
responsePlays.runResponsePlay(id, from, payload)
responsePlays.updateResponseReplay(id, payload)

Log Entries

https://v2.developer.pagerduty.com/v2/page/api-reference#!/Log_Entries

logEntries.listLogEntries(qs)
logEntries.getLogEntry(id, qs)

Maintenance Windows

https://v2.developer.pagerduty.com/v2/page/api-reference#!/Maintenance_Windows

maintenanceWindows.listMaintenanceWindows(qs)
maintenanceWindows.createMaintenanceWindow(from, payload)
maintenanceWindows.deleteMaintenanceWindow(id)
maintenanceWindows.getMaintenanceWindow(id, qs)
maintenanceWindows.updateMaintenanceWindow(id, payload)

Notifications

https://v2.developer.pagerduty.com/v2/page/api-reference#!/Notifications

notifications.listNotifications(qs)

On-Calls

https://v2.developer.pagerduty.com/v2/page/api-reference#!/On-Calls

onCalls.listAllOnCalls(qs)

Rulesets

https://developer.pagerduty.com/api-reference/reference/REST/openapiv3.json/paths/~1rulesets/get

rulesets.listRulesets(qs)
rulesets.getRuleset(id)
rulesets.createRuleset(payload)
rulesets.updateRuleset(id, payload)
rulesets.deleteRuleset(id)
rulesets.listRulesetRules(id, qs)
rulesets.createRulesetRule(id, payload)
rulesets.getRulesetRule(rulesetId, ruleId)
rulesets.deleteRulesetRule(rulesetId, ruleId)
rulesets.updateRulesetRule(rulesetId, ruleId, payload)

Schedules

https://v2.developer.pagerduty.com/v2/page/api-reference#!/Schedules

schedules.listSchedule(qs)
schedules.createSchedule(payload)
schedules.previewSchedule(qs, payload)
schedules.deleteSchedule(id)
schedules.getSchedule(id, qs)
schedules.updateSchedule(id, qs, payload)
schedules.listOverrides(id, qs)
schedules.createOverride(id, payload)
schedules.deleteOverride(id, override_id)
schedules.listUsersOnCall(id, qs)

Service Dependencies

https://developer.pagerduty.com/api-reference/reference/REST/openapiv3.json/paths/~1service_dependencies~1associate/post

serviceDependencies.associateDependencies(payload)
serviceDependencies.disassociateDependencies(payload)
serviceDependencies.getBusinessServiceDependencies(id)
serviceDependencies.getTechnicalServiceDependencies(id)

Services

https://v2.developer.pagerduty.com/v2/page/api-reference#!/Services

services.listServices(qs)
services.createService(payload)
services.deleteService(id)
services.getService(id, qs)
services.updateService(id, payload)
services.createIntegration(id, payload)
services.viewIntegration(id, integration_id)
services.updateIntegration(id, integration_id, payload)

Teams

https://v2.developer.pagerduty.com/v2/page/api-reference#!/Teams

teams.listTeams(qs)
teams.createTeam(payload)
teams.deleteTeam(id, qs)
teams.getTeam(id, qs)
teams.updateTeam(id, payload)
teams.getTeamMembers(id, qs)
teams.removeEscalationPolicy(id, policy_id)
teams.addEscalationPolicy(id, policy_id)
teams.removeUser(id, user_id)
teams.addUser(id, user_id, payload)

Users

https://v2.developer.pagerduty.com/v2/page/api-reference#!/Users

users.listUsers(qs)
users.createUser(from, payload)
users.deleteUser(id)
users.getUser(id, qs)
users.updateUser(id, payload)
users.getCurrentUser(qs)
users.listContactMethods(id)
users.createContactMethod(id, payload)
users.deleteContactMethod(id, contact_method_id)
users.getContactMethod(id, contact_method_id)
users.updateContactMethod(id, contact_method_id, payload)
users.listNotificationRules(id, qs)
users.createNotificationRule(id, payload)
users.deleteNotificationRule(id, rule_id)
users.getNotificationRule(id, rule_id, qs)
users.updateNotificationRule(id, rule_id, payload)
users.deleteAllUserSessions(id)
users.listUserActiveSessions(id)
users.deleteUsersSession(id, type, session_id)
users.getUsersSession(id, type, session_id)

Vendors

https://v2.developer.pagerduty.com/v2/page/api-reference#!/Vendors

vendors.listVendors()
vendors.getVendor(id)

License

MIT license. See the LICENSE file for details.

node-pagerduty's Issues

Passing an array to the querystring

Hi there,

Thanks for putting this together!

Having a small issue with the incidents.listIncidents endpoint (PD docs), when trying to pass through statuses. PagerDuty needs them passed through as an array, but I can't figure out how to pass them in a format that will be appropriately encoded (statuses[]=triggered) by Node's querystring library, which is being used here.

I'm not sure if I'm missing something obvious... or whether another querystring helper library might be required instead?

What I've tried

pagerDuty.incidents.listIncidents({ statuses: 'triggered' })

• value of qs after line 34 in pd.js: ?statuses=triggered
• response from PagerDuty: Invalid Input Provided / error 2001 / Statuses must be a Array.

pagerDuty.incidents.listIncidents({ statuses: ['triggered'] })

• value of qs after line 34 in pd.js: ?statuses=triggered
• response from PagerDuty: Invalid Input Provided / error 2001 / Statuses must be a Array.

pagerDuty.incidents.listIncidents({ statuses: "['triggered']" })

• value of qs after line 34 in pd.js: ?statuses=%5B'triggered'%5D
• response from PagerDuty: Invalid Input Provided / error 2001 / Statuses must be a Array.

pagerDuty.incidents.listIncidents( "statuses[]=triggered" )

• value of qs after line 34 in pd.js: ?
• response from PagerDuty: all of my incidents ;)

What I'm looking for

• value of qs after line 34 in pd.js: ?statuses[]=triggered
• response from PagerDuty: hopefully a list of just triggered incidents 😄

Is there something else I haven't thought of... or otherwise something else this library can do to help these through to the querystring sent to PagerDuty?

For instance, it looks like query-string provides an arrayFormat option which might fix this issue: https://www.npmjs.com/package/query-string#arrayformat-1

API key is shared and overwritten between clients

Is there a specific reason the api key needs to be stored in the global variable myKey? This means that if I create two instances of Client with two different API keys, they'll both end up using the key for whichever was most recently created.

This is normally the kind of thing that would be stored in an instance property for exactly this reason. For instance:

function Client(apiKey) {
    this.apiKey = apiKey
}
Client.prototype.foo = function () {
    doSomethingWith(this.apiKey)
}

Add typescript types for the API

I have created type definition file for your library because I needed one. Not sure if you want to integrate it into your library or I can add it to the DefinitelyTypes repo. Right now I'm using it locally to my own ts application but thought it might help some other folks.

Typescript definition file:
https://github.com/NexusSwitchboard/nexus-mod-service/blob/master/src/%40types/node-pagerduty/index.d.ts

sendEvent() does not check for error responses

When a request is made to the Pagerduty API with the Client.prototype.events.sendEvent method, and the request fails, at least in some cases, the method still returns a promise that fulfills, seeming to indicate success. In one instance, I sent a badly formed event and pagerduty sent back a 400 response indicating the error. In my opinion, the sendEvent method should have given me a Promise that rejected with some kind of error indicating the response, so I would know that my event had not been accepted.

There is a workaround, but it requires the calling code to inspect every response on their own, which is undesirable, imo.

I don't know if this is pervasive through out the package, but I would imagine it is. I also don't know what other errors it is masking in a similar way (e.g., if 5xx series responses would be treated any differently).

As a possible solution, if you use a library such as axios to make the requests, it will treat an error-indicating status codes as errors and return a promise that rejects.

Make timeout configurable for request

I find myself on a slower network and that a longer request, like that for a list of schedules takes longer to retrieve.
Currently the timeout is set to:
timeout: 5000

I would like for this to be configurable, ex:
timeout: options.timeout || 5000

Unable to search for users on a team

According to the API Reference there is a way to get a list of users on a team. But this functionality is not yet exposed by this module, only adding and removing users from a team.

several npm warnings when installing ^1.1.0

given

    "dependencies": {
        "node-pagerduty": "^1.1.0",
    }

I get warnings about a request library that is not installed by default which is a bit confusing

npm i
npm WARN [email protected] requires a peer of request@^2.34 but none is installed. You must install peer dependencies yourself.
npm WARN [email protected] requires a peer of request@^2.34 but none is installed. You must install peer dependencies yourself.

after manually adding "request": "^2.88.0" to my dependencies

I see the following warnings

found 8 moderate severity vulnerabilities
  run `npm audit fix` to fix them, or `npm audit` for details

most of these seem to relate to node-pagerduty > request > hawk

I'm newish to node dependency management. Are these warnings expected?

Unable to add a User to a Team with a particular Role

For adding a User to a Team, the PagerDuty API Reference specifies an optional parameter, role, with the description Can be observer, responder or manager. However, there isn't a way currently to define this using this API:

https://github.com/kmart2234/node-pagerduty/blob/master/lib/pd.js#L861