feat: Add backup and restore functionality

- Update dependencies
- Update mocha setup due to latest changes
- Drop nyc and use c8
- Add backup and restore functionality
- Update readme

.github/workflows/labeler.yml

@@ -1,4 +1,4 @@
-name: "Pull Request Labeler"
+name: 'Pull Request Labeler'
 on:
   - pull_request
 

.github/workflows/release.yml

@@ -6,7 +6,7 @@ on:
   workflow_dispatch:
 
 env:
-  NODE_VERSION: 20
+  NODE_VERSION: 22
   FORCE_COLOR: 1
   NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
 

.github/workflows/test.yml

@@ -6,7 +6,7 @@ on:
   push:
     branches:
       - '*'
-  pull_request: { }
+  pull_request: {}
   workflow_dispatch:
 
 # Cancel previous PR/branch runs when a new commit is pushed
@@ -20,7 +20,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [ 18.x, 20.x ]
+        node-version: [20.x, 22.x]
 
     steps:
       - name: Checkout code

.gitignore

@@ -50,3 +50,8 @@ typings/
 .nyc_output
 
 .yarn
+
+# some test relevant files
+coverage
+*.home
+*.backup

.mocharc.json

@@ -1,10 +1,7 @@
 {
   "extension": ["ts"],
   "spec": "test/**/*.spec.ts",
-  "node-option": [
-    "experimental-specifier-resolution=node",
-    "loader=ts-node/esm"
-  ],
+  "node-option": ["experimental-specifier-resolution=node", "loader=ts-node/esm"],
   "require": ["ts-node/register"],
   "recursive": true
 }

.npmignore

@@ -72,7 +72,7 @@ resources
 .editorconfig
 .mocharc.json
 .releaserc.yaml
-disable-publish-semantic-release-github.js
+disable-publish-semantic-release-github.cjs
 eslint.config.mjs
 prettier.config.mjs
 release-tags.sh

.releaserc.yaml

@@ -1,4 +1,4 @@
-branches: [ 'master' ]
+branches: ['master']
 repositoryUrl: 'git@github.com:holomekc/bosch-smart-home-bridge.git'
 tagFormat: ${version}
 plugins:

.run/Tests E2E Template.run.xml

@@ -9,6 +9,7 @@
       <env name="BSHC_CERT" value="" />
       <env name="BSHC_HOST" value="" />
       <env name="BSHC_PRIV" value="" />
+      <env name="TS_NODE_PROJECT" value="./tsconfig.spec.json" />
     </envs>
     <ui>bdd</ui>
     <extra-mocha-options>--grep e2e --exit</extra-mocha-options>

.run/Tests.run.xml

@@ -5,6 +5,9 @@
     <mocha-package>$PROJECT_DIR$/node_modules/mocha</mocha-package>
     <working-directory>$PROJECT_DIR$</working-directory>
     <pass-parent-env>true</pass-parent-env>
+    <envs>
+      <env name="TS_NODE_PROJECT" value="./tsconfig.spec.json" />
+    </envs>
     <ui>bdd</ui>
     <extra-mocha-options>--grep should --exit</extra-mocha-options>
     <test-kind>DIRECTORY</test-kind>

.yarnrc.yml

@@ -2,10 +2,10 @@ cacheFolder: ./.yarn/cache
 
 enableGlobalCache: false
 
-httpProxy: "${http_proxy:-}"
+httpProxy: '${http_proxy:-}'
 
-httpsProxy: "${https_proxy:-}"
+httpsProxy: '${https_proxy:-}'
 
 nodeLinker: node-modules
 
-npmAuthToken: "${NPM_TOKEN:-}"
+npmAuthToken: '${NPM_TOKEN:-}'

README.md

@@ -17,7 +17,8 @@ Allows communication to Bosch Smart Home Controller (BSHC)
 
 ## Getting started
 
-You need to create a new instance of BoschSmartHomeBridge (BSHB). Therefore, you need to use BoschSmartHomeBridgeBuilder.
+You need to create a new instance of BoschSmartHomeBridge (BSHB). Therefore, you need to use
+BoschSmartHomeBridgeBuilder.
 The builder will force you to set every mandatory properties:
 
 - host name / ip address of BSHC
@@ -84,6 +85,88 @@ bshb
   .subscribe(() => {});
 ```
 
+## Backup & Restore
+
+With this new feature provided by bosch you can automate the backup process.
+
+Example can be found in the e2e test of the test folder.
+
+The workflow is:
+
+1. Create a backup
+   ```typescript
+   bshb.getBshcClient().createBackup('SystemPassword', 'encryptionPassword');
+   ```
+2. Wait for backup status READY
+   ```typescript
+   bshb.getBshcClient().getBackupStatus();
+   ```
+3. Download backup file
+   ```typescript
+   bshb.getBshcClient().getBackup();
+   ```
+4. Upload restore file
+   ```typescript
+   bshb.getBshcClient().uploadRestoreFile(binaryData);
+   ```
+5. Wait for restore status BACKUP_UPLOADED
+   ```typescript
+   bshb.getBshcClient().getRestoreStatus();
+   ```
+6. Press pairing button on controller. Once for Controller II and 3s for Controller I
+7. Wait for restore status RESTORE_AUTHORIZED
+   ```typescript
+   bshb.getBshcClient().getRestoreStatus();
+   ```
+8. Start restore process
+   ```typescript
+   bshb.getBshcClient().startRestoreProcess('encryptionPassword');
+   ```
+9. Wait for restore status RESTORED. The status might be in RESTORING for a while,
+   and due to the restart the controller might not be available for some time as well.
+   ```typescript
+   bshb.getBshcClient().getRestoreStatus();
+   ```
+10. Check partner restore status (Only possible if status is in RESTORED\*)
+
+```typescript
+bshb.getBshcClient().getPartnerRestoreStatus();
+```
+
+11. Complete the process or cancel the process (except if in RESTORING) via
+
+```typescript
+bshb.getBshcClient().deleteRestoreFile();
+bshb.getBshcClient().deleteBackup();
+```
+
+See api documentation for further details.
+
+Uploading incomplete files might end up in a timeout, where the Controller appears to be stuck
+in RESTORING. If this is the case wait until the controller is changing the status to ERROR,
+and then restart the controller. During my tests without the restart the complete backup
+and restore feature is not working properly anymore.
+
 ## Examples
 
 You can find an example in test directory. Npm arguments must be set manually.
+
+## Disclaimer
+
+By using this software, you acknowledge and accept the following terms:
+
+1. **Bosch Smart Home Controller**:
+
+   The use of this software with the Bosch Smart Home Controller I and II is at your own risk. The developer is not
+   liable for any damage to the hardware, including but not limited to physical damage, malfunction, or failure of the
+   Bosch Smart Home Controller. Users are advised to handle the devices with care and follow all manufacturer guidelines
+   and recommendations.
+
+2. **Data Loss**:
+
+   While efforts have been made to ensure the reliability of the backup and restore functionality, the developer cannot
+   guarantee the safety of your data. By using the backup and restore features, you understand and accept that there is
+   a risk of data loss. This may include, but is not limited to, loss of settings, configurations, or other user data
+   stored on the Bosch Smart Home Controller. It is strongly recommended that users perform regular backups and store
+   them in a secure location. The developer shall not be held responsible for any data loss or corruption arising from
+   the use of these features.

package.json

@@ -3,8 +3,9 @@
   "version": "1.4.2",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "type": "module",
   "scripts": {
-    "postinstall": "husky && node disable-publish-semantic-release-github.js",
+    "postinstall": "husky && node disable-publish-semantic-release-github.cjs",
     "prepack": "pinst --disable",
     "postpack": "pinst --enable",
     "clean": "rimraf dist && rimraf dist.spec",
@@ -13,7 +14,8 @@
     "lint": "eslint --max-warnings 0 .",
     "lint:fix": "eslint --max-warnings 0 --fix .",
     "prettier": "prettier --write .",
-    "test": "cross-env TS_NODE_PROJECT='./tsconfig.spec.json' nyc mocha --grep should --exit",
+    "test": "cross-env TS_NODE_PROJECT='./tsconfig.spec.json' c8 mocha --grep should --exit",
+    "test:watch": "cross-env TS_NODE_PROJECT='./tsconfig.spec.json' c8 mocha --grep should",
     "release": "semantic-release"
   },
   "keywords": [
@@ -55,6 +57,7 @@
     "@types/uuid": "10.0.0",
     "@typescript-eslint/eslint-plugin": "8.19.0",
     "@typescript-eslint/parser": "8.19.0",
+    "c8": "10.1.3",
     "chai": "5.1.2",
     "conventional-changelog-conventionalcommits": "8.0.0",
     "cross-env": "7.0.3",
@@ -66,7 +69,6 @@
     "express": "4.21.2",
     "husky": "9.1.7",
     "mocha": "11.0.1",
-    "nyc": "17.1.0",
     "pinst": "3.0.0",
     "prettier": "3.4.2",
     "prettier-eslint": "16.3.0",

src/api/abstract-bshc-client.ts

@@ -10,6 +10,8 @@ import { BshbCallOptions } from '../bshb-call-options';
 import { BshbUtils } from '../bshb-utils';
 import * as util from 'util';
 import * as http from 'http';
+import { Buffer } from 'node:buffer';
+import { BinaryResponse } from '../model/binary-response';
 
 /**
  * This class provides a simple call for all defined clients
@@ -22,6 +24,8 @@ export abstract class AbstractBshcClient {
 
   private static DEFAULT_TIMEOUT = 5000;
 
+  private static CONTENT_DISPOSITION_FILE_NAME_REGEX = /filename="([^"]+)"/;
+
   /**
    * Needed parameters for a {@link AbstractBshcClient}
    *
@@ -59,6 +63,7 @@ export abstract class AbstractBshcClient {
     options?: {
       certificateStorage?: CertificateStorage;
       systemPassword?: string;
+      isBinaryResponse?: boolean;
       bshbCallOptions?: BshbCallOptions;
     }
   ): Observable<BshbResponse<T>> {
@@ -84,9 +89,19 @@ export abstract class AbstractBshcClient {
       requestOptions.headers = {};
     }
 
-    requestOptions.headers['Content-Type'] = 'application/json';
-    requestOptions.headers['Accept'] = 'application/json';
-    requestOptions.headers['api-version'] = '3.12';
+    if (data instanceof Buffer) {
+      requestOptions.headers['Content-Type'] = 'application/octet-stream';
+    } else {
+      requestOptions.headers['Content-Type'] = 'application/json';
+      requestOptions.headers['Accept'] = 'application/json';
+      requestOptions.headers['api-version'] = '3.12';
+    }
+
+    const isBinaryResponse = options?.isBinaryResponse || false;
+
+    if (isBinaryResponse) {
+      requestOptions.headers['Accept'] = 'application/octet-stream';
+    }
 
     if (options && options.bshbCallOptions && options.bshbCallOptions) {
       Object.keys(options.bshbCallOptions).forEach(key => {
@@ -103,44 +118,49 @@ export abstract class AbstractBshcClient {
       requestOptions.headers['Systempassword'] = Buffer.from(options.systemPassword).toString('base64');
     }
 
-    let postData: string | undefined = undefined;
+    let postData: string | Buffer | undefined = undefined;
     if (data) {
       if (typeof data === 'string') {
         postData = data;
+      } else if (data instanceof Buffer) {
+        postData = data;
       } else {
         postData = JSON.stringify(data);
       }
       requestOptions.headers['Content-Length'] = postData.length;
     }
 
-    this.logger.debug(
-      `
+    return new Observable<BshbResponse<T>>(observer => {
+      this.logger.debug(
+        `
 Request: (${requestOptions.method}) ${requestOptions.hostname}:${requestOptions.port}${requestOptions.path}
 Headers:
 ${util.inspect(requestOptions.headers, { colors: true })}
 Body:
 ${util.inspect(data, { colors: true, depth: 10 })}
 `
-    );
-
-    return new Observable<BshbResponse<T>>(observer => {
+      );
       const req = https.request(requestOptions, res => {
         const chunks: any[] = [];
 
         res
-          .on('data', data => {
-            chunks.push(data);
+          .on('data', chunk => {
+            chunks.push(chunk);
           })
           .on('end', () => {
-            let dataString = undefined;
+            let data: any = undefined;
             if (chunks.length > 0) {
-              const data = Buffer.concat(chunks);
-              dataString = data.toString('utf-8');
+              const dataBuffer = Buffer.concat(chunks);
+              if (isBinaryResponse) {
+                data = dataBuffer;
+              } else {
+                data = dataBuffer.toString('utf-8');
+              }
             }
 
             try {
               if (res.statusCode && res.statusCode >= 300) {
-                this.logResponse(requestOptions, res, dataString);
+                this.logResponse(requestOptions, res, data);
 
                 this.handleError(
                   observer,
@@ -149,16 +169,24 @@ ${util.inspect(data, { colors: true, depth: 10 })}
                 );
               } else {
                 let parsedData = undefined;
-                if (dataString) {
-                  parsedData = JSON.parse(dataString);
+                if (data) {
+                  if (isBinaryResponse) {
+                    parsedData = {
+                      data: data,
+                      contentDisposition: res.headers['content-disposition'],
+                      fileName: this.extractFileName(res.headers['content-disposition']),
+                    } as BinaryResponse;
+                  } else {
+                    parsedData = JSON.parse(data);
+                  }
                 }
 
                 this.logResponse(requestOptions, res, parsedData);
 
                 observer.next(new BshbResponse<T>(res, parsedData));
               }
             } catch (e) {
-              this.logResponse(requestOptions, res, dataString);
+              this.logResponse(requestOptions, res, data);
               observer.error(new BshbError('error during parsing response from BSHC', BshbErrorType.PARSING, e));
             } finally {
               observer.complete();
@@ -215,4 +243,12 @@ Content:
 ${typeof data === 'object' ? util.inspect(data, { colors: true }) : data}
 `);
   }
+
+  private extractFileName(contentDisposition: string | undefined) {
+    if (contentDisposition) {
+      const match = contentDisposition.match(AbstractBshcClient.CONTENT_DISPOSITION_FILE_NAME_REGEX);
+      return match ? match[1] : undefined;
+    }
+    return undefined;
+  }
 }