Add pagination function, update docs

covenanttechnologysolutions · Apr 5, 2022 · 0395d6f · 0395d6f
1 parent bd50256
commit 0395d6f
Show file tree

Hide file tree

Showing 7 changed files with 324 additions and 153 deletions.
diff --git a/README.md b/README.md
@@ -1,8 +1,31 @@
 # 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)
+ [![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. 
+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
 
@@ -22,7 +45,7 @@ See the full documentation [here](https://covenanttechnologysolutions.github.io/
 
 ## Usage
 
-### Manage
+### Manage Usage
 
 ```javascript
 // ESM
@@ -44,7 +67,7 @@ const cwm = new ManageAPI({
     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
+    randomize: true,          // randomize delay between retries on timeouts
   },
   debug: false,               // optional, enable debug logging
   logger: (level, text, meta) => { } // optional, pass in logging function
@@ -60,7 +83,7 @@ cwm.ServiceDeskAPI.Tickets.getTicketById(1234)
 ```
 
 
-### Automate
+### Automate Usage
 
 ```javascript
 // ESM
@@ -72,12 +95,12 @@ const cwa = new ManageAPI({
   companyId: 'company',
   serverUrl: 'your.connectwise.com',
   clientId: '<your client id>',
-  // One of the following: token, integrator username and password or username, password and two-factor code
-  token: '<bearer token>',
-
-  // or integrator username/password:
+  // 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
@@ -86,7 +109,7 @@ const cwa = new ManageAPI({
     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
+    randomize: true,          // randomize delay between retries on timeouts
   },
   debug: false,               // optional, enable debug logging
   logger: (level, text, meta) => { } // optional, pass in logging function
@@ -101,6 +124,27 @@ cwa.ComputersAPI.getComputerList()
   });
 ```
 
+### 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:
@@ -222,7 +266,7 @@ 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
+### Manage Callbacks
 
 This library includes an express style callback middleware that will parse and verify the payload signature.
 
@@ -246,3 +290,4 @@ This library includes an express style callback middleware that will parse and v
   }));
 
 ```
+
diff --git a/package.json b/package.json
@@ -20,9 +20,9 @@
     "lint": "npx eslint -c .eslintrc --fix",
     "coveralls": "npx nyc report --reporter=text-lcov > ./.nyc_output/lcov.info",
     "pretypedocs": "npm run clean:docs",
-    "typedocs": "npx typedoc src/index.ts --listInvalidSymbolLinks",
-    "predocs": "npx api-extractor run --local --verbose",
-    "docs": "npx api-documenter markdown --input-folder temp --output-folder docs",
+    "docs": "npx typedoc src/index.ts",
+    "preapidocumenter": "npx api-extractor run --local --verbose",
+    "apidocumenter": "npx api-documenter markdown --input-folder temp --output-folder docs",
     "gh-pages": "npx gh-pages -d docs"
   },
   "repository": {

diff --git a/src/Automate.ts b/src/Automate.ts
@@ -140,18 +140,6 @@ export default class Automate {
     return result.data
   }
 
-  static async refreshToken({
-    username,
-    password,
-    serverUrl,
-  }: {
-    username: string
-    password: string
-    serverUrl: string
-  }) {
-    // @todo how
-  }
-
   async verifyToken() {
     try {
       const result = await this.api({ path: '/api/v1/FeatureFlags', method: 'get' })

diff --git a/src/AutomateAPI.ts b/src/AutomateAPI.ts
@@ -1,24 +1,44 @@
 import Automate from './Automate'
 import { CWLogger, RetryOptions } from './types'
-import * as AVTemplatePolicies from './Automate/AVTemplatePoliciesAPI'
-import * as Clients from './Automate/ClientsAPI'
-import * as Commands from './Automate/CommandsAPI'
-import * as Computers from './Automate/ComputersAPI'
-import * as Contacts from './Automate/ContactsAPI'
-import * as DataViews from './Automate/DataViewsAPI'
-import * as Drives from './Automate/DrivesAPI'
-import * as EventLogs from './Automate/EventLogsAPI'
-import * as Locations from './Automate/LocationsAPI'
-import * as MaintenanceWindowDefinitions from './Automate/MaintenanceWindowDefinitionsAPI'
-import * as Monitors from './Automate/MonitorsAPI'
-import * as NetworkDevices from './Automate/NetworkDevicesAPI'
-import * as Patching from './Automate/PatchingAPI'
-import * as RemoteAgent from './Automate/RemoteAgentAPI'
-import * as Scripting from './Automate/ScriptingAPI'
-import * as Searches from './Automate/SearchesAPI'
-import * as System from './Automate/SystemAPI'
-import * as Ticket from './Automate/TicketsAPI'
-import * as UserProfiles from './Automate/UserProfilesAPI'
+import { AVTemplatePoliciesAPI } from './Automate/AVTemplatePoliciesAPI'
+import { ClientsAPI } from './Automate/ClientsAPI'
+import { CommandsAPI } from './Automate/CommandsAPI'
+import { ComputersAPI } from './Automate/ComputersAPI'
+import { ContactsAPI } from './Automate/ContactsAPI'
+import { DataViewsAPI } from './Automate/DataViewsAPI'
+import { DrivesAPI } from './Automate/DrivesAPI'
+import { EventLogsAPI } from './Automate/EventLogsAPI'
+import { LocationsAPI } from './Automate/LocationsAPI'
+import { MaintenanceWindowDefinitionsAPI } from './Automate/MaintenanceWindowDefinitionsAPI'
+import { MonitorsAPI } from './Automate/MonitorsAPI'
+import { NetworkDevicesAPI } from './Automate/NetworkDevicesAPI'
+import { PatchingAPI } from './Automate/PatchingAPI'
+import { RemoteAgentAPI } from './Automate/RemoteAgentAPI'
+import { ScriptingAPI } from './Automate/ScriptingAPI'
+import { SearchesAPI } from './Automate/SearchesAPI'
+import { SystemAPI } from './Automate/SystemAPI'
+import { TicketsAPI } from './Automate/TicketsAPI'
+import { UserProfilesAPI } from './Automate/UserProfilesAPI'
+
+import type * as AVTemplatePoliciesAPITypes from './Automate/AVTemplatePoliciesAPI'
+import type * as ClientsAPITypes from './Automate/ClientsAPI'
+import type * as CommandsAPITypes from './Automate/CommandsAPI'
+import type * as ComputersAPITypes from './Automate/ComputersAPI'
+import type * as ContactsAPITypes from './Automate/ContactsAPI'
+import type * as DataViewsAPITypes from './Automate/DataViewsAPI'
+import type * as DrivesAPITypes from './Automate/DrivesAPI'
+import type * as EventLogsAPITypes from './Automate/EventLogsAPI'
+import type * as LocationsAPITypes from './Automate/LocationsAPI'
+import type * as MaintenanceWindowDefinitionsAPITypes from './Automate/MaintenanceWindowDefinitionsAPI'
+import type * as MonitorsAPITypes from './Automate/MonitorsAPI'
+import type * as NetworkDevicesAPITypes from './Automate/NetworkDevicesAPI'
+import type * as PatchingAPITypes from './Automate/PatchingAPI'
+import type * as RemoteAgentAPITypes from './Automate/RemoteAgentAPI'
+import type * as ScriptingAPITypes from './Automate/ScriptingAPI'
+import type * as SearchesAPITypes from './Automate/SearchesAPI'
+import type * as SystemAPITypes from './Automate/SystemAPI'
+import type * as TicketsAPITypes from './Automate/TicketsAPI'
+import type * as UserProfilesAPITypes from './Automate/UserProfilesAPI'
 
 /**
  * @public
@@ -86,49 +106,48 @@ class AutomateAPI extends Automate {
   /**
    * @public
    */
-  AVTemplatePoliciesAPI: AVTemplatePolicies.AVTemplatePoliciesAPI
-  ClientsAPI: Clients.ClientsAPI
-  CommandsAPI: Commands.CommandsAPI
-  ComputersAPI: Computers.ComputersAPI
-  ContactsAPI: Contacts.ContactsAPI
-  DataViewsAPI: DataViews.DataViewsAPI
-  DrivesAPI: Drives.DrivesAPI
-  EventLogsAPI: EventLogs.EventLogsAPI
-  LocationsAPI: Locations.LocationsAPI
-  MaintenanceWindowDefinitionsAPI: MaintenanceWindowDefinitions.MaintenanceWindowDefinitionsAPI
-  MonitorsAPI: Monitors.MonitorsAPI
-  NetworkDevicesAPI: NetworkDevices.NetworkDevicesAPI
-  PatchingAPI: Patching.PatchingAPI
-  RemoteAgentAPI: RemoteAgent.RemoteAgentAPI
-  ScriptingAPI: Scripting.ScriptingAPI
-  SearchesAPI: Searches.SearchesAPI
-  SystemAPI: System.SystemAPI
-  TicketsAPI: Ticket.TicketsAPI
-  UserProfilesAPI: UserProfiles.UserProfilesAPI
+  AVTemplatePoliciesAPI: AVTemplatePoliciesAPI
+  ClientsAPI: ClientsAPI
+  CommandsAPI: CommandsAPI
+  ComputersAPI: ComputersAPI
+  ContactsAPI: ContactsAPI
+  DataViewsAPI: DataViewsAPI
+  DrivesAPI: DrivesAPI
+  EventLogsAPI: EventLogsAPI
+  LocationsAPI: LocationsAPI
+  MaintenanceWindowDefinitionsAPI: MaintenanceWindowDefinitionsAPI
+  MonitorsAPI: MonitorsAPI
+  NetworkDevicesAPI: NetworkDevicesAPI
+  PatchingAPI: PatchingAPI
+  RemoteAgentAPI: RemoteAgentAPI
+  ScriptingAPI: ScriptingAPI
+  SearchesAPI: SearchesAPI
+  SystemAPI: SystemAPI
+  TicketsAPI: TicketsAPI
+  UserProfilesAPI: UserProfilesAPI
 
   constructor(options: CWAOptions) {
     super(options)
 
-    this.AVTemplatePoliciesAPI = new AVTemplatePolicies.AVTemplatePoliciesAPI(options)
-    this.ClientsAPI = new Clients.ClientsAPI(options)
-    this.CommandsAPI = new Commands.CommandsAPI(options)
-    this.ComputersAPI = new Computers.ComputersAPI(options)
-    this.ContactsAPI = new Contacts.ContactsAPI(options)
-    this.DataViewsAPI = new DataViews.DataViewsAPI(options)
-    this.DrivesAPI = new Drives.DrivesAPI(options)
-    this.EventLogsAPI = new EventLogs.EventLogsAPI(options)
-    this.LocationsAPI = new Locations.LocationsAPI(options)
-    this.MaintenanceWindowDefinitionsAPI =
-      new MaintenanceWindowDefinitions.MaintenanceWindowDefinitionsAPI(options)
-    this.MonitorsAPI = new Monitors.MonitorsAPI(options)
-    this.NetworkDevicesAPI = new NetworkDevices.NetworkDevicesAPI(options)
-    this.PatchingAPI = new Patching.PatchingAPI(options)
-    this.RemoteAgentAPI = new RemoteAgent.RemoteAgentAPI(options)
-    this.ScriptingAPI = new Scripting.ScriptingAPI(options)
-    this.SearchesAPI = new Searches.SearchesAPI(options)
-    this.SystemAPI = new System.SystemAPI(options)
-    this.TicketsAPI = new Ticket.TicketsAPI(options)
-    this.UserProfilesAPI = new UserProfiles.UserProfilesAPI(options)
+    this.AVTemplatePoliciesAPI = new AVTemplatePoliciesAPI(options)
+    this.ClientsAPI = new ClientsAPI(options)
+    this.CommandsAPI = new CommandsAPI(options)
+    this.ComputersAPI = new ComputersAPI(options)
+    this.ContactsAPI = new ContactsAPI(options)
+    this.DataViewsAPI = new DataViewsAPI(options)
+    this.DrivesAPI = new DrivesAPI(options)
+    this.EventLogsAPI = new EventLogsAPI(options)
+    this.LocationsAPI = new LocationsAPI(options)
+    this.MaintenanceWindowDefinitionsAPI = new MaintenanceWindowDefinitionsAPI(options)
+    this.MonitorsAPI = new MonitorsAPI(options)
+    this.NetworkDevicesAPI = new NetworkDevicesAPI(options)
+    this.PatchingAPI = new PatchingAPI(options)
+    this.RemoteAgentAPI = new RemoteAgentAPI(options)
+    this.ScriptingAPI = new ScriptingAPI(options)
+    this.SearchesAPI = new SearchesAPI(options)
+    this.SystemAPI = new SystemAPI(options)
+    this.TicketsAPI = new TicketsAPI(options)
+    this.UserProfilesAPI = new UserProfilesAPI(options)
   }
 }
 
@@ -137,23 +156,23 @@ class AutomateAPI extends Automate {
  */
 export default AutomateAPI
 export type {
-  AVTemplatePolicies,
-  Clients,
-  Commands,
-  Computers,
-  Contacts,
-  DataViews,
-  Drives,
-  EventLogs,
-  Locations,
-  MaintenanceWindowDefinitions,
-  Monitors,
-  NetworkDevices,
-  Patching,
-  RemoteAgent,
-  Scripting,
-  Searches,
-  System,
-  Ticket,
-  UserProfiles,
+  AVTemplatePoliciesAPITypes,
+  ClientsAPITypes,
+  CommandsAPITypes,
+  ComputersAPITypes,
+  ContactsAPITypes,
+  DataViewsAPITypes,
+  DrivesAPITypes,
+  EventLogsAPITypes,
+  LocationsAPITypes,
+  MaintenanceWindowDefinitionsAPITypes,
+  MonitorsAPITypes,
+  NetworkDevicesAPITypes,
+  PatchingAPITypes,
+  RemoteAgentAPITypes,
+  ScriptingAPITypes,
+  SearchesAPITypes,
+  SystemAPITypes,
+  TicketsAPITypes,
+  UserProfilesAPITypes,
 }