Add scaffolding to publish types

.gitignore

@@ -12,4 +12,5 @@ lib/
 /.idea
 *.tgz
 .vscode
-tmp
+tmp
+/types

package.json

@@ -3,10 +3,11 @@
   "version": "9.4.1",
   "description": "Particle API Client",
   "main": "lib/Particle.js",
+  "types": "types/index.d.ts",
   "scripts": {
     "babel-watch": "babel src -d lib --watch --source-maps",
     "prepublish": "npm run lint && npm run compile",
-    "compile": "babel src -sd lib",
+    "compile": "npm run generate-types && babel src -sd lib",
     "test": "npm run lint && npm run test:unit",
     "test:ci": "npm run lint && npm run test:unit -- --forbid-only && npm run coverage",
     "test:unit": "mocha test/ -R spec --compilers js:babel-register",
@@ -22,7 +23,8 @@
     "preversion": "npm run test && npm run prepublish",
     "reinstall": "rm -rf ./node_modules && npm i",
     "version": "npm run build && npm run docs && npm run update-changelog && git add dist/* docs/*",
-    "update-changelog": "VERSION=`node -p -e \"require('./package.json').version\"` bash -c 'read -p \"Update CHANGELOG.md for version $VERSION and press ENTER when done.\"' && git add CHANGELOG.md"
+    "update-changelog": "VERSION=`node -p -e \"require('./package.json').version\"` bash -c 'read -p \"Update CHANGELOG.md for version $VERSION and press ENTER when done.\"' && git add CHANGELOG.md",
+    "generate-types": "tsc"
   },
   "repository": {
     "type": "git",
@@ -46,6 +48,7 @@
   ],
   "license": "Apache-2.0",
   "devDependencies": {
+    "@types/node": "^16.18.32",
     "babel-cli": "^6.9.0",
     "babel-eslint": "^6.0.4",
     "babel-plugin-add-module-exports": "^0.1.2",
@@ -73,6 +76,7 @@
     "should": "^9.0.0",
     "sinon": "^7.2.5",
     "sinon-chai": "^3.7.0",
+    "typescript": "^5.0.4",
     "watchify": "^3.7.0"
   },
   "dependencies": {

src/Particle.js

@@ -433,6 +433,7 @@ class Particle {
 	 * Claim a device to the account. The device must be online and unclaimed.
 	 * @param {Object} options            Options for this API call
 	 * @param {String} options.deviceId   Device ID
+	 * @param {Boolean} [options.requestTransfer]  Request the device be transferred to the account doing the claim
 	 * @param {String} options.auth       Access Token
 	 * @param {Object} [options.headers]  Key/Value pairs like `{ 'X-FOO': 'foo', X-BAR: 'bar' }` to send as headers.
 	 * @param {Object} [options.context]  Request context
@@ -587,8 +588,8 @@ class Particle {
 	 * @param {Object} [options.context]               Request context
 	 * @returns {Promise} A promise
 	 */
-	lockDeviceProductFirmware({ deviceId, desiredFirmwareVersion, flash, product, auth, context }){
-		return this.updateDevice({ deviceId, desiredFirmwareVersion, flash, product, auth, context });
+	lockDeviceProductFirmware({ deviceId, desiredFirmwareVersion, flash, product, auth, context, headers }){
+		return this.updateDevice({ deviceId, desiredFirmwareVersion, flash, product, auth, context, headers });
 	}
 
 	/**
@@ -1207,6 +1208,7 @@ class Particle {
 	 * @param {String} options.iccid          ICCID of the SIM card
 	 * @param {Array<String>} options.iccids  (Product only) ICCID of multiple SIM cards to import
 	 * @param {String} options.country        The ISO country code for the SIM cards
+	 * @param {String} [options.promoCode]    (Product only) Promo code for the SIM cards
 	 * @param {String} [options.product]      SIM cards for this product ID or slug
 	 * @param {String} options.auth           Access Token
 	 * @param {Object} [options.headers]      Key/Value pairs like `{ 'X-FOO': 'foo', X-BAR: 'bar' }` to send as headers.
@@ -1322,7 +1324,6 @@ class Particle {
 	 * - 'verified' - list only verified libraries
 	 * - 'featured' - list only featured libraries
 	 * @param  {String} options.excludeScopes  list of scopes to exclude
-	 * @param  {String} options.category Category to filter
 	 * @param  {String} options.auth Access Token
 	 * @param {Object} [options.headers]              Key/Value pairs like `{ 'X-FOO': 'foo', X-BAR: 'bar' }` to send as headers.
 	 * @param {Object} [options.context]              Request context
@@ -2003,7 +2004,7 @@ class Particle {
 	 * @param  {Object} options          Options for this API call
 	 * @param  {String} options.product  Config for this product ID or slug
 	 * @param  {String} options.auth     Access Token
-	 * @param  {Object} opitons.config   Product configuration to update
+	 * @param  {Object} options.config   Product configuration to update
 	 * @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
@@ -2023,7 +2024,7 @@ class Particle {
 	 * @param  {Object} options          Options for this API call
 	 * @param  {String} options.product  Config for this product ID or slug
 	 * @param  {String} options.auth     Access Token
-	 * @param  {Object} opitons.config   Product configuration to update
+	 * @param  {Object} options.config   Product configuration to update
 	 * @param  {String} options.deviceId Device ID to access
 	 * @param {Object} [options.headers] Key/Value pairs like `{ 'X-FOO': 'foo', X-BAR: 'bar' }` to send as headers.
 	 * @param {Object} [options.context] Request context
@@ -2086,8 +2087,6 @@ class Particle {
 	 * @param  {String} options.deviceId  Device ID to query
 	 * @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.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
 	 */
 	getProductDeviceLocations({ auth, product, dateRange, rectBl, rectTr, deviceId, headers, context }){
@@ -2120,7 +2119,7 @@ class Particle {
 	 * @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<{body: {block: ResponseBlock}, statusCode: int}>} A promise that resolves to the created logic block data.
+	 * @returns {Promise<{body: {block: BlockResponse}, statusCode: number}>} A promise that resolves to the created logic block data.
 	 */
 	createLogicBlock({ auth, org, block, headers, context }) {
 		return this.post({
@@ -2142,7 +2141,7 @@ class Particle {
 	 * @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<{body: {block: ResponseBlock}, statusCode: int}>} A promise that resolves to the specified logic block data.
+	 * @returns {Promise<{body: {block: BlockResponse}, statusCode: number}>} A promise that resolves to the specified logic block data.
 	 */
 	getLogicBlock({ auth, org, blockId, headers, context }) {
 		return this.get({
@@ -2158,6 +2157,9 @@ class Particle {
 	 *
 	 * If you include an id on a matcher, it will update the matcher in place.
 	 *
+	 * @typedef {import('./types/blocks').Block} Block
+	 * @typedef {import('./types/blocks').BlockResponse} BlockResponse
+	 *
 	 * @param {Object} options          The options for updating the logic block.
 	 * @param {Object} options.auth     The authentication object with the API key.
 	 * @param {string} options.org      The unique identifier of the organization.
@@ -2166,7 +2168,7 @@ class Particle {
 	 * @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<{body: {block: ResponseBlock}, statusCode: int}>} A promise that resolves to the updated logic block data.
+	 * @returns {Promise<{body: {block: BlockResponse}, statusCode: number}>} A promise that resolves to the updated logic block data.
 	 */
 	updateLogicBlock({ auth, org, blockId, block, headers, context }) {
 		return this.put({
@@ -2188,7 +2190,7 @@ class Particle {
 	 * @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<{body: {block_id: int}, statusCode: int}>} A promise that resolves to an object containing the deleted block ID.
+	 * @returns {Promise<{body: {block_id: number}, statusCode: number}>} A promise that resolves to an object containing the deleted block ID.
 	 */
 	deleteLogicBlock({ auth, org, blockId, headers, context }) {
 		return this.delete({
@@ -2208,7 +2210,7 @@ class Particle {
 	 * @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<{body: {block: ResponseBlock[]}, statusCode: int}>} A promise that resolves to an array of logic block data.
+	 * @returns {Promise<{body: {block: BlockResponse[]}, statusCode: number}>} A promise that resolves to an array of logic block data.
 	 */
 	listLogicBlocks({ auth, org, headers, context }) {
 		return this.get({
@@ -2229,7 +2231,9 @@ class Particle {
 	 * @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<{body: {blocks: BlockRun[]}, statusCode: int}>} A promise that resolves to an array of block run data.
+	 * @typedef {import('./types/blocks').BlockRun} BlockRun
+	 *
+	 * @returns {Promise<{body: {blocks: BlockRun[]}, statusCode: number}>} A promise that resolves to an array of block run data.
 	 */
 	listBlockRuns({ auth, org, blockId, headers, context }) {
 		return this.get({
@@ -2251,7 +2255,7 @@ class Particle {
 	 * @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<{body: {block_runs: BlockRun[]}, statusCode: int}>} A promise that resolves to an array of block run data for the specified block run ID.
+	 * @returns {Promise<{body: {block_runs: BlockRun[]}, statusCode: number}>} A promise that resolves to an array of block run data for the specified block run ID.
 	 */
 	getBlockRun({ auth, org, blockId, runId, headers, context }) {
 		return this.get({
@@ -2273,7 +2277,9 @@ class Particle {
 	 * @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<{body: {block_run_log: BlockRunLog}, statusCode: int}>} A promise that resolves to the logs for the specified block run ID.
+	 * @typedef {import('./types/blocks').BlockRunLog} BlockRunLog
+	 *
+	 * @returns {Promise<{body: {block_run_log: BlockRunLog}, statusCode: number}>} A promise that resolves to the logs for the specified block run ID.
 	 */
 	getBlockRunLog({ auth, org, blockId, runId, headers, context }) {
 		return this.get({

src/index.js

@@ -0,0 +1,5 @@
+// Builds into index.d.ts and serves as the type definition for the package
+import Particle from './Particle';
+export default Particle;
+
+export * from './types/blocks';

src/types/blocks.js

@@ -0,0 +1,92 @@
+/**
+ * Types for the Particle Blocks API
+ * Responses have the same structure as the request, with additional fields
+ */
+
+/**
+ * @typedef {Object} Block
+ * @property {boolean} enabled Whether the block is enabled
+ * @property {string} name The name of the block
+ * @property {string} description A description of the block
+ * @property {Logic} logic The logic to run for the block
+ * @property {Matcher[]} matchers The matchers for the block
+ *
+ * @typedef {Object} Logic
+ * @property {"JavaScript"} type Must be "JavaScript"
+ * @property {string} code The JavaScript code to run
+ *
+ * @typedef {Object} PubSubMatcher
+ * @property {"PubSub"} type Must be "PubSub"
+ * @property {boolean} enabled Whether the matcher is enabled
+ * @property {number} product_id The ID of the product to match
+ * @property {string} event_name The name of the event to match
+ *
+ * @typedef {Object} ChronMatcher
+ * @property {"Chron"} type Must be "Chron"
+ * @property {boolean} enabled Whether the matcher is enabled
+ * @property {string} cron The cron schedule for the matcher
+ * @property {string} [start_at] The start time for the matcher (ISO 8601 format)
+ * @property {string} [end_at] The end time for the matcher (ISO 8601 format)
+ *
+ * @typedef {(PubSubMatcher | ChronMatcher)} Matcher
+ *
+ * @typedef {Object} BlockRun
+ * @property {number} id The ID of the block run
+ * @property {number} block_id The ID of the block
+ * @property {"PubSub"|"Chron"} matcher_type The type of the matcher
+ * @property {number} matcher_id The ID of the matcher
+ * @property {"Success"|"Failure"} status The status of the block run
+ * @property {string} started_at The start time of the block run (ISO 8601 format)
+ * @property {string} finished_at The end time of the block run (ISO 8601 format)
+ * @property {string} log_filename The name of the log file
+ *
+ * @typedef {Object} Log
+ * @property {"Info"|"Warn"|"Error"} level The level of the log
+ * @property {string} timestamp The time of the log (ISO 8601 format)
+ * @property {any[]} args The arguments for the log
+ *
+ * @typedef {Object} BlockRunLog
+ * @property {Log[]} logs An array of logs for the block run
+ * @property {string} [err] The error message, if the block execution failed
+ */
+
+/**
+ * @typedef {Object} BlockResponse
+ * @property {boolean} enabled Whether the block is enabled
+ * @property {string} name The name of the block
+ * @property {string} description A description of the block
+ * @property {Logic} logic The logic to run for the block
+ * @property {number} id The id of the block
+ * @property {string} owner_id The id of the owner of the block
+ * @property {string} version The version of the block
+ * @property {string} created_at The creation date of the block (ISO 8601 format)
+ * @property {string} updated_at The update date of the block (ISO 8601 format)
+ * @property {string} created_by The creator of the block
+ * @property {string} updated_by The updater of the block
+ * @property {MatcherResponse[]} matchers The matchers associated with the block
+ *
+ * @typedef {Object} PubSubMatcherResponse
+ * @property {"PubSub"} type Must be "PubSub"
+ * @property {boolean} enabled Whether the matcher is enabled
+ * @property {number} product_id The ID of the product to match
+ * @property {string} event_name The name of the event to match
+ * @property {string} id The id of the matcher
+ * @property {string} block_id The id of the block
+ * @property {number} version The version of the matcher
+ * @property {string} last_scheduled_at The last time the matcher was scheduled (ISO 8601 format)
+ * @property {string} next_unscheduled_at The next time the matcher will be scheduled (ISO 8601 format)
+ *
+ * @typedef {Object} ChronMatcherResponse
+ * @property {"Chron"} type Must be "Chron"
+ * @property {boolean} enabled Whether the matcher is enabled
+ * @property {string} cron The cron schedule for the matcher
+ * @property {string} start_at The start time for the matcher (ISO 8601 format)
+ * @property {string} end_at The end time for the matcher (ISO 8601 format)
+ * @property {string} id The id of the matcher
+ * @property {string} block_id The id of the block
+ *
+ * @typedef {(PubSubMatcherResponse | ChronMatcherResponse)} MatcherResponse
+ */
+
+// export all JSDoc types
+module.exports = {};

tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "declarationMap": true,
+    "outDir": "./types",
+    "allowJs": true,
+    "checkJs": false
+  },
+  "include": ["src/**/*.js"],
+  "exclude": ["node_modules", "test"]
+}