feat: add lock status to Node SDK (#163)

Added lock status capability into the SDK --------- Authored-by: Haig Hovsepian Co-authored-by: Adrian Garcia <joadgaji>
smartcar · Aug 23, 2023 · 6029075 · 6029075
1 parent cb3c2f2
commit 6029075
Show file tree

Hide file tree

Showing 4 changed files with 256 additions and 0 deletions.
diff --git a/doc/readme.md b/doc/readme.md
@@ -74,6 +74,8 @@ the following fields :</p>
 <dd></dd>
 <dt><a href="#Odometer">Odometer</a> : <code>Object</code></dt>
 <dd></dd>
+<dt><a href="#SecurityResponse">SecurityResponse</a> : <code>Object</code></dt>
+<dd></dd>
 <dt><a href="#Location">Location</a> : <code>Object</code></dt>
 <dd></dd>
 <dt><a href="#Attributes">Attributes</a> : <code>Object</code></dt>
@@ -626,6 +628,7 @@ Initializes a new Service object to make requests to the Smartcar API.
     * [.startCharge()](#Vehicle+startCharge) ⇒ [<code>ActionResponse</code>](#ActionResponse)
     * [.stopCharge()](#Vehicle+stopCharge) ⇒ [<code>ActionResponse</code>](#ActionResponse)
     * [.disconnect()](#Vehicle+disconnect) ⇒ [<code>ActionResponse</code>](#ActionResponse)
+    * [.security()](#Vehicle+security) ⇒ [<code>SecurityResponse</code>](#SecurityResponse)
 
 <a name="new_Vehicle_new"></a>
 
@@ -980,6 +983,19 @@ to make requests to it again.
   for all possible errors.
 
 **See**: [Smartcar API Doc - Disconnect](https://smartcar.com/docs/api#delete-disconnect)
+<a name="Vehicle+security"></a>
+
+### vehicle.security() ⇒ [<code>SecurityResponse</code>](#SecurityResponse)
+Returns the lock status of the vehicle.
+
+**Kind**: instance method of [<code>Vehicle</code>](#Vehicle)
+**Throws**:
+
+- [<code>SmartcarError</code>](#SmartcarError) - an instance of SmartcarError.
+  See the [errors section](https://github.com/smartcar/node-sdk/tree/master/doc#errors)
+  for all possible errors.
+
+**See**: [Smartcar API Doc - Security](https://smartcar.com/docs/api#get-security)
 <a name="METHODS_MAP"></a>
 
 ## METHODS\_MAP : <code>object.&lt;String, Object&gt;</code>
@@ -1317,6 +1333,90 @@ the following fields :
   }
 }
 ```
+<a name="SecurityResponse"></a>
+
+## SecurityResponse : <code>Object</code>
+**Kind**: global typedef
+**Properties**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| isLocked | <code>Boolean</code> | Whether the vehicle is locked or not. |
+| doors | <code>Array</code> | The status of each of the vehicle's doors. |
+| windows | <code>Array</code> | The status of each of the vehicle's windows. |
+| sunroof | <code>Array</code> | The status of each of the vehicle's sunroof. |
+| storage | <code>Array</code> | The status of each of the vehicle's storage. |
+| chargingPort | <code>Array</code> | The status of each of the vehicle's chargingPort. |
+| meta | [<code>Meta</code>](#Meta) |  |
+
+**Example**
+```js
+{
+   isLocked: true,
+   doors: [
+      {
+          type: 'frontLeft',
+          status: 'LOCKED',
+      },
+      {
+          type: 'frontRight',
+          status: 'LOCKED',
+      },
+      {
+          type: 'backLeft',
+          status: 'LOCKED',
+      },
+      {
+          type: 'backRight',
+          status: 'LOCKED',
+      },
+   ],
+   windows: [
+      {
+          type: 'frontLeft',
+          status: 'CLOSED',
+      },
+      {
+          type: 'frontRight',
+          status: 'CLOSED',
+      },
+      {
+          type: 'backLeft',
+          status: 'CLOSED',
+      },
+      {
+          type: 'backRight',
+          status: 'CLOSED',
+      },
+   ],
+   sunroof: [
+      {
+          type: 'sunroof',
+          status: 'CLOSED',
+      },
+   ],
+   storage: [
+      {
+          type: 'rear',
+          status: 'CLOSED',
+      },
+      {
+          type: 'front',
+          status: 'CLOSED',
+      },
+   ],
+   chargingPort: [
+      {
+          type: 'chargingPort',
+          status: 'CLOSED',
+      },
+   ],
+   meta: {
+       dataAge: new Date('2018-05-04T07:20:50.844Z'),
+       requestId: '26c14915-0c26-43c5-8e42-9edfc2a66a0f',
+   },
+}
+```
 <a name="Location"></a>
 
 ## Location : <code>Object</code>

diff --git a/lib/vehicle.js b/lib/vehicle.js
@@ -31,6 +31,7 @@ const METHODS_MAP = {
   startCharge: {requestType: 'post', path: 'charge', body: {action: 'START'}},
   stopCharge: {requestType: 'post', path: 'charge', body: {action: 'STOP'}},
   disconnect: {requestType: 'delete', path: 'application'},
+  lockStatus: {path: 'security'},
 };
 
 /** @exports Vehicle */
@@ -595,6 +596,86 @@ Vehicle.prototype.request = async function(
  *   }
  * }
  */
+
+/**
+ * @type {Object}
+ * @typedef SecurityResponse
+ * @property {Boolean} isLocked - Whether the vehicle is locked or not.
+ * @property {Array} doors - The status of each of the vehicle's doors.
+ * @property {Array} windows - The status of each of the vehicle's windows.
+ * @property {Array} sunroof - The status of each of the vehicle's sunroof.
+ * @property {Array} storage - The status of each of the vehicle's storage.
+ * @property {Array} chargingPort - The status of each of the vehicle's chargingPort.
+ * @property {Meta} meta
+ *
+ * @example
+ * {
+ *    isLocked: true,
+ *    doors: [
+ *       {
+ *           type: 'frontLeft',
+ *           status: 'LOCKED',
+ *       },
+ *       {
+ *           type: 'frontRight',
+ *           status: 'LOCKED',
+ *       },
+ *       {
+ *           type: 'backLeft',
+ *           status: 'LOCKED',
+ *       },
+ *       {
+ *           type: 'backRight',
+ *           status: 'LOCKED',
+ *       },
+ *    ],
+ *    windows: [
+ *       {
+ *           type: 'frontLeft',
+ *           status: 'CLOSED',
+ *       },
+ *       {
+ *           type: 'frontRight',
+ *           status: 'CLOSED',
+ *       },
+ *       {
+ *           type: 'backLeft',
+ *           status: 'CLOSED',
+ *       },
+ *       {
+ *           type: 'backRight',
+ *           status: 'CLOSED',
+ *       },
+ *    ],
+ *    sunroof: [
+ *       {
+ *           type: 'sunroof',
+ *           status: 'CLOSED',
+ *       },
+ *    ],
+ *    storage: [
+ *       {
+ *           type: 'rear',
+ *           status: 'CLOSED',
+ *       },
+ *       {
+ *           type: 'front',
+ *           status: 'CLOSED',
+ *       },
+ *    ],
+ *    chargingPort: [
+ *       {
+ *           type: 'chargingPort',
+ *           status: 'CLOSED',
+ *       },
+ *    ],
+ *    meta: {
+ *        dataAge: new Date('2018-05-04T07:20:50.844Z'),
+ *        requestId: '26c14915-0c26-43c5-8e42-9edfc2a66a0f',
+ *    },
+ * }
+ */
+
 /**
  * @name Vehicle#odometer
  * @function
@@ -747,4 +828,16 @@ Vehicle.prototype.request = async function(
  *   for all possible errors.
  */
 
+/**
+ * @name Vehicle#security
+ * @function
+ * @memberof Vehicle
+ * @description Returns the lock status of the vehicle.
+ * @see {@link https://smartcar.com/docs/api#get-security|Smartcar API Doc - Security}
+ * @return {SecurityResponse}
+ * @throws {SmartcarError} - an instance of SmartcarError.
+ *   See the [errors section](https://github.com/smartcar/node-sdk/tree/master/doc#errors)
+ *   for all possible errors.
+ */
+
 module.exports = Vehicle;
diff --git a/test/end-to-end/vehicle.js b/test/end-to-end/vehicle.js
@@ -25,6 +25,7 @@ test.before(async(t) => {
     getVehicle('FORD', [
       'required:control_charge',
       'required:control_security',
+      'required:read_security',
     ]),
     getVehicle('KIA', [
       'required:read_charge',
@@ -312,6 +313,22 @@ test('vehicle unlock', async(t) => {
   t.is(response.meta.requestId.length, 36);
 });
 
+test('vehicle read security', async(t) => {
+  const response = await t.context.ford.lockStatus();
+  t.deepEqual(
+    _.xor(_.keys(response), [
+      'isLocked',
+      'doors',
+      'windows',
+      'sunroof',
+      'storage',
+      'chargingPort',
+      'meta',
+    ]),
+    [],
+  );
+});
+
 test('vehicle startCharge', async(t) => {
   const response = await t.context.ford.startCharge();
   t.deepEqual(
@@ -377,6 +394,26 @@ test('vehicle batch', async(t) => {
   t.is(location.meta.requestId.length, 36);
 });
 
+test('vehicle batch - security', async(t) => {
+  const response = await t.context.ford.batch([
+    '/security',
+  ]);
+
+  const security = response.security();
+  t.deepEqual(
+    _.xor(_.keys(security), [
+      'isLocked',
+      'doors',
+      'windows',
+      'sunroof',
+      'storage',
+      'chargingPort',
+      'meta',
+    ]),
+    [],
+  );
+});
+
 test('vehicle request - odometer', async(t) => {
   const response = await t.context.volt.request(
     'get',

diff --git a/test/unit/lib/vehicle.js b/test/unit/lib/vehicle.js
@@ -350,3 +350,29 @@ test('request - set charge limit', async function(t) {
   );
   t.true(t.context.n.isDone());
 });
+
+test('request - security', async function(t) {
+  sinon.restore(); // clear all spys
+
+  t.context.n = nocks
+    .base()
+    .get('/security')
+    .reply(200,
+      {
+        isLocked: true,
+        doors: [],
+        windows: [],
+        storage: [],
+        sunroof: [],
+        chargingPort: [],
+      }, {'sc-request-id': 'requestId'});
+
+  const serviceRequestSpy = sinon.spy(vehicle.service, 'request');
+
+  const response = await vehicle.lockStatus();
+
+  t.true(serviceRequestSpy.calledOnceWith('get', 'security'));
+  t.is(response.meta.requestId, 'requestId');
+  t.is(response.isLocked, true);
+  t.true(t.context.n.isDone());
+});