particle-api-js 10.4.1 → 10.4.3

package/package.json

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

package/src/Agent.js

@@ -103,7 +103,7 @@ class Agent {
      * @param {string} params.uri        The URI to request
      * @param {Auth}   [params.auth]     Authorization token to use
      * @param {object} [params.headers]  Key/Value pairs like `{ 'X-FOO': 'foo', X-BAR: 'bar' }` to send as headers.
-     * @param {object} [params.data]     Key/Value pairs of query params
+     * @param {object} [params.data]     Request body
      * @param {object} [params.context]  The invocation context, describing the tool and project
      * @returns {Promise<RequestResponse, RequestError>} A promise that resolves with either the requested data or an error object
      */
@@ -117,12 +117,13 @@ class Agent {
      * @param {string} params.uri        The URI to request
      * @param {Auth}   [params.auth]     Authorization token to use
      * @param {object} [params.headers]  Key/Value pairs like `{ 'X-FOO': 'foo', X-BAR: 'bar' }` to send as headers.
-     * @param {object} [params.data]     Key/VAlue pairs of query params
+     * @param {object} [params.data]     Request body
+     * @param {object}          [params.query]    Key/Value pairs of query params or a correctly formatted string
      * @param {object} [params.context]  The invocation context, describing the tool and project
      * @returns {Promise<RequestResponse, RequestError>} A promise that resolves with either the requested data or an error object
      */
-    put({ uri, auth, headers, data, context }) {
-        return this.request({ uri, method: 'put', auth, headers, data, context });
+    put({ uri, auth, headers, data, query, context }) {
+        return this.request({ uri, method: 'put', auth, headers, data, query, context });
     }
 
     /**
@@ -131,7 +132,7 @@ class Agent {
      * @param {string} params.uri        The URI to request
      * @param {Auth}   [params.auth]     Authorization token to use
      * @param {object} [params.headers]  Key/Value pairs like `{ 'X-FOO': 'foo', X-BAR: 'bar' }` to send as headers.
-     * @param {object} [params.data]     Key/Value pairs of query params
+     * @param {object} [params.data]     Request body
      * @param {object} [params.context]  The invocation context, describing the tool and project
      * @returns {Promise<RequestResponse, RequestError>} A promise that resolves with either the requested data or an error object
      */

package/src/Particle.js

@@ -243,18 +243,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
         });
@@ -2162,7 +2164,7 @@ class Particle {
      * @param {Object} options                The options for creating the logic function.
      * @param {Auth}   [options.auth]         The access token or basic auth object. Can be ignored if provided in constructor
      * @param {string} [options.org]          The Organization ID or slug. If not provided, the request will go to your sandbox account.
-     * @param {string} options.logicFunction  The logic function object containing the function details.
+     * @param {Object} options.logicFunction  The logic function object containing the function details.
      * @param {Object} [options.headers]      Key/Value pairs like `{ 'X-FOO': 'foo', X-BAR: 'bar' }` to send as headers.
      * @param {Object} [options.context]      Request context
      *
@@ -2208,7 +2210,7 @@ class Particle {
      * @param {Auth}   [options.auth]           The access token or basic auth object. Can be ignored if provided in constructor
      * @param {string} [options.org]            The Organization ID or slug. If not provided, the request will go to your sandbox account.
      * @param {string} options.logicFunctionId  The ID of the logic function to update.
-     * @param {string} options.logicFunction    The logic function object containing the logic function details.
+     * @param {Object} options.logicFunction    The logic function object containing the logic function details.
      * @param {Object} [options.headers]        Key/Value pairs like `{ 'X-FOO': 'foo', X-BAR: 'bar' }` to send as headers.
      * @param {Object} [options.context]        Request context.
      *
@@ -2275,7 +2277,7 @@ class Particle {
      * @param {Object} options                  The options for the request.
      * @param {Auth}   [options.auth]           The access token or basic auth object. Can be ignored if provided in constructor
      * @param {string} [options.org]            The Organization ID or slug. If not provided, the request will go to your sandbox account.
-     * @param {number} options.logicFunctionId  The ID of the logic function for which to retrieve the logic runs.
+     * @param {string} options.logicFunctionId  The ID of the logic function for which to retrieve the logic runs.
      * @param {Object} [options.headers]        Key/Value pairs like `{ 'X-FOO': 'foo', X-BAR: 'bar' }` to send as headers.
      * @param {Object} [options.context]        Request context
      *
@@ -2296,8 +2298,8 @@ class Particle {
      * @param {Object} options                  The options for the request.
      * @param {Auth}   [options.auth]           The access token or basic auth object. Can be ignored if provided in constructor
      * @param {string} [options.org]            The Organization ID or slug. If not provided, the request will go to your sandbox account.
-     * @param {number} options.logicFunctionId  The ID of the logic function for which to retrieve the logic run.
-     * @param {number} options.logicRunId       The ID of the logic run to retrieve.
+     * @param {string} options.logicFunctionId  The ID of the logic function for which to retrieve the logic run.
+     * @param {string} options.logicRunId       The ID of the logic run to retrieve.
      * @param {Object} [options.headers]        Key/Value pairs like `{ 'X-FOO': 'foo', X-BAR: 'bar' }` to send as headers.
      * @param {Object} [options.context]        Request context
      *
@@ -2318,8 +2320,8 @@ class Particle {
      * @param {Object} options                  The options for the request.
      * @param {Auth}   [options.auth]           The access token or basic auth object. Can be ignored if provided in constructor
      * @param {string} [options.org]            The unique identifier of the organization.
-     * @param {number} options.logicFunctionId  The ID of the logic function for which to retrieve the logic run logs.
-     * @param {number} options.logicRunId       The ID of the logic run for which to retrieve the logs.
+     * @param {string} options.logicFunctionId  The ID of the logic function for which to retrieve the logic run logs.
+     * @param {string} options.logicRunId       The ID of the logic run for which to retrieve the logs.
      * @param {Object} [options.headers]        Key/Value pairs like `{ 'X-FOO': 'foo', X-BAR: 'bar' }` to send as headers.
      * @param {Object} [options.context]        Request context
      *
@@ -2477,23 +2479,31 @@ class Particle {
         });
     }
 
+    /**
+     * @typedef {"Replace" | "Merge"} SetMode
+     */
+
     /**
      * Set ledger instance data.
      *
-     * @param {Object} options             The options for updating the ledger instance.
-     * @param {Auth}   [options.auth]      The access token or basic auth object. Can be ignored if provided in constructor
-     * @param {string} [options.org]       The Organization ID or slug. If not provided, the request will go to your sandbox account.
-     * @param {string} options.ledgerName  Ledger name.
-     * @param {string} options.scopeValue  Scope value.
-     * @param {object} options.instance    The instance with the data
-     * @param {Object} [options.headers]   Key/Value pairs like `{ 'X-FOO': 'foo', X-BAR: 'bar' }` to send as headers.
-     * @param {Object} [options.context]   Request context.
+     * @param {Object}  options             The options for updating the ledger instance.
+     * @param {Auth}    [options.auth]      The access token or basic auth object. Can be ignored if provided in constructor
+     * @param {string}  [options.org]       The Organization ID or slug. If not provided, the request will go to your sandbox account.
+     * @param {string}  options.ledgerName  Ledger name.
+     * @param {string}  options.scopeValue  Scope value.
+     * @param {object}  options.instance    The instance with the data
+     * @param {SetMode} [options.setMode]   How the data should be set with existing data. Default is "Replace"
+     * @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<RequestResponse>} A promise that resolves to the updated ledger instance data.
      */
-    setLedgerInstance({ auth, org, ledgerName, scopeValue, instance, headers, context }) {
+    setLedgerInstance({ auth, org, ledgerName, scopeValue, instance, setMode, headers, context }) {
         return this.put({
             uri: this._namespacedPath(org, `ledgers/${ledgerName}/instances/${scopeValue}`),
+            query: {
+                set_mode: setMode
+            },
             auth,
             data: { instance },
             headers,
@@ -2685,7 +2695,7 @@ class Particle {
      * @param {string}          params.uri        The URI to request
      * @param {Auth}            [params.auth]     Authorization token to use
      * @param {object}          [params.headers]  Key/Value pairs like `{ 'X-FOO': 'foo', X-BAR: 'bar' }` to send as headers.
-     * @param {string | object} [params.data]     Key/Value pairs of query params or a correctly formatted string
+     * @param {string | object} [params.data]     Request body
      * @param {object}          [params.context]  The invocation context, describing the tool and project
      * @returns {Promise<RequestResponse, RequestError>} A promise that resolves with either the requested data or an error object
      */
@@ -2701,14 +2711,15 @@ class Particle {
      * @param {string}          params.uri        The URI to request
      * @param {Auth}            [params.auth]     Authorization token to use
      * @param {object}          [params.headers]  Key/Value pairs like `{ 'X-FOO': 'foo', X-BAR: 'bar' }` to send as headers.
-     * @param {string | object} [params.data]     Key/Value pairs of query params or a correctly formatted string
+     * @param {string | object} [params.data]     Request body
+     * @param {object}          [params.query]    Key/Value pairs of query params or a correctly formatted string
      * @param {object}          [params.context]  The invocation context, describing the tool and project
      * @returns {Promise<RequestResponse, RequestError>} A promise that resolves with either the requested data or an error object
      */
-    put({ uri, auth, headers, data, context }){
+    put({ uri, auth, headers, data, query, context }){
         context = this._buildContext(context);
         auth = this._getActiveAuthToken(auth);
-        return this.agent.put({ uri, auth, headers, data, context });
+        return this.agent.put({ uri, auth, headers, data, query, context });
     }
 
     /**
@@ -2717,7 +2728,7 @@ class Particle {
      * @param {string}          params.uri        The URI to request
      * @param {Auth}            [params.auth]     Authorization token to use
      * @param {object}          [params.headers]  Key/Value pairs like `{ 'X-FOO': 'foo', X-BAR: 'bar' }` to send as headers.
-     * @param {string | object} [params.data]     Key/Value pairs of query params or a correctly formatted string
+     * @param {string | object} [params.data]     Request body
      * @param {object}          [params.context]  The invocation context, describing the tool and project
      * @returns {Promise<RequestResponse, RequestError>} A promise that resolves with either the requested data or an error object
      */

package/test/Agent.spec.js

@@ -78,8 +78,8 @@ describe('Agent', () => {
 
         it('can PUT a resource', () => {
             method = 'put';
-            return agent.put({ uri, auth, headers, data, context }).then(() => {
-                expect(agent.request).to.be.calledWith({ uri, method, auth, headers, data, context });
+            return agent.put({ uri, auth, headers, data, context, query }).then(() => {
+                expect(agent.request).to.be.calledWith({ uri, method, auth, headers, data, context, query });
             });
         });
 

package/test/FakeAgent.js

@@ -11,8 +11,8 @@ class FakeAgent {
         return this.request({ uri, method: 'post', auth, headers, data, context });
     }
 
-    put({ uri, auth, headers, data, context }){
-        return this.request({ uri, method: 'put', auth, headers, data, context });
+    put({ uri, auth, headers, data, query, context }){
+        return this.request({ uri, method: 'put', auth, headers, data, query, context });
     }
 
     delete({ uri, auth, headers, data, context }){
@@ -20,7 +20,7 @@ class FakeAgent {
     }
 
     request(opts){
-        return new Promise((resolve) => resolve(opts));
+        return Promise.resolve(opts);
     }
 }
 module.exports = FakeAgent;

package/test/Particle.spec.js

@@ -66,7 +66,7 @@ const props = {
     clientId: 'client-123',
     type: 'web',
     redirect_uri: 'https://example.com',
-    scope: '',
+    scope: 'Owner',
     deviceName: 'test-device',
     page: 5,
     perPage: 50,
@@ -78,7 +78,7 @@ const props = {
     notes: 'A fancy Photon',
     desiredFirmwareVersion: 42,
     flash: false,
-    version: 42,
+    version: '42',
     title: 'prod',
     description: 'ready for production',
     file: new Buffer('ELF...'),
@@ -96,8 +96,8 @@ const props = {
     dateRange: '2020-05-15T18:29:45.000Z,2020-05-19T18:29:45.000Z',
     rectBl: '56.185412,-4.049868',
     rectTr: '56.571537,-5.385920',
-    logicFunctionId: 1,
-    logicRunId: 1,
+    logicFunctionId: 'ea838324-a4a7-4fa6-b278-95bdaed7114b',
+    logicRunId: 'd0580956-71dc-4f11-89e2-987dcf82a86f',
     logicFunction: {
         enabled: true,
         name: 'function-1',
@@ -140,12 +140,13 @@ const props = {
         scope: 'Owner',
         name: 'myledger',
         description: 'my ledger',
-        direction: 'Downstream'
+        direction: 'CloudOnly'
     },
-    scopeValue: '1234',
+    scopeValue: 'abc1234',
     instance: {
         property: 'yes'
-    }
+    },
+    setMode: 'Replace'
 };
 
 const product = 'ze-product-v1';
@@ -315,6 +316,7 @@ describe('ParticleAPI', () => {
                         method: 'put',
                         auth: props.auth,
                         headers: props.headers,
+                        query: undefined,
                         data: {
                             current_password: props.password,
                         },
@@ -350,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: {}
                     });
@@ -1462,6 +1485,7 @@ describe('ParticleAPI', () => {
                             method: 'put',
                             auth: 'X',
                             headers: undefined,
+                            query: undefined,
                             data: {
                                 account_info: { first_name: 'John', last_name: 'Scully' }
                             },
@@ -1480,6 +1504,7 @@ describe('ParticleAPI', () => {
                             method: 'put',
                             auth: 'X',
                             headers: undefined,
+                            query: undefined,
                             data: {
                                 current_password: 'blabla',
                                 username: 'john@skul.ly'
@@ -1496,6 +1521,7 @@ describe('ParticleAPI', () => {
                             method: 'put',
                             auth: 'X',
                             headers: undefined,
+                            query: undefined,
                             data: {
                                 current_password: 'blabla',
                                 username: 'john@skul.ly',
@@ -1516,6 +1542,7 @@ describe('ParticleAPI', () => {
                             method: 'put',
                             auth: 'X',
                             headers: undefined,
+                            query: undefined,
                             data: {
                                 current_password: 'blabla',
                                 password: 'blabla2'
@@ -1533,6 +1560,7 @@ describe('ParticleAPI', () => {
                             uri: '/v1/user',
                             auth: 'X',
                             headers: undefined,
+                            query: undefined,
                             data: {
                                 current_password: 'blabla',
                                 password: 'blabla2',
@@ -2622,30 +2650,7 @@ describe('ParticleAPI', () => {
                         uri: `/v1/orgs/${org}/logic/functions`,
                         auth: props.auth,
                         data: {
-                            logic_function: {
-                                enabled: true,
-                                name: 'function-1',
-                                description: 'hello world',
-                                source: {
-                                    type: 'JavaScript',
-                                    code: 'console.log("hello from function-1");'
-                                },
-                                logic_triggers: [
-                                    {
-                                        type: 'Event',
-                                        enabled: true,
-                                        product_id: parseInt(props.productId),
-                                        event_name: props.event,
-                                    },
-                                    {
-                                        type: 'Scheduled',
-                                        enabled: true,
-                                        cron: '0 0 1 * *',
-                                        start_at: '2021-05-15T18:29:45.000Z',
-                                        end_at: '2021-05-19T18:29:45.000Z',
-                                    }
-                                ]
-                            }
+                            logic_function: props.logicFunction
                         }
                     });
                 });
@@ -2672,30 +2677,7 @@ describe('ParticleAPI', () => {
                         uri: `/v1/orgs/${org}/logic/functions/${props.logicFunctionId}`,
                         auth: props.auth,
                         data: {
-                            logic_function: {
-                                enabled: true,
-                                name: 'function-1',
-                                description: 'hello world',
-                                source: {
-                                    type: 'JavaScript',
-                                    code: 'console.log("hello from function-1");'
-                                },
-                                logic_triggers: [
-                                    {
-                                        type: 'Event',
-                                        enabled: true,
-                                        product_id: parseInt(props.productId),
-                                        event_name: props.event,
-                                    },
-                                    {
-                                        type: 'Scheduled',
-                                        enabled: true,
-                                        cron: '0 0 1 * *',
-                                        start_at: '2021-05-15T18:29:45.000Z',
-                                        end_at: '2021-05-19T18:29:45.000Z',
-                                    }
-                                ]
-                            }
+                            logic_function: props.logicFunction
                         }
                     });
                 });
@@ -2784,12 +2766,7 @@ describe('ParticleAPI', () => {
                         uri: `/v1/orgs/${org}/ledgers`,
                         auth: props.auth,
                         data: {
-                            ledger: {
-                                scope: 'Owner',
-                                name: 'myledger',
-                                description: 'my ledger',
-                                direction: 'Downstream'
-                            }
+                            ledger: props.ledger
                         }
                     });
                 });
@@ -2816,12 +2793,7 @@ describe('ParticleAPI', () => {
                         uri: `/v1/orgs/${org}/ledgers/${props.ledgerName}`,
                         auth: props.auth,
                         data: {
-                            ledger: {
-                                scope: 'Owner',
-                                name: 'myledger',
-                                description: 'my ledger',
-                                direction: 'Downstream'
-                            }
+                            ledger: props.ledger
                         }
                     });
                 });
@@ -2870,11 +2842,12 @@ describe('ParticleAPI', () => {
                     results.should.match({
                         method: 'put',
                         uri: `/v1/orgs/${org}/ledgers/${props.ledgerName}/instances/${props.scopeValue}`,
+                        query: {
+                            set_mode: props.setMode
+                        },
                         auth: props.auth,
                         data: {
-                            instance: {
-                                property: 'yes'
-                            }
+                            instance: props.instance
                         }
                     });
                 });
@@ -3073,7 +3046,7 @@ describe('ParticleAPI', () => {
 
             it('calls _buildContext and _getActiveAuthToken from put', () => {
                 api.agent.put = sinon.stub().returns(result);
-                const options = { uri, auth, headers, data, context };
+                const options = { uri, auth, headers, data, context, query };
                 const res = api.put(options);
                 expect(res).to.equal(result);
                 expect(api.agent.put).to.have.been.calledWith({
@@ -3081,6 +3054,7 @@ describe('ParticleAPI', () => {
                     auth,
                     headers,
                     data,
+                    query,
                     context: contextResult
                 });
             });