fix: fix return type of rules execute function; update dependencies

The API for executing rules returned more data than we were using. The method calling this API has
been updated to match it.

BREAKING CHANGE: the return type of RulesEndpoint.execute is different

Author: rossiam

package-lock.json

@@ -19,37 +19,37 @@
 		"dist/**/*"
 	],
 	"dependencies": {
-		"async-mutex": "^0.2.1",
+		"async-mutex": "^0.3.2",
 		"axios": "^0.21.4",
-		"http-signature": "^1.3.4",
-		"qs": "^6.9.3",
-		"sshpk": "^1.16.1",
-		"underscore": "^1.10.2"
+		"http-signature": "^1.3.6",
+		"qs": "^6.10.3",
+		"sshpk": "^1.17.0",
+		"underscore": "^1.13.2"
 	},
 	"devDependencies": {
 		"@commitlint/cli": "^16.0.2",
 		"@commitlint/config-conventional": "^16.0.0",
 		"@semantic-release/changelog": "^6.0.1",
 		"@semantic-release/git": "^10.0.1",
-		"@types/jest": "^26.0.10",
-		"@types/node": "^12.11.7",
-		"@types/qs": "^6.9.1",
-		"@types/sshpk": "^1.10.4",
-		"@types/underscore": "^1.9.4",
-		"@typescript-eslint/eslint-plugin": "^5.8.1",
-		"@typescript-eslint/parser": "^5.8.1",
+		"@types/jest": "^27.4.0",
+		"@types/node": "^17.0.9",
+		"@types/qs": "^6.9.7",
+		"@types/sshpk": "^1.10.7",
+		"@types/underscore": "^1.11.4",
+		"@typescript-eslint/eslint-plugin": "^5.10.0",
+		"@typescript-eslint/parser": "^5.10.0",
 		"conventional-changelog-conventionalcommits": "^4.6.3",
 		"cz-conventional-changelog": "^3.3.0",
-		"eslint": "^8.5.0",
+		"eslint": "^8.7.0",
 		"eslint-config-prettier": "^8.3.0",
 		"eslint-plugin-eslint-comments": "^3.2.0",
-		"eslint-plugin-import": "^2.25.3",
-		"eslint-plugin-jest": "^23.8.2",
-		"jest": "^26.4.2",
+		"eslint-plugin-import": "^2.25.4",
+		"eslint-plugin-jest": "^25.7.0",
+		"jest": "^27.4.7",
 		"prettier": "^2.5.1",
-		"semantic-release": "^18.0.1",
-		"ts-jest": "^26.3.0",
-		"typedoc": "^0.20.36",
+		"semantic-release": "^19.0.2",
+		"ts-jest": "^27.1.3",
+		"typedoc": "^0.22.11",
 		"typescript": "^4.5.4"
 	},
 	"scripts": {

package.json

@@ -89,8 +89,12 @@ export interface RefreshTokenStore {
 }
 
 /**
- * An authenticator that supports refreshing of the access token using a refresh token by loading the refresh token,
- * client ID, and client secret from a token store, performing the refresh, and storing the new tokens.
+ * An authenticator that supports refreshing of the access token using a refresh token by loading
+ * the refresh token, client ID, and client secret from a token store, performing the refresh, and
+ * storing the new tokens.
+ *
+ * Note that corruption of the refresh token is unlikely but possible if two of the same
+ * authenticators refresh the same token at the same time.
  */
 export class RefreshTokenAuthenticator implements Authenticator {
 	constructor(public token: string, private tokenStore: RefreshTokenStore) {
@@ -129,14 +133,21 @@ export class RefreshTokenAuthenticator implements Authenticator {
 				refreshToken: response.data.refresh_token,
 			}
 			this.token = authData.authToken
-			requestConfig.headers.Authorization = `Bearer ${this.token}`
+			requestConfig.headers = { ...(requestConfig.headers ?? {}), Authorization: `Bearer ${this.token}` }
 			return this.tokenStore.putAuthData(authData)
 		}
 
 		throw Error(`error ${response.status} refreshing token, with message ${response.data}`)
 	}
 }
 
+/**
+ * A an authenticator that works like RefreshTokenAuthenticator but which can use a mutex to help
+ * prevent corruption of the refresh token.
+ *
+ * Note that while `acquireRefreshMutex` is provided for you to use the mutex, the mutex is not
+ * automatically used.
+ */
 export class SequentialRefreshTokenAuthenticator extends RefreshTokenAuthenticator {
 	constructor(token: string, tokenStore: RefreshTokenStore, private refreshMutex: MutexInterface) {
 		super(token, tokenStore)

src/authenticator.ts

@@ -295,6 +295,41 @@ export interface Rule extends RuleRequest {
 	id: string
 }
 
+export type ExecutionResult = 'Success' | 'Failure' | 'Ignored'
+
+export type IfExecutionResult = 'True' | 'False'
+export interface IfActionExecutionResult {
+	result: IfExecutionResult
+}
+export interface LocationActionExecutionResult {
+	result: ExecutionResult
+	locationId: string
+}
+
+export type CommandExecutionResult = 'Success' | 'Failure' | 'Offline'
+export interface CommandActionExecutionResult {
+	result: CommandExecutionResult
+	deviceId: string
+}
+
+export interface SleepActionExecutionResult {
+	result: ExecutionResult
+}
+
+export interface ActionExecutionResult {
+	actionId: string
+	if?: IfActionExecutionResult
+	location?: LocationActionExecutionResult
+	command?: CommandActionExecutionResult[]
+	sleep?: SleepActionExecutionResult
+}
+export interface ExecuteResponse {
+	executionId: string
+	id: string
+	result: string
+	actions?: ActionExecutionResult[]
+}
+
 export class RulesEndpoint extends Endpoint {
 	constructor(config: EndpointClientConfig) {
 		super(new EndpointClient('rules', config))
@@ -308,7 +343,7 @@ export class RulesEndpoint extends Endpoint {
 	 * can be omitted
 	 */
 	public list(locationId?: string): Promise<Rule[]> {
-		return this.client.getPagedItems<Rule>(undefined, {locationId: this.locationId(locationId)})
+		return this.client.getPagedItems<Rule>(undefined, { locationId: this.locationId(locationId) })
 	}
 
 	/**
@@ -318,7 +353,7 @@ export class RulesEndpoint extends Endpoint {
 	 * can be omitted
 	 */
 	public get(id: string, locationId?: string): Promise<Rule> {
-		return this.client.get<Rule>(id, {locationId: this.locationId(locationId)})
+		return this.client.get<Rule>(id, { locationId: this.locationId(locationId) })
 	}
 
 	/**
@@ -328,7 +363,7 @@ export class RulesEndpoint extends Endpoint {
 	 * can be omitted
 	 */
 	public async delete(id: string, locationId?: string): Promise<Status> {
-		await this.client.delete(id, {locationId: this.locationId(locationId)})
+		await this.client.delete(id, { locationId: this.locationId(locationId) })
 		return SuccessStatusValue
 	}
 
@@ -339,7 +374,7 @@ export class RulesEndpoint extends Endpoint {
 	 * can be omitted
 	 */
 	public create(data: RuleRequest, locationId?: string): Promise<Rule> {
-		return this.client.post(undefined, data, {locationId: this.locationId(locationId)})
+		return this.client.post(undefined, data, { locationId: this.locationId(locationId) })
 	}
 
 	/**
@@ -350,7 +385,7 @@ export class RulesEndpoint extends Endpoint {
 	 * can be omitted
 	 */
 	public update(id: string, data: RuleRequest, locationId?: string): Promise<Rule> {
-		return this.client.put(id, data, {locationId: this.locationId(locationId)})
+		return this.client.put(id, data, { locationId: this.locationId(locationId) })
 	}
 
 	/**
@@ -359,8 +394,7 @@ export class RulesEndpoint extends Endpoint {
 	 * @param locationId UUID of the location, If the client is configured with a location ID this parameter
 	 * can be omitted
 	 */
-	public async execute(id: string, locationId?: string): Promise<Status> {
-		await this.client.post(`execute/${id}`, undefined, {locationId: this.locationId(locationId)})
-		return SuccessStatusValue
+	public async execute(id: string, locationId?: string): Promise<ExecuteResponse> {
+		return this.client.post(`execute/${id}`, undefined, { locationId: this.locationId(locationId) })
 	}
 }