feat: more consistent code examples

.github/scripts/filter-deprecated-params.js

@@ -22,6 +22,20 @@ try {
     });
   });
 
+  // Wrap string parameter examples in JS-style double quotes so the
+  // openapi-generator-cli renders them as valid JS string literals.
+  if (openapi.components?.parameters) {
+    Object.values(openapi.components.parameters).forEach((param) => {
+      if (
+        param.schema?.type === "string" &&
+        param.example !== undefined &&
+        !String(param.example).startsWith('"')
+      ) {
+        param.example = `"${param.example}"`;
+      }
+    });
+  }
+
   // Save the updated content to a new file
   fs.writeFileSync(outputFile, yaml.stringify(openapi), "utf8");
   console.log(`Filtered file written to ${outputFile}`);

README.md

@@ -3,7 +3,7 @@
 The notehub-js library is a JavaScript implementation for communicating with the [Blues Notehub API](https://dev.blues.io/reference/notehub-api/api-introduction/)
 generated by the [OpenAPI Generator](https://openapi-generator.tech) tool.
 
-This library is auto-generated via the `openapi.yaml` file from the Blues Wireless Notehub project and published
+This library is auto-generated via the `openapi.yaml` file from the Blues Notehub project and published
 to [npm](https://www.npmjs.com/package/@blues-inc/notehub-js) for ease of use in JavaScript-based projects that need to interact with [Notehub.io][notehub].
 
 ## Table of Contents
@@ -12,7 +12,6 @@ to [npm](https://www.npmjs.com/package/@blues-inc/notehub-js) for ease of use in
   - [Table of Contents](#table-of-contents)
   - [Installation](#installation)
   - [Sample Code](#sample-code)
-    - [Real World Use Cases of Notehub JS Library](#real-world-use-cases-of-notehub-js-library)
   - [Further Library Documentation \& Code Examples](#further-library-documentation--code-examples)
   - [Project Structure](#project-structure)
     - [High Level Project Overview](#high-level-project-overview)
@@ -72,6 +71,8 @@ Here is an example of how to fetch all devices associated with a particular [Not
 
 The `personalAccessToken` variable declared below is a Personal Access Token (PAT) required for all Notehub API requests.
 
+<a id="personalAccessToken"></a>
+
 **Creating a Personal Access Token**
 
 To create a PAT:
@@ -86,14 +87,11 @@ Personal Access Tokens have the same permissions as your Notehub user account an
 
 Once you have your PAT, supply it to the library by setting it equal to: `personalAccessToken.accessToken = "YOUR_ACCESS_TOKEN";` in the code.
 
-> **NOTE**: Be aware that all Notehub API calls made using the Notehub JS library utilize your account's [Consumption Credits](https://dev.blues.io/reference/glossary#consumption-credit) (CCs). For > more information, please consult our [pricing page](https://blues.io/pricing/).
-
 ```javascript
 import * as NotehubJs from "@blues-inc/notehub-js";
 
 let defaultClient = NotehubJs.ApiClient.instance;
 
-// Configure Bearer access token for authorization: personalAccessToken
 let personalAccessToken = defaultClient.authentications["personalAccessToken"];
 personalAccessToken.accessToken = "YOUR ACCESS TOKEN";
 
@@ -117,20 +115,6 @@ apiInstance.getProjectDevices(projectUID, opts).then(
 );
 ```
 
-### Real World Use Cases of Notehub JS Library
-
-As this library gains adoptions, we'll continue to provide new links to repos where this library being used in real world projects.
-
-[**Indoor Floor Level Tracker Project**](https://github.com/blues/app-accelerators/tree/main/01-indoor-floor-level-tracker/web-app)
-
-If you'd like to see examples of this library being used in real-world applications, check out [this indoor floor-level tracker project](https://github.com/blues/app-accelerators/tree/main/01-indoor-floor-level-tracker/web-app) in the [Blues App Accelerator repo](https://github.com/blues/app-accelerators/blob/main/) on GitHub.
-
-The files that deserve special attention are:
-
-- [`ServiceLocatorServer.ts`](https://github.com/blues/app-accelerators/blob/main/01-indoor-floor-level-tracker/web-app/src/services/ServiceLocatorServer.ts) - this file makes the variety of services composing the backend logic of the application discoverable to each other. For DRY-er code, the Notehub JS library's instances were created and passed to the various services that would require them to fetch and update data via the Notehub API. An instance of the Notehub JS client is created via `const notehubJsClient = NotehubJs.ApiClient.instance`, and passed to the `getDataProvider()` and `getAttributeStore()` services that will need to interact with the Notehub API to perform their duties.
-- [`NotehubDataProvider.ts`](https://github.com/blues/app-accelerators/blob/main/01-indoor-floor-level-tracker/web-app/src/services/notehub/NotehubDataProvider.ts) - this file is responsible for fetching data from the Notehub API for the application to display. It calls the project API's `getProjectFleetDevices()` and `getProjectEvents()` methods, and the fleet API's `getFleetEnvironmentVariables()` method as well.
-- [`NotehubAttributeStore.ts`](https://github.com/blues/app-accelerators/blob/main/01-indoor-floor-level-tracker/web-app/src/services/notehub/NotehubAttributeStore.ts) - this file sends updates to the Notehub API from the application like updated device name or updated environment variables. It calls two of the environment variable API's methods: `putDeviceEnvironmentVariables()` and `putFleetEnvironmentVariables()`.
-
 ## Further Library Documentation & Code Examples
 
 If you want more information, code examples of how to use each of the Notehub API endpoints are located in the [`src/docs/`](src/docs/) folder and available on the [Blues Developer Experience site][blues.dev].

libTemplate/api_doc.mustache

@@ -35,7 +35,6 @@ let {{{name}}} = defaultClient.authentications['{{{name}}}'];
 {{{name}}}.password = 'YOUR PASSWORD';
 {{/isBasicBasic}}
 {{#isBasicBearer}}
-// Configure Bearer{{#bearerFormat}} ({{{.}}}){{/bearerFormat}} access token for authorization: {{{name}}}
 let {{{name}}} = defaultClient.authentications['{{{name}}}'];
 {{{name}}}.accessToken = "YOUR ACCESS TOKEN"
 {{/isBasicBearer}}

openapi.filtered.yaml

@@ -3039,7 +3039,7 @@ paths:
 components:
   parameters:
     billingAccountUIDParam:
-      example: 00000000-0000-0000-000000000001
+      example: '"00000000-0000-0000-000000000001"'
       in: path
       name: billingAccountUID
       required: true
@@ -3151,7 +3151,7 @@ components:
       description:
         Which date to filter on, either 'captured' or 'uploaded'.  This
         will apply to the startDate and endDate parameters
-      example: uploaded
+      example: '"uploaded"'
       in: query
       name: dateType
       required: false
@@ -3170,7 +3170,7 @@ components:
         items:
           type: string
     deviceUIDParam:
-      example: dev:000000000000000
+      example: '"dev:000000000000000"'
       in: path
       name: deviceUID
       required: true
@@ -3226,21 +3226,21 @@ components:
           type: string
       style: form
     eventUIDParam:
-      example: 4506f411-dea6-44a0-9743-1130f57d7747
+      example: '"4506f411-dea6-44a0-9743-1130f57d7747"'
       in: path
       name: eventUID
       required: true
       schema:
         type: string
     filenameQueryParam:
-      example: notecard-7.2.2.16518$20240410043100.bin
+      example: '"notecard-7.2.2.16518$20240410043100.bin"'
       in: query
       name: filename
       required: false
       schema:
         type: string
     filesQueryParam:
-      example: _health.qo, data.qo
+      example: '"_health.qo, data.qo"'
       in: query
       name: files
       required: false
@@ -3356,7 +3356,7 @@ components:
       style: form
     jobUIDParam:
       description: Unique identifier for a batch job
-      example: my-reconciliation-job
+      example: '"my-reconciliation-job"'
       in: path
       name: jobUID
       required: true
@@ -3388,7 +3388,7 @@ components:
       schema:
         type: string
     monitorUIDParam:
-      example: monitor:8bAdf00d-000f-51c-af-01d5eaf00dbad
+      example: '"monitor:8bAdf00d-000f-51c-af-01d5eaf00dbad"'
       in: path
       name: monitorUID
       required: true
@@ -3455,7 +3455,7 @@ components:
       schema:
         type: string
     productUIDParam:
-      example: com.blues.bridge:sensors
+      example: '"com.blues.bridge:sensors"'
       in: path
       name: productUID
       required: true
@@ -3472,15 +3472,15 @@ components:
           type: string
       style: form
     projectOrProductUIDParam:
-      example: app:2606f411-dea6-44a0-9743-1130f57d77d8
+      example: '"app:2606f411-dea6-44a0-9743-1130f57d77d8"'
       in: path
       name: projectOrProductUID
       required: true
       schema:
         type: string
     reportUIDParam:
       description: Unique identifier for a job run report
-      example: my-reconciliation-job-1707654321000
+      example: '"my-reconciliation-job-1707654321000"'
       in: path
       name: reportUID
       required: true
@@ -3530,7 +3530,7 @@ components:
           - asc
           - desc
     routeUIDParam:
-      example: route:cbd20093cba58392c9f9bbdd0cdeb1a0
+      example: '"route:cbd20093cba58392c9f9bbdd0cdeb1a0"'
       in: path
       name: routeUID
       required: true

package.json

@@ -4,7 +4,7 @@
   "main": "./src/dist/index.js",
   "scripts": {
     "downloadJsTemplate": "openapi-generator-cli author template -g javascript --library javascript",
-    "generateDocs": "openapi-generator-cli generate -g javascript --library javascript -t libTemplate -o src -i openapi.filtered.yaml -c config.json",
+    "generateDocs": "openapi-generator-cli generate -g javascript --library javascript -t libTemplate -o src -i openapi.filtered.yaml -c config.json && npx prettier --write \"src/docs/**/*.md\" \"src/src/**/*.js\" \"src/README.md\" \"src/package.json\"",
     "installAndShrinkwrap": "cd src && npm install && npm shrinkwrap",
     "filterOpenapi": "node ./.github/scripts/filter-deprecated-params.js",
     "test": "echo \"Error: no test specified\" && exit 1",

src/.openapi-generator/FILES

@@ -319,17 +319,3 @@ src/model/UserDfuStateMachine.js
 src/model/UserDfuStateMachineStatus.js
 src/model/UserFirmwareInfo.js
 src/model/WebhookSettings.js
-test/api/JobsApi.spec.js
-test/model/AWSRoleConfig.spec.js
-test/model/CancelJobRun200Response.spec.js
-test/model/CreateJob201Response.spec.js
-test/model/DeleteJob200Response.spec.js
-test/model/GetBillingAccount200Response.spec.js
-test/model/GetBillingAccount200ResponsePlan.spec.js
-test/model/GetBillingAccountBalanceHistory200Response.spec.js
-test/model/GetBillingAccountBalanceHistory200ResponseDataInner.spec.js
-test/model/GetJobRuns200Response.spec.js
-test/model/GetJobs200Response.spec.js
-test/model/Job.spec.js
-test/model/JobRun.spec.js
-test/model/RunJob200Response.spec.js

src/README.md

@@ -100,27 +100,30 @@ module: {
 Please follow the [installation](#installation) instruction and execute the following JS code:
 
 ```javascript
-var NotehubJs = require('@blues-inc/notehub-js');
+var NotehubJs = require("@blues-inc/notehub-js");
 
 var defaultClient = NotehubJs.ApiClient.instance;
 // Configure Bearer access token for authorization: personalAccessToken
-var personalAccessToken = defaultClient.authentications['personalAccessToken'];
-personalAccessToken.accessToken = "YOUR ACCESS TOKEN"
+var personalAccessToken = defaultClient.authentications["personalAccessToken"];
+personalAccessToken.accessToken = "YOUR ACCESS TOKEN";
 
-var api = new NotehubJs.AlertApi()
-var projectOrProductUID = app:2606f411-dea6-44a0-9743-1130f57d77d8; // {String}
+var api = new NotehubJs.AlertApi();
+var projectOrProductUID = "app:2606f411-dea6-44a0-9743-1130f57d77d8"; // {String}
 var opts = {
-  'pageSize': 50, // {Number}
-  'pageNum': 1, // {Number}
-  'monitorUID': "monitorUID_example" // {String}
+  pageSize: 50, // {Number}
+  pageNum: 1, // {Number}
+  monitorUID: "monitorUID_example", // {String}
 };
-api.getAlerts(projectOrProductUID, opts).then(function(data) {
-  console.log('API called successfully. Returned data: ' + JSON.stringify(data));
-}, function(error) {
-  console.error(error);
-});
-
-
+api.getAlerts(projectOrProductUID, opts).then(
+  function (data) {
+    console.log(
+      "API called successfully. Returned data: " + JSON.stringify(data)
+    );
+  },
+  function (error) {
+    console.error(error);
+  }
+);
 ```
 
 ## Documentation for API Endpoints

src/docs/AlertApi.md

@@ -15,25 +15,28 @@ Get list of defined Alerts
 ### Example
 
 ```javascript
-import * as NotehubJs from '@blues-inc/notehub-js';
+import * as NotehubJs from "@blues-inc/notehub-js";
 let defaultClient = NotehubJs.ApiClient.instance;
-// Configure Bearer access token for authorization: personalAccessToken
-let personalAccessToken = defaultClient.authentications['personalAccessToken'];
-personalAccessToken.accessToken = "YOUR ACCESS TOKEN"
+let personalAccessToken = defaultClient.authentications["personalAccessToken"];
+personalAccessToken.accessToken = "YOUR ACCESS TOKEN";
 
 let apiInstance = new NotehubJs.AlertApi();
-let projectOrProductUID = app:2606f411-dea6-44a0-9743-1130f57d77d8; // String |
+let projectOrProductUID = "app:2606f411-dea6-44a0-9743-1130f57d77d8"; // String |
 let opts = {
-  'pageSize': 50, // Number |
-  'pageNum': 1, // Number |
-  'monitorUID': "monitorUID_example" // String |
+  pageSize: 50, // Number |
+  pageNum: 1, // Number |
+  monitorUID: "monitorUID_example", // String |
 };
-apiInstance.getAlerts(projectOrProductUID, opts).then((data) => {
-  console.log('API called successfully. Returned data: ' + JSON.stringify(data));
-}, (error) => {
-  console.error(error);
-});
-
+apiInstance.getAlerts(projectOrProductUID, opts).then(
+  (data) => {
+    console.log(
+      "API called successfully. Returned data: " + JSON.stringify(data)
+    );
+  },
+  (error) => {
+    console.error(error);
+  }
+);
 ```
 
 ### Parameters

src/docs/BillingAccountApi.md

@@ -19,12 +19,11 @@ Get Billing Account Information
 ```javascript
 import * as NotehubJs from "@blues-inc/notehub-js";
 let defaultClient = NotehubJs.ApiClient.instance;
-// Configure Bearer access token for authorization: personalAccessToken
 let personalAccessToken = defaultClient.authentications["personalAccessToken"];
 personalAccessToken.accessToken = "YOUR ACCESS TOKEN";
 
 let apiInstance = new NotehubJs.BillingAccountApi();
-let billingAccountUID = 00000000 - 0000 - 0000 - 000000000001; // String |
+let billingAccountUID = "00000000-0000-0000-000000000001"; // String |
 apiInstance.getBillingAccount(billingAccountUID).then(
   (data) => {
     console.log(
@@ -67,12 +66,11 @@ Get Billing Account Balance history, only enterprise supported
 ```javascript
 import * as NotehubJs from "@blues-inc/notehub-js";
 let defaultClient = NotehubJs.ApiClient.instance;
-// Configure Bearer access token for authorization: personalAccessToken
 let personalAccessToken = defaultClient.authentications["personalAccessToken"];
 personalAccessToken.accessToken = "YOUR ACCESS TOKEN";
 
 let apiInstance = new NotehubJs.BillingAccountApi();
-let billingAccountUID = 00000000 - 0000 - 0000 - 000000000001; // String |
+let billingAccountUID = "00000000-0000-0000-000000000001"; // String |
 let opts = {
   startDate: 1628631763, // Number | Start date for filtering results, specified as a Unix timestamp
   endDate: 1657894210, // Number | End date for filtering results, specified as a Unix timestamp
@@ -121,7 +119,6 @@ Get Billing Accounts accessible by the api_key
 ```javascript
 import * as NotehubJs from "@blues-inc/notehub-js";
 let defaultClient = NotehubJs.ApiClient.instance;
-// Configure Bearer access token for authorization: personalAccessToken
 let personalAccessToken = defaultClient.authentications["personalAccessToken"];
 personalAccessToken.accessToken = "YOUR ACCESS TOKEN";