@smartcar/auth 2.13.1 → 2.14.0

package/README.md

@@ -7,7 +7,7 @@ The official Smartcar JavaScript SDK.
 The [Smartcar API](https://smartcar.com/docs) lets you read vehicle data
 (location, odometer) and send commands to vehicles (lock, unlock) using HTTP requests.
 
-To make requests to a vehicle from a web application, the end user must connect their vehicle using [Smartcar Connect](https://smartcar.com/docs/api#smartcar-connect). The Smartcar JavaScript SDK provides an easy way to launch and handle Connect to retrieve the resulting `code`.
+To make requests to a vehicle from a web application, the end user must connect their vehicle using [Smartcar Connect](https://smartcar.com/docs/connect/what-is-connect). The Smartcar JavaScript SDK provides an easy way to launch and handle Connect to retrieve the resulting `code`, or to complete a redirect-less M2M authorization flow using `response_type=none`.
 
 Before integrating with the JavaScript SDK, you'll need to register an application in the [Smartcar dashboard](https://dashboard.smartcar.com). Once you have registered an application, you will have an Application ID, which will allow you to launch Connect and authorize users.
 
@@ -24,7 +24,7 @@ npm install @smartcar/auth
 ### Smartcar CDN
 
 ```html
-<script src="https://javascript-sdk.smartcar.com/2.13.1/sdk.js"></script>
+<script src="https://javascript-sdk.smartcar.com/2.14.0/sdk.js"></script>
 ```
 
 ## SDK reference
@@ -132,6 +132,34 @@ const url = smartcar.getAuthUrl();
 
 **Reference:** [`smartcar.getAuthUrl(options)`](doc#Smartcar+getAuthUrl)
 
+### response_type=none flow
+
+For M2M use cases, you can launch Connect with `responseType: 'none'` to complete authorization without exchanging the authorization code in the browser. This mode is intended for M2M Auth flow that does not require a vehicle-scope authorization code.
+
+If you provide a `redirectUri`, Connect redirects the user after authorization completes and `onComplete` fires as normal. If you do not provide a `redirectUri`, the user lands on a Smartcar-hosted page after authorization completes.
+
+It is recommended that you pass an `externalId` to associate the vehicle connection with an identifier in your system. It will be returned in the `onComplete` callback.
+
+```javascript
+const smartcar = new Smartcar({
+  applicationId: '<your-application-id>',
+  scope: ['read_vehicle_info', 'read_odometer'],
+  redirectUri: '<your-redirect-uri>'
+  responseType: 'none',
+  externalId: '<your-external-id>',
+});
+```
+
+Launch Connect as usual:
+
+```javascript
+smartcar.openDialog();
+```
+
+Use `externalId` to correlate the completed authorization with a user in your system in webhook delivieres or by making a request to the `/connections` endpoint filtered by the user's `externalId`.
+
+**Reference:** [`new Smartcar(options)`](doc#new_Smartcar_new)
+
 ### Server-side redirect handling
 
 In a traditional OAuth implementation, the redirect URI is normally set to your application's back end, rather than Smartcar's special JavaScript SDK redirect page described in the flow above. Instead of using the JavaScript SDK redirect page, you can still choose to use the traditional server-side architecture (described below). In this architecture you would receive the authorization code on a back-end route instead of the client-side `onComplete` callback.
@@ -180,4 +208,4 @@ https://application-backend.com/page?error=access_denied&error_description=User+
 [tag-image]: https://img.shields.io/github/tag/smartcar/javascript-sdk.svg
 
 <!-- Please do not modify or remove this, it is used by the build process -->
-[version]: 2.13.1
+[version]: 2.14.0

package/README.mdt

@@ -7,7 +7,7 @@ The official Smartcar JavaScript SDK.
 The [Smartcar API](https://smartcar.com/docs) lets you read vehicle data
 (location, odometer) and send commands to vehicles (lock, unlock) using HTTP requests.
 
-To make requests to a vehicle from a web application, the end user must connect their vehicle using [Smartcar Connect](https://smartcar.com/docs/api#smartcar-connect). The Smartcar JavaScript SDK provides an easy way to launch and handle Connect to retrieve the resulting `code`.
+To make requests to a vehicle from a web application, the end user must connect their vehicle using [Smartcar Connect](https://smartcar.com/docs/connect/what-is-connect). The Smartcar JavaScript SDK provides an easy way to launch and handle Connect to retrieve the resulting `code`, or to complete a redirect-less M2M authorization flow using `response_type=none`.
 
 Before integrating with the JavaScript SDK, you'll need to register an application in the [Smartcar dashboard](https://dashboard.smartcar.com). Once you have registered an application, you will have an Application ID, which will allow you to launch Connect and authorize users.
 
@@ -132,6 +132,34 @@ const url = smartcar.getAuthUrl();
 
 **Reference:** [`smartcar.getAuthUrl(options)`](doc#Smartcar+getAuthUrl)
 
+### response_type=none flow
+
+For M2M use cases, you can launch Connect with `responseType: 'none'` to complete authorization without exchanging the authorization code in the browser. This mode is intended for M2M Auth flow that does not require a vehicle-scope authorization code.
+
+If you provide a `redirectUri`, Connect redirects the user after authorization completes and `onComplete` fires as normal. If you do not provide a `redirectUri`, the user lands on a Smartcar-hosted page after authorization completes.
+
+It is recommended that you pass an `externalId` to associate the vehicle connection with an identifier in your system. It will be returned in the `onComplete` callback.
+
+```javascript
+const smartcar = new Smartcar({
+  applicationId: '<your-application-id>',
+  scope: ['read_vehicle_info', 'read_odometer'],
+  redirectUri: '<your-redirect-uri>'
+  responseType: 'none',
+  externalId: '<your-external-id>',
+});
+```
+
+Launch Connect as usual:
+
+```javascript
+smartcar.openDialog();
+```
+
+Use `externalId` to correlate the completed authorization with a user in your system in webhook delivieres or by making a request to the `/connections` endpoint filtered by the user's `externalId`.
+
+**Reference:** [`new Smartcar(options)`](doc#new_Smartcar_new)
+
 ### Server-side redirect handling
 
 In a traditional OAuth implementation, the redirect URI is normally set to your application's back end, rather than Smartcar's special JavaScript SDK redirect page described in the flow above. Instead of using the JavaScript SDK redirect page, you can still choose to use the traditional server-side architecture (described below). In this architecture you would receive the authorization code on a back-end route instead of the client-side `onComplete` callback.

package/dist/npm/sdk.js

@@ -71,8 +71,8 @@ function _typeof(obj) { "@babel/helpers - typeof"; return _typeof = "function" =
      * @param {?Error} error - something went wrong in Connect; this
      * normally indicates that the user denied access to your application or does not
      * have a connected vehicle
-     * @param {String} code - the authorization code to be exchanged from a
-     * backend sever for an access token
+     * @param {String} [code] - the authorization code to be exchanged from a
+     * backend server for an access token; undefined for response_type=none flows
      * @param {Object} [state] - contains state if it was set on the initial
      * authorization request
      * @param {String} [virtualKeyUrl] - virtual key URL used by Tesla to register
@@ -80,6 +80,7 @@ function _typeof(obj) { "@babel/helpers - typeof"; return _typeof = "function" =
      * any commands on a Tesla vehicle. It is an optional argument as it is only included in
      * specific cases.
      * @param {String} userId - A unique identifier for the vehicle owner that granted access.
+     * @param {String} [externalId] - The external_id returned by Connect.
      */
 
     /**
@@ -97,6 +98,11 @@ function _typeof(obj) { "@babel/helpers - typeof"; return _typeof = "function" =
      * Launch Smartcar Connect in [test mode](https://smartcar.com/docs/guides/testing/).
      * @param {String} [options.mode='live'] - Determine what mode Smartcar Connect should be
      * launched in. Should be one of test, live or simulated.
+     * @param {String} [options.responseType='code'] - OAuth response type. Use 'none' for
+     * redirect-less M2M flows; defaults to 'code'.
+     * @param {String} [options.externalId] - An optional external identifier passed through
+     * to Connect and returned in the onComplete callback. Pass `null` to explicitly clear a
+     * previously set externalId; omit the option (`undefined`) to leave it unset.
     */
     function Smartcar(options) {
       var _this = this;
@@ -142,7 +148,8 @@ function _typeof(obj) { "@babel/helpers - typeof"; return _typeof = "function" =
         throw new Error('The "mode" parameter MUST be one of the following: \'test\', \'live\', \'simulated\'');
       }
 
-      this.responseType = 'code'; // identifier for matching message event and multiple Smartcar instances
+      this.responseType = options.responseType || 'code';
+      this.externalId = options.externalId; // identifier for matching message event and multiple Smartcar instances
       // it is a string composed of a timestamp and a 8-digit random number
 
       this.instanceId = new Date().getTime() + String(Math.random()).slice(2, 10); // handler
@@ -222,6 +229,7 @@ function _typeof(obj) { "@babel/helpers - typeof"; return _typeof = "function" =
           var err = generateError(message.error, message.errorDescription);
           var virtualKeyUrl = message.virtualKeyUrl;
           var userId = message.userId;
+          var externalId = message.externalId;
           /**
            * Call `onComplete` with parameters even if developer is not using
            * a Smartcar-hosted redirect. Regardless of if they are using a
@@ -235,7 +243,7 @@ function _typeof(obj) { "@babel/helpers - typeof"; return _typeof = "function" =
            * parameters in their redirect uri.
            */
 
-          _this.onComplete(err, message.code, originalState, virtualKeyUrl, userId);
+          _this.onComplete(err, message.code, originalState, virtualKeyUrl, userId, externalId);
         }
       }; // add handler for postMessage event on completion of Smartcar Connect
 
@@ -374,6 +382,11 @@ function _typeof(obj) { "@babel/helpers - typeof"; return _typeof = "function" =
           link += "&user=".concat(encodeURIComponent(options.user));
         }
 
+        if (this.externalId !== undefined) {
+          var externalId = this.externalId === null ? 'null' : encodeURIComponent(this.externalId);
+          link += "&external_id=".concat(externalId);
+        }
+
         return link;
       }
       /**
@@ -405,6 +418,8 @@ function _typeof(obj) { "@babel/helpers - typeof"; return _typeof = "function" =
     }, {
       key: "openDialog",
       value: function openDialog(options) {
+        options = options || {};
+
         var windowOptions = Smartcar._getWindowOptions(options.windowOptions || {});
 
         var href = this.getAuthUrl(options);
@@ -539,6 +554,12 @@ function _typeof(obj) { "@babel/helpers - typeof"; return _typeof = "function" =
           throw new TypeError('An applicationId option must be provided');
         }
 
+        var VALID_RESPONSE_TYPES = ['code', 'none'];
+
+        if (options.responseType && !VALID_RESPONSE_TYPES.includes(options.responseType)) {
+          throw new Error("The \"responseType\" option must be one of: ".concat(VALID_RESPONSE_TYPES.join(', ')));
+        }
+
         if (options.redirectUri) {
           if (options.redirectUri.startsWith('https://javascript-sdk.smartcar.com')) {
             // require onComplete method with at least two parameters (error & code)
@@ -554,6 +575,9 @@ function _typeof(obj) { "@babel/helpers - typeof"; return _typeof = "function" =
               console.warn("\nThe Smartcar redirect URI you're using is outdated! To update it, please see:\nhttps://github.com/smartcar/javascript-sdk#1-register-a-javascript-sdk-redirect-uri\n");
             }
           }
+        } else if (options.responseType === 'none' && options.onComplete) {
+          // eslint-disable-next-line no-console
+          console.warn('The "onComplete" callback will not fire for responseType "none" unless a redirectUri is provided.');
         }
       }
       /**

package/doc/README.md

@@ -56,6 +56,8 @@ Initializes Smartcar class.
 | [options.onComplete] | [<code>OnComplete</code>](#OnComplete) |  | called on completion of Smartcar Connect |
 | [options.testMode] | <code>Boolean</code> | <code>false</code> | Deprecated, please use `mode` instead. Launch Smartcar Connect in [test mode](https://smartcar.com/docs/guides/testing/). |
 | [options.mode] | <code>String</code> | <code>&#x27;live&#x27;</code> | Determine what mode Smartcar Connect should be launched in. Should be one of test, live or simulated. |
+| [options.responseType] | <code>String</code> | <code>&#x27;code&#x27;</code> | OAuth response type. Use 'none' for redirect-less M2M flows; defaults to 'code'. |
+| [options.externalId] | <code>String</code> |  | An optional external identifier passed through to Connect and returned in the onComplete callback. Pass `null` to explicitly clear a previously set externalId; omit the option (`undefined`) to leave it unset. |
 
 <a name="Smartcar+getAuthUrl"></a>
 
@@ -204,10 +206,11 @@ Invalid subscription error returned by Connect.
 | Param | Type | Description |
 | --- | --- | --- |
 | error | <code>Error</code> | something went wrong in Connect; this normally indicates that the user denied access to your application or does not have a connected vehicle |
-| code | <code>String</code> | the authorization code to be exchanged from a backend sever for an access token |
+| [code] | <code>String</code> | the authorization code to be exchanged from a backend server for an access token; undefined for response_type=none flows |
 | [state] | <code>Object</code> | contains state if it was set on the initial authorization request |
 | [virtualKeyUrl] | <code>String</code> | virtual key URL used by Tesla to register Smartcar's virtual key on a vehicle. This registration will be required in order to use any commands on a Tesla vehicle. It is an optional argument as it is only included in specific cases. |
 | userId | <code>String</code> | A unique identifier for the vehicle owner that granted access. |
+| [externalId] | <code>String</code> | The external_id returned by Connect. |
 
 <a name="WindowOptions"></a>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartcar/auth",
-  "version": "2.13.1",
+  "version": "2.14.0",
   "description": "javascript auth sdk for the smartcar",
   "main": "dist/npm/sdk.js",
   "license": "MIT",