particle-api-js 10.1.0 → 10.3.0

package/package.json

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

package/src/Particle.js

@@ -2115,48 +2115,72 @@ class Particle {
 	}
 
 	/**
-	 * Creates a new logic block in the specified organization using the provided block data.
+	 * Executes the provided logic function once and returns the result. No logs, runs, etc are saved
 	 *
-	 * When you create a logic block with PubSub matchers, events will immediately
-	 * start being handled by the block code.
+	 * NOTE: Any external interactions such as Particle.publish will actually occur when the logic is executed.
 	 *
-	 * When you create a Chron matcher, it will immediately be scheduled at the next time
+	 * @param {Object} options         The options for creating the logic function.
+	 * @param {Object} options.auth    Access token
+	 * @param {string | undefined} options.org     The Organization ID or slug. If not provided, the request will go to your sandbox account.
+	 * @param {string}  options.logic   The logic "function" which will be executed once
+	 * @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 created logic function data.
+	 */
+	executeLogic({ auth, org, logic, headers, context }) {
+		return this.post({
+			uri: this._namespacedPath(org, 'logic/execute'),
+			auth,
+			data: logic,
+			headers,
+			context
+		});
+	}
+
+	/**
+	 * Creates a new logic function in the specified organization or sandbox using the provided function data.
+	 *
+	 * When you create a logic function with Event logic triggers, events will immediately
+	 * start being handled by the function code.
+	 *
+	 * When you create a Scheduled logic trigger, it will immediately be scheduled at the next time
 	 * according to the cron and start_at properties.
 	 *
-	 * @param {Object} options         The options for creating the logic block.
+	 * @param {Object} options         The options for creating the logic function.
 	 * @param {Object} options.auth    Access token
-	 * @param {string} options.org     The name of the organization.
-	 * @param {string}  options.block   The block object containing the block details.
+	 * @param {string | undefined} 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.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 created logic block data.
+	 * @returns {Promise<RequestResponse>} A promise that resolves to the created logic function data.
 	 */
-	createLogicBlock({ auth, org, block, headers, context }) {
+	createLogicFunction({ auth, org, logicFunction, headers, context }) {
 		return this.post({
-			uri: `/v1/orgs/${org}/blocks`,
+			uri: this._namespacedPath(org, 'logic/functions'),
 			auth,
-			data: { block },
+			data: { logic_function: logicFunction },
 			headers,
 			context
 		});
 	}
 
 	/**
-	 * Get a logic block in the specified organization by block ID.
+	 * Get a logic function in the specified organization or sandbox by logic function ID.
 	 *
-	 * @param {Object} options         The options for the logic block.
+	 * @param {Object} options         The options for the logic function.
 	 * @param {Object} options.auth    Access token
-	 * @param {string} options.org     The name of the organization.
-	 * @param {string} options.blockId The ID of the block to retrieve.
+	 * @param {string | undefined} 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 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
 	 *
-	 * @returns {Promise<RequestResponse>} A promise that resolves to the specified logic block data.
+	 * @returns {Promise<RequestResponse>} A promise that resolves to the specified logic function data.
 	 */
-	getLogicBlock({ auth, org, blockId, headers, context }) {
+	getLogicFunction({ auth, org, logicFunctionId, headers, context }) {
 		return this.get({
-			uri: `/v1/orgs/${org}/blocks/${blockId}`,
+			uri: this._namespacedPath(org, `logic/functions/${logicFunctionId}`),
 			auth,
 			headers,
 			context
@@ -2164,45 +2188,45 @@ class Particle {
 	}
 
 	/**
-	 * Updates an existing logic block in the specified organization using the provided block data.
+	 * Updates an existing logic function in the specified organization or sandbox using the provided function data.
 	 *
-	 * If you include an id on a matcher, it will update the matcher in place.
+	 * If you include an id on a logic trigger, it will update the logic trigger in place.
 	 *
-	 * @param {Object} options          The options for updating the logic block.
+	 * @param {Object} options          The options for updating the logic function.
 	 * @param {Object} options.auth     The authentication object with the API key.
-	 * @param {string} options.org      The unique identifier of the organization.
-	 * @param {string} options.blockId  The ID of the block to update.
-	 * @param {string} options.block     The block object containing the block details.
+	 * @param {string | undefined} 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.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 logic block data.
+	 * @returns {Promise<RequestResponse>} A promise that resolves to the updated logic function data.
 	 */
-	updateLogicBlock({ auth, org, blockId, block, headers, context }) {
+	updateLogicFunction({ auth, org, logicFunctionId, logicFunction, headers, context }) {
 		return this.put({
-			uri: `/v1/orgs/${org}/blocks/${blockId}`,
+			uri: this._namespacedPath(org, `logic/functions/${logicFunctionId}`),
 			auth,
-			data: { block },
+			data: { logic_function: logicFunction },
 			headers,
 			context
 		});
 	}
 
 	/**
-	 * Deletes a logic block in the specified organization by block ID.
+	 * Deletes a logic function in the specified organization or sandbox by logic function ID.
 	 *
-	 * @param {Object} options          The options for deleting the logic block.
+	 * @param {Object} options          The options for deleting the logic function.
 	 * @param {Object} options.auth     The authentication object with the API key.
-	 * @param {string} options.org      The unique identifier of the organization.
-	 * @param {string} options.blockId  The ID of the block to delete.
+	 * @param {string | undefined} 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 delete.
 	 * @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 an object containing the deleted block ID.
+	 * @returns {Promise<RequestResponse>} A promise that resolves to an object containing the deleted logic function ID.
 	 */
-	deleteLogicBlock({ auth, org, blockId, headers, context }) {
+	deleteLogicFunction({ auth, org, logicFunctionId, headers, context }) {
 		return this.delete({
-			uri: `/v1/orgs/${org}/blocks/${blockId}`,
+			uri: this._namespacedPath(org, `logic/functions/${logicFunctionId}`),
 			auth,
 			headers,
 			context
@@ -2210,19 +2234,19 @@ class Particle {
 	}
 
 	/**
-	 * Lists all logic blocks in the specified organization.
+	 * Lists all logic functions in the specified organization or sandbox.
 	 *
-	 * @param {Object} options          The options for listing logic blocks.
+	 * @param {Object} options          The options for listing logic functions.
 	 * @param {Object} options.auth     The authentication object with the API key.
-	 * @param {string} options.org      The unique identifier of the organization.
+	 * @param {string | undefined} options.org     The Organization ID or slug. If not provided, the request will go to your sandbox account.
 	 * @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 an array of logic block data.
+	 * @returns {Promise<RequestResponse>} A promise that resolves to an array of logic functions data.
 	 */
-	listLogicBlocks({ auth, org, headers, context }) {
+	listLogicFunctions({ auth, org, headers, context }) {
 		return this.get({
-			uri: `/v1/orgs/${org}/blocks`,
+			uri: this._namespacedPath(org, 'logic/functions'),
 			auth,
 			headers,
 			context
@@ -2230,20 +2254,20 @@ class Particle {
 	}
 
 	/**
-	 * Lists all block runs for the specified block.
+	 * Lists all logic runs for the specified logic function in the specified organization or sandbox.
 	 *
 	 * @param {Object} options          The options for the request.
 	 * @param {Object} options.auth     Access token
-	 * @param {string} options.org      The unique identifier of the organization.
-	 * @param {number} options.blockId  The ID of the block for which to retrieve the block runs.
+	 * @param {string | undefined} 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 {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 an array of block run data.
+	 * @returns {Promise<RequestResponse>} A promise that resolves to an array of logic run data.
 	 */
-	listBlockRuns({ auth, org, blockId, headers, context }) {
+	listLogicRuns({ auth, org, logicFunctionId, headers, context }) {
 		return this.get({
-			uri: `/v1/orgs/${org}/blocks/${blockId}/runs`,
+			uri: this._namespacedPath(org, `logic/functions/${logicFunctionId}/runs`),
 			auth,
 			headers,
 			context
@@ -2251,21 +2275,21 @@ class Particle {
 	}
 
 	/**
-	 * Retrieves a block run by its ID for the specified block.
+	 * Retrieves a logic run by its ID for the specified logic function in the specified organization or sandbox.
 	 *
 	 * @param {Object} options          The options for the request.
 	 * @param {Object} options.auth     Access token
-	 * @param {string} options.org      The unique identifier of the organization.
-	 * @param {number} options.blockId  The ID of the block for which to retrieve the block run.
-	 * @param {number} options.runId    The ID of the block run to retrieve.
+	 * @param {string | undefined} 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 {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 an array of block run data for the specified block run ID.
+	 * @returns {Promise<RequestResponse>} A promise that resolves to an array of logic run data for the specified logic run ID.
 	 */
-	getBlockRun({ auth, org, blockId, runId, headers, context }) {
+	getLogicRun({ auth, org, logicFunctionId, logicRunId, headers, context }) {
 		return this.get({
-			uri: `/v1/orgs/${org}/blocks/${blockId}/runs/${runId}`,
+			uri: this._namespacedPath(org, `logic/functions/${logicFunctionId}/runs/${logicRunId}`),
 			auth,
 			headers,
 			context
@@ -2273,21 +2297,21 @@ class Particle {
 	}
 
 	/**
-	 * Retrieves the logs for a block run by its ID for the specified block.
+	 * Retrieves the logs for a logic run by its ID for the specified logic function in the specified organization or sandbox.
 	 *
 	 * @param {Object} options          The options for the request.
 	 * @param {Object} options.auth     Access token
-	 * @param {string} options.org      The unique identifier of the organization.
-	 * @param {number} options.blockId  The ID of the block for which to retrieve the block run logs.
-	 * @param {number} options.runId    The ID of the block run for which to retrieve the logs.
+	 * @param {string | undefined} 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 {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 logs for the specified block run ID.
+	 * @returns {Promise<RequestResponse>} A promise that resolves to the logs for the specified logic run ID.
 	 */
-	getBlockRunLog({ auth, org, blockId, runId, headers, context }) {
+	getLogicRunLogs({ auth, org, logicFunctionId, logicRunId, headers, context }) {
 		return this.get({
-			uri: `/v1/orgs/${org}/blocks/${blockId}/runs/${runId}/logs`,
+			uri: this._namespacedPath(org, `logic/functions/${logicFunctionId}/runs/${logicRunId}/logs`),
 			auth,
 			headers,
 			context
@@ -2295,11 +2319,11 @@ class Particle {
 	}
 
 	/**
-	 * Creates a new ledger definition in the specified organization.
+	 * Creates a new ledger definition in the specified organization or sandbox.
 	 *
 	 * @param {Object} options         The options for creating the ledger definition.
 	 * @param {Object} options.auth    Access token
-	 * @param {string} options.org     The name of the organization.
+	 * @param {string | undefined} options.org     The Organization ID or slug. If not provided, the request will go to your sandbox account.
 	 * @param {object} options.definition   The ledger definition object.
 	 * @param {object} options.ledger     The ledger definition object.
 	 * @param {Object} [options.headers] Key/Value pairs like `{ 'X-FOO': 'foo', X-BAR: 'bar' }` to send as headers.
@@ -2309,7 +2333,7 @@ class Particle {
 	 */
 	createLedger({ auth, org, ledger, headers, context }) {
 		return this.post({
-			uri: `/v1/orgs/${org}/ledgers`,
+			uri: this._namespacedPath(org, 'ledgers'),
 			auth,
 			data: { ledger },
 			headers,
@@ -2318,11 +2342,11 @@ class Particle {
 	}
 
 	/**
-	 * Get a ledger definition in the specified organization by ledger name.
+	 * Get a ledger definition in the specified organization or sandbox by ledger name.
 	 *
 	 * @param {Object} options         The options for the ledger definition.
 	 * @param {Object} options.auth    Access token
-	 * @param {string} options.org     The name of the organization.
+	 * @param {string | undefined} options.org     The Organization ID or slug. If not provided, the request will go to your sandbox account.
 	 * @param {string} options.ledgerName The ID of the ledger definition 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
@@ -2331,7 +2355,7 @@ class Particle {
 	 */
 	getLedger({ auth, org, ledgerName, headers, context }) {
 		return this.get({
-			uri: `/v1/orgs/${org}/ledgers/${ledgerName}`,
+			uri: this._namespacedPath(org, `ledgers/${ledgerName}`),
 			auth,
 			headers,
 			context
@@ -2339,11 +2363,11 @@ class Particle {
 	}
 
 	/**
-	 * Updates an existing ledger definition in the specified organization.
+	 * Updates an existing ledger definition in the specified organization or sandbox.
 	 *
 	 * @param {Object} options          The options for updating the ledger definition.
 	 * @param {Object} options.auth     The authentication object with the API key.
-	 * @param {string} options.org      The unique identifier of the organization.
+	 * @param {string | undefined} options.org     The Organization ID or slug. If not provided, the request will go to your sandbox account.
 	 * @param {string} options.ledgerName  Name of the ledger definition to update.
 	 * @param {object} options.ledger     The ledger definition object.
 	 * @param {Object} [options.headers] Key/Value pairs like `{ 'X-FOO': 'foo', X-BAR: 'bar' }` to send as headers.
@@ -2353,7 +2377,7 @@ class Particle {
 	 */
 	updateLedger({ auth, org, ledgerName, ledger, headers, context }) {
 		return this.put({
-			uri: `/v1/orgs/${org}/ledgers/${ledgerName}`,
+			uri: this._namespacedPath(org, `ledgers/${ledgerName}`),
 			auth,
 			data: { ledger },
 			headers,
@@ -2362,11 +2386,11 @@ class Particle {
 	}
 
 	/**
-	 * Archives a ledger definition in the specified organization by ledger name.
+	 * Archives a ledger definition in the specified organization or sandbox by ledger name.
 	 *
 	 * @param {Object} options          The options for archiving the ledger definition.
 	 * @param {Object} options.auth     The authentication object with the API key.
-	 * @param {string} options.org      The unique identifier of the organization.
+	 * @param {string | undefined} options.org     The Organization ID or slug. If not provided, the request will go to your sandbox account.
 	 * @param {string} options.ledgerName  Name of the ledger definition to archive.
 	 * @param {Object} [options.headers] Key/Value pairs like `{ 'X-FOO': 'foo', X-BAR: 'bar' }` to send as headers.
 	 * @param {Object} [options.context] Request context.
@@ -2375,7 +2399,7 @@ class Particle {
 	 */
 	archiveLedger({ auth, org, ledgerName, headers, context }) {
 		return this.delete({
-			uri: `/v1/orgs/${org}/ledgers/${ledgerName}`,
+			uri: this._namespacedPath(org, `ledgers/${ledgerName}`),
 			auth,
 			headers,
 			context
@@ -2383,11 +2407,11 @@ class Particle {
 	}
 
 	/**
-	 * Lists all ledger definitions in the specified organization.
+	 * Lists all ledger definitions in the specified organization or sandbox.
 	 *
 	 * @param {Object} options          The options for listing ledger definitions.
 	 * @param {Object} options.auth     The authentication object with the API key.
-	 * @param {string} options.org      The unique identifier of the organization.
+	 * @param {string | undefined} options.org     The Organization ID or slug. If not provided, the request will go to your sandbox account.
 	 * @param {Object} [options.headers] Key/Value pairs like `{ 'X-FOO': 'foo', X-BAR: 'bar' }` to send as headers.
 	 * @param {Object} [options.context] Request context.
 	 *
@@ -2395,7 +2419,7 @@ class Particle {
 	 */
 	listLedgers({ auth, org, headers, context }) {
 		return this.get({
-			uri: `/v1/orgs/${org}/ledgers`,
+			uri: this._namespacedPath(org, 'ledgers'),
 			auth,
 			headers,
 			context
@@ -2407,7 +2431,7 @@ class Particle {
 	 *
 	 * @param {Object} options         The options for the ledger instance.
 	 * @param {Object} options.auth    Access token
-	 * @param {string} options.org     The name of the organization.
+	 * @param {string | undefined} 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.headers] Key/Value pairs like `{ 'X-FOO': 'foo', X-BAR: 'bar' }` to send as headers.
@@ -2417,7 +2441,7 @@ class Particle {
 	 */
 	getLedgerInstance({ auth, org, ledgerName, scopeValue, headers, context }) {
 		return this.get({
-			uri: `/v1/orgs/${org}/ledgers/${ledgerName}/instances/${scopeValue}`,
+			uri: this._namespacedPath(org, `ledgers/${ledgerName}/instances/${scopeValue}`),
 			auth,
 			headers,
 			context
@@ -2429,7 +2453,7 @@ class Particle {
 	 *
 	 * @param {Object} options          The options for updating the ledger instance.
 	 * @param {Object} options.auth     The authentication object with the API key.
-	 * @param {string} options.org      The unique identifier of the organization.
+	 * @param {string | undefined} 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 ledger instance object.
@@ -2441,7 +2465,7 @@ class Particle {
 	 */
 	setLedgerInstance({ auth, org, ledgerName, scopeValue, data, headers, context }) {
 		return this.put({
-			uri: `/v1/orgs/${org}/ledgers/${ledgerName}/instances/${scopeValue}`,
+			uri: this._namespacedPath(org, `ledgers/${ledgerName}/instances/${scopeValue}`),
 			auth,
 			data: { data },
 			headers,
@@ -2450,11 +2474,11 @@ class Particle {
 	}
 
 	/**
-	 * Delete a ledger instance in the specified organization by ledger name.
+	 * Delete a ledger instance in the specified organization or sandbox by ledger name.
 	 *
 	 * @param {Object} options          The options for archiving the ledger instance.
 	 * @param {Object} options.auth     The authentication object with the API key.
-	 * @param {string} options.org      The unique identifier of the organization.
+	 * @param {string | undefined} options.org     The Organization ID or slug. If not provided, the request will go to your sandbox account.
 	 * @param {string} options.ledgerName  Name of the ledger instance to archive.
 	 * @param {string} options.scopeValue Scope value.
 	 * @param {Object} [options.headers] Key/Value pairs like `{ 'X-FOO': 'foo', X-BAR: 'bar' }` to send as headers.
@@ -2464,7 +2488,7 @@ class Particle {
 	 */
 	deleteLedgerInstance({ auth, org, ledgerName, scopeValue, headers, context }) {
 		return this.delete({
-			uri: `/v1/orgs/${org}/ledgers/${ledgerName}/instances/${scopeValue}`,
+			uri: this._namespacedPath(org, `ledgers/${ledgerName}/instances/${scopeValue}`),
 			auth,
 			headers,
 			context
@@ -2472,11 +2496,11 @@ class Particle {
 	}
 
 	/**
-	 * Lists ledger instances.
+	 * Lists ledger instances in the specified organization or sandbox.
 	 *
 	 * @param {Object} options          The options for listing ledger instances.
 	 * @param {Object} options.auth     The authentication object with the API key.
-	 * @param {string} options.org      The unique identifier of the organization.
+	 * @param {string} [options.org]    The unique identifier of the organization.
 	 * @param {string} options.ledgerName  Name of the ledger instance to archive.
 	 * @param {Object} [options.headers] Key/Value pairs like `{ 'X-FOO': 'foo', X-BAR: 'bar' }` to send as headers.
 	 * @param {Object} [options.context] Request context.
@@ -2485,7 +2509,7 @@ class Particle {
 	 */
 	listLedgerInstances({ auth, org, ledgerName, headers, context }) {
 		return this.get({
-			uri: `/v1/orgs/${org}/ledgers/${ledgerName}/instances`,
+			uri: this._namespacedPath(org, `ledgers/${ledgerName}/instances`),
 			auth,
 			headers,
 			context
@@ -2525,6 +2549,17 @@ class Particle {
 		return product ? `/v1/products/${product}/devices/${deviceId}` : `/v1/devices/${deviceId}`;
 	}
 
+	/**
+	 * Helper for building API paths that support sandbox and org prefixes based on org presence
+	 * @param {string | undefined} org slug or ID
+	 * @param {string} path will be appended to the end of the org/sandbox prefix
+	 * @returns {string} the full combined path
+	 * @private
+	 */
+	_namespacedPath(org, path) {
+		return org ? `/v1/orgs/${org}/${path}` : `/v1/${path}`;
+	}
+
 	/**
 	 * Make a GET request
 	 * @param {object} params