connectwise-rest 0.24.0 → 1.0.1

package/.eslintrc

@@ -1,59 +1,23 @@
-{
-  "env": {
-    "browser": false,
-    "node": true,
-    "es6": true
-  },
-  "extends": ["plugin:promise/recommended"],
-  "plugins": ["promise"],
-  "rules": {
-    "promise/avoid-new": "off",
-    "promise/no-nesting": "off",
-    "space-before-function-paren": 0,
-    "object-curly-spacing": 0,
-    "arrow-body-style": 0,
-    "linebreak-style": 0,
-    "consistent-return": "off",
-    "prefer-template": "warn",
-    "global-require": "off",
-    "no-case-declarations": "off",
-    "no-underscore-dangle": "off",
-    "no-var": "error",
-    "prefer-const": "error",
-    "one-var": ["error", "never"],
-    "template-curly-spacing": ["error", "never"],
-    "no-shadow": [
-      "error", {
-        "allow": [
-          "then", "catch", "done"
-        ]
-      }
-    ],
-    "max-len": [
-      "error", {
-        "code": 140,
-        "ignoreComments": true
-      }
-    ],
-    // use ide formatting
-    "indent": [
-      2, 2, {
-        "SwitchCase": 1
-      }
-    ],
-    "quotes": [
-      2, "single"
-    ],
-    "new-cap": 0,
-    "no-prototype-builtins": 0,
-    "no-restricted-syntax": [
-      "error", "WithStatement"
-    ],
-    "no-use-before-define": [
-      "error", {
-        "functions": false,
-        "classes": true
-      }
-    ]
-  }
-}
+{
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": "latest"
+  },
+  "plugins": ["@typescript-eslint", "prettier"],
+  "env": {
+    "node": true,
+    "mocha": true,
+    "es6": true
+  },
+  "extends": [
+    "plugin:@typescript-eslint/eslint-recommended",
+    "plugin:@typescript-eslint/recommended",
+    "plugin:prettier/recommended"
+  ],
+  "ignorePatterns": [
+    "dist",
+    "src/AutomateTypes.js",
+    "src/ManageTypes.js"
+  ],
+  "rules": {}
+}

package/.gitattributes

@@ -0,0 +1 @@
+*.json  linguist-language=JSON-with-Comments

package/.mocharc.json

@@ -0,0 +1,5 @@
+{
+  "timeout": 10000,
+  "ui": "bdd",
+  "extension": ["ts", "js"]
+}

package/.prettierrc

@@ -0,0 +1,7 @@
+{
+  "semi": false,
+  "trailingComma": "all",
+  "singleQuote": true,
+  "printWidth": 100,
+  "tabWidth": 2
+}

package/README.md

@@ -1,230 +1,293 @@
-# connectwise-rest
-
- [![npm version](https://img.shields.io/npm/v/connectwise-rest.svg)](https://www.npmjs.com/package/connectwise-rest) [![npm downloads](https://img.shields.io/npm/dt/connectwise-rest.svg)](https://www.npmjs.com/package/connectwise-rest) [![travis build](https://api.travis-ci.org/covenanttechnologysolutions/connectwise-rest.svg?branch=master)](https://travis-ci.org/covenanttechnologysolutions/connectwise-rest)
-
-A nodejs module for interacting with the ConnectWise REST API.   This module is currently under construction.  This module provides bindings for ease of development against the ConnectWise REST API. 
-
-## Requirements
-
-- ConnectWise 2018.1+, though these functions are written for ConnectWise 2016.1 APIs (API3.0 v1.0.0). 
-- ConnectWise API keys (available on ConnectWise 2015.3+), or API Only Member keys (only available on ConnectWise 2015.6+).  See the [documentation](https://developer.connectwise.com/Authentication) for more details. 
-
-## Documentation
-
-See the documentation [here](https://github.com/covenanttechnologysolutions/connectwise-rest/blob/master/doc.md)
-
-## Usage
-
-Create a new API key, or API Only Member, then instantiate the module.  
-
-```javascript
-    
-    const ConnectWiseRest = require('connectwise-rest');
-    
-    const cw = new ConnectWiseRest({
-        companyId: 'company',
-        companyUrl: 'your.connectwise.com',
-        publicKey: '<public key>',
-        privateKey: '<private key>',
-        clientId: '<your client id>',
-        entryPoint: 'v4_6_release', // optional, defaults to 'v4_6_release'
-        apiVersion: '3.0.0',        // optional, defaults to '3.0.0'
-        timeout: 20000,             // optional, request connection timeout in ms, defaults to 20000
-        retry: false,               // optional, defaults to false
-        retryOptions: {             // optional, override retry behavior, defaults as shown
-          retries: 4,               // maximum number of retries
-          minTimeout: 50,           // number of ms to wait between retries
-          maxTimeout: 20000,        // maximum number of ms between retries
-          randomize: true,          // randomize timeouts
-        },
-        debug: false,               // optional, enable debug logging
-        logger: (level, text, meta) => { } // optional, pass in logging function
-    });
-    
-    cw.ServiceDeskAPI.Tickets.getTicketById(1234)
-        .then((ticket) => {
-            //do something with results
-        })
-        .catch((error) => {
-            //handle errors
-        });
-```
-
-Or if you only require access to one API component:
-
-```javascript
-
-    const ConnectWiseRest = require('connectwise-rest');
-    
-    const tickets = new ConnectWiseRest(options).ServiceDeskAPI.Tickets;
-    
-    tickets.getTicketById(1234)
-        .then(function (result){
-            //do something with results
-        })
-        .catch(function (error){
-            //handle errors
-        });
-```
-
-You can also manually access the API:
-
-```javascript
-
-    const ConnectWiseRest = require('connectwise-rest');
-
-    const api = new ConnectWiseRest(options).API.api;
-
-    api('/path/to/api', 'POST', {
-        'param1': 'val1',
-        'param2': 'val2'
-    })
-    .then((result) => {
-        //do something with results
-    })
-    .catch((error) => {
-        //handle errors
-    });
-```
-
-### Cloud-Hosted ConnectWise Manage
-
-To access cloud-hosted ConnectWise, use the `companyUrl` of `api-na.myconnectwise.net` and override the default `entryPoint`.
-
-| Region | |
-| --- | --- |
-| North America | api-na.myconnectwise.net |
-| Europe | api-eu.myconnectwise.net |
-| Australia | api-aus.myconnectwise.net |
-| Demo | api-staging.connectwisedev.com |
-
-```javascript
-    options = {
-        companyId: 'company',
-        companyUrl: 'api-na.myconnectwise.net',
-        entryPoint: 'v2019_3', // change to the current hosted version 
-        publicKey: '<public key>',
-        privateKey: '<private key>'
-    }
-```
-
-## Implemented APIs
-
-| Module           | API                 | Status                        |
-| ---------------- | ------------------- | ----------------------------- |
-| Company API      | Companies           | Complete                      |
-| Company API      | CompanyTeams        | Complete                      |
-| Company API      | Configurations      | Complete                      |
-| Company API      | Contacts            | Complete                      |
-| Finance API      | Additions           | Complete                      |
-| Finance API      | Adjustments         | Complete                      |
-| Finance API      | Agreements          | Complete                      |
-| Finance API      | AgreementSites      | Complete                      |
-| Finance API      | BoardDefaults       | Complete                      |
-| Finance API      | WorkRoles           | Complete                      |
-| Finance API      | WorkTypeExclusions  | Complete                      |
-| Finance API      | WorkTypes           | Complete                      |
-| Project API      | Projects            | Complete                      |
-| ScheduleAPI      | ScheduleEntries     | Complete                      |
-| ScheduleAPI      | ScheduleTypes       | Complete                      |
-| Service Desk API | Boards              | Complete                      |
-| Service Desk API | BoardTeams          | Complete                      |
-| Service Desk API | Priorities          | Complete                      |
-| Service Desk API | ServiceNotes        | Complete                      |
-| Service Desk API | Statuses            | Complete                      |
-| Service Desk API | Tickets             | Complete                      |
-| System API       | Members             | Complete                      |
-| System API       | Reports             | Complete                      |
-| Time API         | TimeEntries         | Complete                      |
-
-
-## Examples
-
-### Code Examples
-
-Get ticket 1234 and print ticket number, summary and status. 
-
-```javascript
-
-    tickets.getTicketById(1234)
-        .then((ticket) => { console.log(ticket.id, ticket.summary, ticket.status.name); })
-        .catch((err) => { console.log(err); });
-```
-
-Create new ticket on service board, then print the returned ticket number, or any errors
-
-```javascript
-
-    tickets.createTicket({
-        summary: "This is the summary",
-        board: {
-            name: "Service Board"
-        },
-        company: {
-            identifier: "ABC" //company ID
-        },
-        initialDescription: "ticket description",
-        recordType: "ServiceTicket"
-        //can also pass in any other Ticket object settings as needed
-    })
-    .then((ticket) => { console.log(ticket.id); })
-    .catch((err) => { console.log(err); });    
-    
-```
-
-Change the status of a ticket
-
-```javascript
-
-    updateTicket(1234, [{
-        op: 'replace',
-        path: 'status',
-        value: {id: 123} //id of the status to change to, find with boards.getBoards and status.getStatuses
-    }, {
-        //second or more operations
-    }])
-    .then((res) => { //do something with returned ticket });
-    .catch((err) => { //do something with errors });    
-
-```
-
-### Conditions 
-
-Valid example conditions string:
-  
-```javascript
-
-    const conditions = '(contact/name like "Fred%" and closedFlag = false) and dateEntered > [2015-12-23T05:53:27Z] or summary contains "test" AND  summary != "Some Summary"'
-
-```
-
-Error message returned from server when invalid conditions are passed in:
-> Expected a boolean value, not a numeric. String values should be enclosed with double or single quotes; DateTime values should be enclosed in square brackets; numbers should consist of only digits, and optionally a decimal point and a negation sign; boolean values should be indicated with the keywords true or false; null values should be indicated by the keyword null.
-
-
-### Callbacks
-
-This library includes an express style callback middleware that will parse and verify the payload signature.
-
-```javascript 
-
-  const CWCallback = cw.utils.Callback;
-  
-  router.post('/your/callback', CWCallback.middleware((err, req, res, verified, payload) => {
-    if (err) {
-      //handle error, parsing, malformed object, etc
-      res.status(500).end();
-    } else if (!verified) {
-      // send 403 on verification failure, 
-      // or handle some other way
-      res.status(403).end();
-    } else {
-      res.status(200).end()
-    }
-    const {action, id} = req.query;
-    // do something with the payload
-  }));
-
-```
-
-See also using [verifyCallback](https://github.com/covenanttechnologysolutions/connectwise-rest/blob/master/doc.md#verifyCallback) manually.
+# connectwise-rest
+
+ [![npm version](https://img.shields.io/npm/v/connectwise-rest.svg)](https://www.npmjs.com/package/connectwise-rest) [![npm downloads](https://img.shields.io/npm/dt/connectwise-rest.svg)](https://www.npmjs.com/package/connectwise-rest) ![Node.js CI](https://github.com/covenanttechnologysolutions/connectwise-rest/actions/workflows/node.js.yml/badge.svg?branch=master)
+
+A Node.JS TypeScript module for interacting with the ConnectWise Manage and Automate REST APIs. 
+This module provides bindings for ease of development against the ConnectWise REST APIs as well as pagination, automatic retries and logging.   
+
+###  ⚠️Breaking Changes ⚠️
+
+Version 1.0 has been completely re-written and is automatically generated, some function names have changed as well as removal of subsections from version 0.x.  Pagination API has been changed for easier usage.   VSCode, JetBrains, etc editors will automatically pick up the new type definitions.  
+
+## Table of Contents
+
+- [Requirements](#requirements)
+  - [Manage](#manage)
+  - [Automate](#automate)
+- [Documentation](#documentation)
+- [Usage](#usage)
+  - [Manage Usage](#manage-usage)
+  - [Automate Usage](#automate-usage)
+  - [Pagination](#pagination)
+  - [APIs Without Typings](#apis-without-typings)
+  - [Cloud-Hosted ConnectWise Manage](#cloud-hosted-connectwise-manage)
+- [Examples](#examples)
+  - [Sample Project](#sample-project)
+  - [Code Examples](#code-examples)
+  - [Manage Conditions Example](#manage-conditions-example)
+  - [Manage Callbacks](#manage-callbacks)
+
+## Requirements
+
+### Manage 
+
+- ConnectWise Manage 2018.1+, though these functions are written for ConnectWise Manage 2021.1 APIs.
+- ConnectWise Manage API keys (available on ConnectWise 2015.3+), or API Only Member keys (only available on ConnectWise 2015.6+).  See the [documentation](https://developer.connectwise.com/Authentication) for more details.
+
+### Automate
+
+- ConnectWise Automate 2020+
+- ConnectWise Automate integrator login, your own generated token, or user account with 2FA.
+
+## Documentation
+
+See the full documentation [here](https://covenanttechnologysolutions.github.io/connectwise-rest/index.html)
+
+## Usage
+
+### Manage Usage
+
+```javascript
+// ESM
+import { AutomateAPI } from 'connectwise-rest';
+// CommonJS
+const { AutomateAPI } = require('connectwise-rest');
+
+const cwm = new ManageAPI({
+  companyId: 'company',
+  companyUrl: 'your.connectwise.com',
+  publicKey: '<public key>',
+  privateKey: '<private key>',
+  clientId: '<your client id>',
+  entryPoint: 'v4_6_release', // optional, defaults to 'v4_6_release'
+  apiVersion: '3.0.0',        // optional, defaults to '3.0.0'
+  timeout: 20000,             // optional, request connection timeout in ms, defaults to 20000
+  retry: false,               // optional, defaults to false
+  retryOptions: {             // optional, override retry behavior, defaults as shown
+    retries: 4,               // maximum number of retries
+    minTimeout: 50,           // number of ms to wait between retries
+    maxTimeout: 20000,        // maximum number of ms between retries
+    randomize: true,          // randomize delay between retries on timeouts
+  },
+  debug: false,               // optional, enable debug logging
+  logger: (level, text, meta) => { } // optional, pass in logging function
+});
+
+cwm.ServiceDeskAPI.Tickets.getTicketById(1234)
+  .then((ticket) => {
+      //do something with results
+  })
+  .catch((error) => {
+      //handle errors
+  });
+```
+
+
+### Automate Usage
+
+```javascript
+// ESM
+import { AutomateAPI } from 'connectwise-rest';
+// CommonJS
+const { AutomateAPI } = require('connectwise-rest');
+
+const cwa = new ManageAPI({
+  companyId: 'company',
+  serverUrl: 'your.connectwise.com',
+  clientId: '<your client id>',
+  // One of the following: integrator username and password or username, password and two-factor code
+  // integrator username/password:
+  username: '<username>',
+  password: '<private key>',
+  
+  // also pass in two factor passcode if not using an integrator account
+  twoFactorPasscode: '<2fa code>',
+
+  timeout: 20000,             // optional, request connection timeout in ms, defaults to 20000
+  retry: false,               // optional, defaults to false
+  retryOptions: {             // optional, override retry behavior, defaults as shown
+    retries: 4,               // maximum number of retries
+    minTimeout: 50,           // number of ms to wait between retries
+    maxTimeout: 20000,        // maximum number of ms between retries
+    randomize: true,          // randomize delay between retries on timeouts
+  },
+  debug: false,               // optional, enable debug logging
+  logger: (level, text, meta) => { } // optional, pass in logging function
+});
+
+cwa.ComputersAPI.getComputerList()
+  .then((computers) => {
+      //do something with results
+  })
+  .catch((error) => {
+      //handle errors
+  });
+```
+
+### Pagination
+
+Use the pagination function to automatically fetch all records in order that match the request.  
+
+Note: the last argument to the pagination function must be an object, or an error will be thrown.  
+
+```javascript
+const cwa = new ManageAPI()
+const cwm = new AutomateAPI()
+
+// use the instantiated ManageAPI or AutomateAPI
+cwm.paginate(
+  cwm.ServiceAPI.getServiceTickets,   // pass in the api function to be paginated
+  {startPage: 10, pageSize: 500},     // pagination options, defaults to startPage 1, pageSize 1000
+  {}                                  // additional arguments to the api function as needed                            
+)
+  .then(results => { ... })
+  .catch(error => { ... })
+
+```
+
+### APIs Without Typings
+
+You can also manually access the API without typings:
+
+```javascript
+
+    const { Manage, Automate } = require('connectwise-rest');
+
+    const cwm = new Manage(CWMOptions);
+    const cwa = new Automate(CWAOptions);
+    
+    // use cwa.request or cwm.request
+    cwm.request({
+      path: '/path/to/api',
+      method: 'POST', 
+      params: {
+        'queryParam1': 'val1',
+        'queryParam2': 'val2'
+      },
+      data: {
+        'dataValue': 'val1',
+    })
+      .then((result) => {
+          //do something with results
+      })
+      .catch((error) => {
+          //handle errors
+      });
+```
+
+### Cloud-Hosted ConnectWise Manage
+
+To access cloud-hosted ConnectWise, use the `companyUrl` of `api-na.myconnectwise.net` and override the default `entryPoint`.
+
+| Region | URL                            |
+| --- |--------------------------------|
+| North America | api-na.myconnectwise.net       |
+| Europe | api-eu.myconnectwise.net       |
+| Australia | api-aus.myconnectwise.net      |
+| Demo | api-staging.connectwisedev.com |
+
+```javascript
+    options = {
+        companyId: 'company',
+        companyUrl: 'api-na.myconnectwise.net',
+        entryPoint: 'v2022.1', // change to the current hosted version 
+        publicKey: '<public key>',
+        privateKey: '<private key>'
+    }
+```
+
+## Examples
+
+### Sample Project
+
+See [the sample project here](https://github.com/k-grube/cw-micro).  This is a simple node.js express based API. 
+
+### Code Examples
+
+Get ticket 1234 and print ticket number, summary and status. 
+
+```javascript
+
+    cwm.ServiceAPI.getServiceTicketsById(1234)
+        .then((ticket) => { console.log(ticket.id, ticket.summary, ticket.status.name); })
+        .catch((err) => { console.log(err); });
+```
+
+Create new ticket on service board, then print the returned ticket number, or any errors
+
+```javascript
+    cwm.ServiceAPI.postServiceTickets({
+      summary: "This is the summary",
+      board: {
+          name: "Service Board"
+      },
+      company: {
+          identifier: "ABC" //company ID
+      },
+      initialDescription: "ticket description",
+      recordType: "ServiceTicket"
+      //can also pass in any other Ticket object settings as needed
+    })
+    .then((ticket) => { console.log(ticket.id); })
+    .catch((err) => { console.log(err); });    
+    
+```
+
+Change the status of a ticket
+
+```javascript
+    cwa.ServiceAPI.patchServiceTicketsById(1234, [{
+        op: 'replace',
+        path: 'status',
+        value: {id: 123} //id of the status to change to, find with boards.getBoards and status.getStatuses
+    }, {
+        //second or more operations
+    }])
+    .then((res) => { 
+      //do something with returned ticket 
+    })
+    .catch((err) => { 
+      //do something with errors 
+    });    
+
+```
+
+### Manage Conditions Example
+
+Valid example conditions string:
+  
+```javascript
+
+    const conditions = '(contact/name like "Fred%" and closedFlag = false) and dateEntered > [2015-12-23T05:53:27Z] or summary contains "test" AND  summary != "Some Summary"'
+
+```
+
+Error message returned from server when invalid conditions are passed in:
+> Expected a boolean value, not a numeric. String values should be enclosed with double or single quotes; DateTime values should be enclosed in square brackets; numbers should consist of only digits, and optionally a decimal point and a negation sign; boolean values should be indicated with the keywords true or false; null values should be indicated by the keyword null.
+
+
+### Manage Callbacks
+
+This library includes an express style callback middleware that will parse and verify the payload signature.
+
+```javascript
+  const {utils} = require('connectwise-rest')
+  const CWCallback = utils.Callback;
+  
+  router.post('/your/callback', CWCallback.middleware((err, req, res, verified, payload) => {
+    if (err) {
+      //handle error, parsing, malformed object, etc
+      res.status(500).end();
+    } else if (!verified) {
+      // send 403 on verification failure, 
+      // or handle some other way
+      res.status(403).end();
+    } else {
+      res.status(200).end()
+    }
+    const {action, id} = req.query;
+    // do something with the payload
+  }));
+
+```
+