docs(NODE-5094): fix docs for azure kms credential refresh (#596)

Author: baileympearson

README.md

@@ -60,6 +60,9 @@ npm test
 <dt><a href="#MongoCryptCreateEncryptedCollectionError">MongoCryptCreateEncryptedCollectionError</a></dt>
 <dd><p>An error indicating that <code>ClientEncryption.createEncryptedCollection()</code> failed to create a collection</p>
 </dd>
+<dt><a href="#MongoCryptAzureKMSRequestError">MongoCryptAzureKMSRequestError</a></dt>
+<dd><p>An error indicating that mongodb-client-encryption failed to auto-refresh Azure KMS credentials.</p>
+</dd>
 </dl>
 
 ## Typedefs
@@ -692,6 +695,20 @@ An error indicating that `ClientEncryption.createEncryptedCollection()` failed t
 **Experimental**: Public Technical Preview  
 An error indicating that `ClientEncryption.createEncryptedCollection()` failed to create a collection
 
+<a name="MongoCryptAzureKMSRequestError"></a>
+
+## MongoCryptAzureKMSRequestError
+An error indicating that mongodb-client-encryption failed to auto-refresh Azure KMS credentials.
+
+<a name="new_MongoCryptAzureKMSRequestError_new"></a>
+
+### new MongoCryptAzureKMSRequestError(message, body)
+
+| Param | Type |
+| --- | --- |
+| message | <code>string</code> | 
+| body | <code>object</code> \| <code>undefined</code> | 
+
 <a name="BSONValue"></a>
 
 ## BSONValue

lib/providers/azure.js

@@ -9,6 +9,7 @@ const utils = require('./utils');
 const MINIMUM_TOKEN_REFRESH_IN_MILLISECONDS = 6000;
 
 /**
+ * @class
  * @ignore
  */
 class AzureCredentialCache {
@@ -36,35 +37,45 @@ class AzureCredentialCache {
   }
 
   /**
-   * @ignore
    * exposed for testing
+   * @ignore
    */
   resetCache() {
     this.cachedToken = null;
   }
 
   /**
-   * @ignore
    * exposed for testing
+   * @ignore
    */
   _getToken() {
     return fetchAzureKMSToken();
   }
 }
 /**
- * @type{AzureCredentialCache}
+ * @type{ AzureCredentialCache }
+ * @ignore
  */
 let tokenCache = new AzureCredentialCache();
 
+/**
+ * @typedef {object} KmsRequestResponsePayload
+ * @property {string | undefined} access_token
+ * @property {string | undefined} expires_in
+ *
+ * @ignore
+ */
+
 /**
  * @param { {body: string, status: number }} response
  * @returns { Promise<{ accessToken: string, expiresOnTimestamp: number } >}
+ * @ignore
  */
 async function parseResponse(response) {
   const { status, body: rawBody } = response;
 
   /**
-   * @type { { access_token?: string, expires_in?: string} }
+   * @type { KmsRequestResponsePayload }
    */
   const body = (() => {
     try {
@@ -107,6 +118,8 @@ async function parseResponse(response) {
  * @param {object} options
  * @param {object | undefined} [options.headers]
  * @param {URL | undefined} [options.url]
+ *
+ * @ignore
  */
 function prepareRequest(options) {
   const url =
@@ -122,13 +135,26 @@ function prepareRequest(options) {
 }
 
 /**
+ * @typedef {object} AzureKMSRequestOptions
+ * @property {object | undefined} headers
+ * @property {URL | undefined} url
  * @ignore
+ */
+
+/**
+ * @typedef {object} AzureKMSRequestResponse
+ * @property {string} accessToken
+ * @property {number} expiresOnTimestamp
+ * @ignore
+ */
+
+/**
  * exported only for testing purposes in the driver
  *
- * @param {object} options
- * @param {object | undefined} [options.headers]
- * @param {URL | undefined} [options.url]
- * @returns {Promise<{ accessToken: string, expiresOnTimestamp: number }>}
+ * @param {AzureKMSRequestOptions} options
+ * @returns {Promise<AzureKMSRequestResponse>}
+ *
+ * @ignore
  */
 async function fetchAzureKMSToken(options = {}) {
   const { headers, url } = prepareRequest(options);
@@ -142,7 +168,6 @@ async function fetchAzureKMSToken(options = {}) {
 }
 
 /**
- * @param {import('../../index').KMSProviders} kmsProviders
  * @ignore
  */
 async function loadAzureCredentials(kmsProviders) {

lib/providers/index.js

@@ -5,14 +5,15 @@ const { loadAzureCredentials, fetchAzureKMSToken } = require('./azure');
 const { loadGCPCredentials } = require('./gcp');
 
 /**
- * @ignore
  * Auto credential fetching should only occur when the provider is defined on the kmsProviders map
  * and the settings are an empty object.
  *
  * This is distinct from a nullish provider key.
  *
  * @param {'aws' | 'gcp' | 'azure'} provider
- * @param {import('../../index').KMSProviders} kmsProviders
+ * @param {object} kmsProviders
+ *
+ * @ignore
  */
 function isEmptyCredentials(provider, kmsProviders) {
   return (
@@ -28,8 +29,8 @@ function isEmptyCredentials(provider, kmsProviders) {
  * Credentials will only attempt to get loaded if they do not exist
  * and no existing credentials will get overwritten.
  *
- * @param {import('../../index').KMSProviders} kmsProviders - The user provided KMS providers.
- * @returns {Promise<import('../../index').KMSProviders>} The new kms providers.
+ * @param {object} kmsProviders - The user provided KMS providers.
+ * @returns {object} The new kms providers.
  *
  * @ignore
  */

lib/providers/utils.js

@@ -8,6 +8,7 @@ const http = require('http');
  * @param {http.RequestOptions} options
  *
  * @returns { Promise<{ body: string, status: number }> }
+ * @ignore
  */
 function get(url, options = {}) {
   return new Promise((resolve, reject) => {