particle-api-js 10.4.2 → 10.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "particle-api-js",
-  "version": "10.4.2",
+  "version": "10.5.0",
   "description": "Particle API Client",
   "main": "src/Particle.js",
   "scripts": {

package/src/Particle.js

@@ -3,17 +3,6 @@ const EventStream = require('./EventStream');
 const Agent = require('./Agent');
 const Client = require('./Client');
 
-// Hack to avoid importing the type on every @return statement
-/**
- * @typedef {import('./Agent').RequestResponse} RequestResponse
- */
-/**
- * @typedef {import('./Agent').RequestError} RequestError
- */
-/**
- * @typedef {import('./Agent').Auth} Auth
- */
-
 /**
  * Particle Cloud API wrapper.
  *
@@ -22,7 +11,12 @@ const Client = require('./Client');
  *
  * Most Particle methods take a single unnamed argument object documented as
  * `options` with key/value pairs for each option.
+ *
+ * @typedef {import('./Agent').RequestResponse} RequestResponse
+ * @typedef {import('./Agent').RequestError} RequestError
+ * @typedef {import('./Agent').Auth} Auth
  */
+// These typedef avoid importing the type on every @return statement
 class Particle {
     /**
      * Contructor for the Cloud API wrapper.
@@ -243,18 +237,20 @@ class Particle {
      * @param {String} options.username     Email of the new user
      * @param {String} options.password     Password
      * @param {String} options.accountInfo  Object that contains account information fields such as user real name, company name, business account flag etc
+     * @param {Object} [options.utm]        Object that contains info about the campaign that lead to this user creation
      * @param {Object} [options.headers]    Key/Value pairs like `{ 'X-FOO': 'foo', X-BAR: 'bar' }` to send as headers.
      * @param {Object} [options.context]    Request context
      * @returns {Promise} A promise
      */
-    createUser({ username, password, accountInfo, headers, context }){
+    createUser({ username, password, accountInfo, utm, headers, context }){
         return this.post({
             uri: '/v1/users',
             headers,
             data: {
                 username,
                 password,
-                account_info : accountInfo
+                account_info: accountInfo,
+                utm
             },
             context
         });
@@ -667,6 +663,42 @@ class Particle {
         return this.put({ uri, auth, headers, data, context });
     }
 
+    /**
+     * Disable device protection.
+     *
+     * @param {Object} options                   Options for this API call.
+     * @param {String} options.deviceId          Device ID or name.
+     * @param {String} options.action            Request action: `prepare` or `confirm`.
+     * @param {String} [options.org]             Organziation ID or slug.
+     * @param {String} [options.product]         Product ID or slug.
+     * @param {String} [options.serverNonce]     Base64-encoded server nonce. Mandatory if `action` is `confirm`,
+     * @param {String} [options.deviceNonce]     Base64-encoded device nonce. Mandatory if `action` is `confirm`,
+     * @param {String} [options.deviceSignature] Base64-encoded device signature. Mandatory if `action` is `confirm`,
+     * @param {String} [options.devicePublicKeyFingerprint] Base64-encoded fingerprint of the device public key.
+     *                                           Mandatory if `action` is `confirm`,
+     * @param {Auth}   [options.auth]            Access token or basic auth object. Can be ignored if provided in constructor.
+     * @param {Object} [options.headers]         Key/value pairs to send as headers.
+     * @param {Object} [options.context]         Request context.
+     * @returns {Promise} A promise
+     */
+    unprotectDevice({ deviceId, org, product, action, serverNonce, deviceNonce, deviceSignature, devicePublicKeyFingerprint, auth, headers, context }) {
+        const data = { action };
+        if (deviceNonce !== undefined) {
+            data.device_nonce = deviceNonce;
+        }
+        if (serverNonce !== undefined) {
+            data.server_nonce = serverNonce;
+        }
+        if (deviceSignature !== undefined) {
+            data.device_signature = deviceSignature;
+        }
+        if (devicePublicKeyFingerprint !== undefined) {
+            data.device_public_key_fingerprint = devicePublicKeyFingerprint;
+        }
+        const uri = this.deviceUri({ deviceId, product, org }) + '/unprotect';
+        return this.put({ uri, data, auth, headers, context });
+    }
+
     /**
      * Provision a new device for products that allow self-provisioning
      * @param {Object} options            Options for this API call
@@ -712,16 +744,6 @@ class Particle {
         });
     }
 
-    changeProduct({ deviceId, productId, auth, headers, context }){
-        return this.put({
-            uri: `/v1/devices/${deviceId}`,
-            auth,
-            headers,
-            data: { product_id: productId },
-            context
-        });
-    }
-
     /**
      * Get the value of a device variable
      * @param {Object} options            Options for this API call
@@ -2637,11 +2659,18 @@ class Particle {
      * @param {Object} options           Options for this API call
      * @param {String} options.deviceId  Device ID to access
      * @param {String} [options.product] Device only in this product ID or slug
+     * @param {String} [options.org]     Device only in this organization ID or slug
      * @private
      * @returns {string} URI
      */
-    deviceUri({ deviceId, product }){
-        return product ? `/v1/products/${product}/devices/${deviceId}` : `/v1/devices/${deviceId}`;
+    deviceUri({ deviceId, product, org }){
+        if (org) {
+            return `/v1/orgs/${org}/devices/${deviceId}`;
+        }
+        if (product) {
+            return `/v1/products/${product}/devices/${deviceId}`;
+        }
+        return `/v1/devices/${deviceId}`;
     }
 
     /**

package/test/Particle.spec.js

@@ -352,7 +352,28 @@ describe('ParticleAPI', () => {
                         data: {
                             username: props.username,
                             password: props.password,
-                            account_info: props.accountInfo
+                            account_info: props.accountInfo,
+                            utm: undefined
+                        },
+                        context: {}
+                    });
+                });
+            });
+            it('allows sending utm parameters', () => {
+                props.utm = { utm_source: 'web' };
+                return api.createUser(props).then(( results ) => {
+                    results.should.eql({
+                        uri: '/v1/users',
+                        method: 'post',
+                        auth: undefined,
+                        headers: props.headers,
+                        data: {
+                            username: props.username,
+                            password: props.password,
+                            account_info: props.accountInfo,
+                            utm: {
+                                utm_source: 'web'
+                            }
                         },
                         context: {}
                     });
@@ -796,19 +817,6 @@ describe('ParticleAPI', () => {
             });
         });
 
-        describe('.changeProduct', () => {
-            it('generates request', () => {
-                return api.changeProduct(props).then(Common.expectDeviceUrlAndToken);
-            });
-
-            it('sends proper data', () => {
-                return api.changeProduct(props).then(({ data }) => {
-                    data.should.be.instanceOf(Object);
-                    data.product_id.should.equal(props.productId);
-                });
-            });
-        });
-
         describe('.getVariable', () => {
             describe('user scope', () => {
                 it('generates request', () => {
@@ -2880,6 +2888,32 @@ describe('ParticleAPI', () => {
                 });
             });
         });
+
+        describe('.unprotectDevice', () => {
+            it('generates request', () => {
+                return api.unprotectDevice(Object.assign({}, propsWithProduct, {
+                    action: 'action',
+                    deviceNonce: 'device-nonce',
+                    serverNonce: 'server-nonce',
+                    deviceSignature: 'device-signature',
+                    devicePublicKeyFingerprint: 'device-public-key-fingerprint'
+                })).then((results) => {
+                    results.should.match({
+                        method: 'put',
+                        uri: `/v1/products/${product}/devices/${props.deviceId}/unprotect`,
+                        auth: props.auth,
+                        headers: props.headers,
+                        data: {
+                            action: 'action',
+                            device_nonce: 'device-nonce',
+                            server_nonce: 'server-nonce',
+                            device_signature: 'device-signature',
+                            device_public_key_fingerprint: 'device-public-key-fingerprint'
+                        }
+                    });
+                });
+            });
+        });
     });
 
     describe('backwards-compatibility function aliases', () => {
@@ -2901,6 +2935,12 @@ describe('ParticleAPI', () => {
                 uri.should.equal('/v1/products/xyz/devices/abc');
             });
         });
+        describe('org scope', () => {
+            it('gets the org device uri', () => {
+                const uri = api.deviceUri({ deviceId: 'abc', org: 'xyz' });
+                uri.should.equal('/v1/orgs/xyz/devices/abc');
+            });
+        });
     });