ibm-cloud-sdk-core 4.0.0 → 4.0.2

package/es/auth/token-managers/jwt-token-manager.js

@@ -1,6 +1,6 @@
 /* eslint-disable class-methods-use-this */
 /**
- * (C) Copyright IBM Corp. 2019, 2021.
+ * (C) Copyright IBM Corp. 2019, 2022.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -25,15 +25,14 @@ import { TokenManager } from './token-manager';
  */
 export class JwtTokenManager extends TokenManager {
     /**
-     * Create a new [[JwtTokenManager]] instance.
-     * @constructor
-     * @param {object} options Configuration options.
-     * @param {string} options.url for HTTP token requests.
-     * @param {boolean} [options.disableSslVerification] A flag that indicates
-     *   whether verification of the token server's SSL certificate should be
-     *   disabled or not.
-     * @param {object<string, string>} [options.headers] Headers to be sent with every
-     *   outbound HTTP requests to token services.
+     * Create a new JwtTokenManager instance.
+     *
+     * @param options - Configuration options.
+     * This should be an object containing these fields:
+     * - url: (optional) the endpoint URL for the token service
+     * - disableSslVerification: (optional) a flag that indicates whether verification of the token server's SSL certificate
+     * should be disabled or not
+     * - headers: (optional) a set of HTTP headers to be sent with each request to the token service
      */
     constructor(options) {
         // all parameters are optional
@@ -45,7 +44,7 @@ export class JwtTokenManager extends TokenManager {
     /**
      * Request a JWT using an API key.
      *
-     * @returns {Promise}
+     * @returns Promise
      */
     requestToken() {
         const errMsg = '`requestToken` MUST be overridden by a subclass of JwtTokenManagerV1.';
@@ -56,9 +55,7 @@ export class JwtTokenManager extends TokenManager {
     /**
      * Save the JWT service response and the calculated expiration time to the object's state.
      *
-     * @param tokenResponse - Response object from JWT service request
-     * @protected
-     * @returns {void}
+     * @param tokenResponse - the response object from JWT service request
      */
     saveTokenInfo(tokenResponse) {
         const responseBody = tokenResponse.result || {};
@@ -68,14 +65,14 @@ export class JwtTokenManager extends TokenManager {
             logger.error(err);
             throw new Error(err);
         }
-        // the time of expiration is found by decoding the JWT access token
-        // exp is the time of expire and iat is the time of token retrieval
         const decodedResponse = decode(this.accessToken);
         if (!decodedResponse) {
             const err = 'Access token recieved is not a valid JWT';
             logger.error(err);
             throw new Error(err);
         }
+        // the time of expiration is found by decoding the JWT access token
+        // 'exp' is the time of expire and 'iat' is the time of token retrieval
         const { exp, iat } = decodedResponse;
         // There are no required claims in JWT
         if (!exp || !iat) {

package/es/auth/token-managers/token-manager.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="node" />
 /**
- * (C) Copyright IBM Corp. 2020, 2021.
+ * (C) Copyright IBM Corp. 2020, 2022.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -33,8 +33,8 @@ export type TokenManagerOptions = {
 /**
  * A class for shared functionality for storing, and requesting tokens.
  * Intended to be used as a parent to be extended for token request management.
- * Child classes should implement `requestToken()` to retrieve the token
- * from intended sources and `saveTokenInfo(tokenResponse)` to parse and save
+ * Child classes should implement "requestToken()" to retrieve the token
+ * from intended sources and "saveTokenInfo(tokenResponse)" to parse and save
  * token information from the response.
  */
 export declare class TokenManager {
@@ -48,40 +48,36 @@ export declare class TokenManager {
     private requestTime;
     private pendingRequests;
     /**
-     * Create a new [[TokenManager]] instance.
-     * @constructor
-     * @param {object} options Configuration options.
-     * @param {string} options.url for HTTP token requests.
-     * @param {boolean} [options.disableSslVerification] A flag that indicates
-     *   whether verification of the token server's SSL certificate should be
-     *   disabled or not.
-     * @param {object<string, string>} [options.headers] Headers to be sent with every
-     *   outbound HTTP requests to token services.
+     * Create a new TokenManager instance.
+     *
+     * @param options - Configuration options.
+     * This should be an object containing these fields:
+     * - url: (optional) the endpoint URL for the token service
+     * - disableSslVerification: (optional) a flag that indicates whether verification of the token server's SSL certificate
+     * should be disabled or not
+     * - headers: (optional) a set of HTTP headers to be sent with each request to the token service
      */
     constructor(options: TokenManagerOptions);
     /**
-     * Retrieve a new token using `requestToken()` in the case there is not a
-     *   currently stored token from a previous call, or the previous token
-     *   has expired.
+     * Retrieves a new token using "requestToken()" if there is not a
+     * currently stored token from a previous call, or the previous token
+     * has expired.
      */
     getToken(): Promise<any>;
     /**
-     * Setter for the disableSslVerification property.
+     * Sets the "disableSslVerification" property.
      *
-     * @param {boolean} value - the new value for the disableSslVerification
-     *   property
-     * @returns {void}
+     * @param value - the new value for the disableSslVerification property
      */
     setDisableSslVerification(value: boolean): void;
     /**
-     * Set a completely new set of headers.
+     * Sets the headers to be included with each outbound request to the token server.
      *
-     * @param {OutgoingHttpHeaders} headers - the new set of headers as an object
-     * @returns {void}
+     * @param headers - the set of headers to send with each request to the token server
      */
     setHeaders(headers: OutgoingHttpHeaders): void;
     /**
-     * Paces requests to request_token.
+     * Paces requests to requestToken().
      *
      * This method pseudo-serializes requests for an access_token
      * when the current token is undefined or expired.
@@ -95,7 +91,7 @@ export declare class TokenManager {
     /**
      * Request a token using an API endpoint.
      *
-     * @returns {Promise}
+     * @returns Promise
      */
     protected requestToken(): Promise<any>;
     /**
@@ -104,24 +100,16 @@ export declare class TokenManager {
      * Calculate expiration and refresh time from the received info
      * and store them in fields `expireTime` and `refreshTime`.
      *
-     * @param tokenResponse - Response object from a token service request
-     * @protected
-     * @returns {void}
+     * @param tokenResponse - the response object from a token service request
      */
     protected saveTokenInfo(tokenResponse: any): void;
     /**
-     * Check if currently stored token is expired
-     *
-     * @private
-     * @returns {boolean}
+     * Checks if currently-stored token is expired
      */
     private isTokenExpired;
     /**
-     * Check if currently stored token should be refreshed
+     * Checks if currently-stored token should be refreshed
      * i.e. past the window to request a new token
-     *
-     * @private
-     * @returns {boolean}
      */
     private tokenNeedsRefresh;
 }

package/es/auth/token-managers/token-manager.js

@@ -6,21 +6,20 @@ import { getCurrentTime } from '../utils';
 /**
  * A class for shared functionality for storing, and requesting tokens.
  * Intended to be used as a parent to be extended for token request management.
- * Child classes should implement `requestToken()` to retrieve the token
- * from intended sources and `saveTokenInfo(tokenResponse)` to parse and save
+ * Child classes should implement "requestToken()" to retrieve the token
+ * from intended sources and "saveTokenInfo(tokenResponse)" to parse and save
  * token information from the response.
  */
 export class TokenManager {
     /**
-     * Create a new [[TokenManager]] instance.
-     * @constructor
-     * @param {object} options Configuration options.
-     * @param {string} options.url for HTTP token requests.
-     * @param {boolean} [options.disableSslVerification] A flag that indicates
-     *   whether verification of the token server's SSL certificate should be
-     *   disabled or not.
-     * @param {object<string, string>} [options.headers] Headers to be sent with every
-     *   outbound HTTP requests to token services.
+     * Create a new TokenManager instance.
+     *
+     * @param options - Configuration options.
+     * This should be an object containing these fields:
+     * - url: (optional) the endpoint URL for the token service
+     * - disableSslVerification: (optional) a flag that indicates whether verification of the token server's SSL certificate
+     * should be disabled or not
+     * - headers: (optional) a set of HTTP headers to be sent with each request to the token service
      */
     constructor(options) {
         // all parameters are optional
@@ -37,9 +36,9 @@ export class TokenManager {
         this.pendingRequests = [];
     }
     /**
-     * Retrieve a new token using `requestToken()` in the case there is not a
-     *   currently stored token from a previous call, or the previous token
-     *   has expired.
+     * Retrieves a new token using "requestToken()" if there is not a
+     * currently stored token from a previous call, or the previous token
+     * has expired.
      */
     getToken() {
         if (!this.accessToken || this.isTokenExpired()) {
@@ -56,11 +55,9 @@ export class TokenManager {
         return Promise.resolve(this.accessToken);
     }
     /**
-     * Setter for the disableSslVerification property.
+     * Sets the "disableSslVerification" property.
      *
-     * @param {boolean} value - the new value for the disableSslVerification
-     *   property
-     * @returns {void}
+     * @param value - the new value for the disableSslVerification property
      */
     setDisableSslVerification(value) {
         // if they try to pass in a non-boolean value,
@@ -68,10 +65,9 @@ export class TokenManager {
         this.disableSslVerification = Boolean(value);
     }
     /**
-     * Set a completely new set of headers.
+     * Sets the headers to be included with each outbound request to the token server.
      *
-     * @param {OutgoingHttpHeaders} headers - the new set of headers as an object
-     * @returns {void}
+     * @param headers - the set of headers to send with each request to the token server
      */
     setHeaders(headers) {
         if (typeof headers !== 'object') {
@@ -81,7 +77,7 @@ export class TokenManager {
         this.headers = headers;
     }
     /**
-     * Paces requests to request_token.
+     * Paces requests to requestToken().
      *
      * This method pseudo-serializes requests for an access_token
      * when the current token is undefined or expired.
@@ -119,7 +115,7 @@ export class TokenManager {
     /**
      * Request a token using an API endpoint.
      *
-     * @returns {Promise}
+     * @returns Promise
      */
     requestToken() {
         const errMsg = '`requestToken` MUST be overridden by a subclass of TokenManagerV1.';
@@ -133,19 +129,14 @@ export class TokenManager {
      * Calculate expiration and refresh time from the received info
      * and store them in fields `expireTime` and `refreshTime`.
      *
-     * @param tokenResponse - Response object from a token service request
-     * @protected
-     * @returns {void}
+     * @param tokenResponse - the response object from a token service request
      */
     saveTokenInfo(tokenResponse) {
         const errMsg = '`saveTokenInfo` MUST be overridden by a subclass of TokenManager.';
         logger.error(errMsg);
     }
     /**
-     * Check if currently stored token is expired
-     *
-     * @private
-     * @returns {boolean}
+     * Checks if currently-stored token is expired
      */
     isTokenExpired() {
         const { expireTime } = this;
@@ -156,11 +147,8 @@ export class TokenManager {
         return expireTime <= currentTime;
     }
     /**
-     * Check if currently stored token should be refreshed
+     * Checks if currently-stored token should be refreshed
      * i.e. past the window to request a new token
-     *
-     * @private
-     * @returns {boolean}
      */
     tokenNeedsRefresh() {
         const { refreshTime } = this;

package/es/auth/token-managers/vpc-instance-token-manager.d.ts

@@ -1,5 +1,5 @@
 /**
- * (C) Copyright IBM Corp. 2021.
+ * (C) Copyright IBM Corp. 2021, 2022.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -28,27 +28,27 @@ export declare class VpcInstanceTokenManager extends JwtTokenManager {
     private iamProfileCrn;
     private iamProfileId;
     /**
-     * Create a new [[VpcInstanceTokenManager]] instance.
+     * Create a new VpcInstanceTokenManager instance.
      *
-     * @param {object} [options] Configuration options.
-     * @param {string} [options.iamProfileCrn] The CRN of the linked trusted IAM profile to be used as the identity of the compute resource.
-     *    At most one of iamProfileCrn or iamProfileId may be specified.
-     *    If neither one is specified, then the default IAM profile defined for the compute resource will be used.
-     * @param {string} [options.iamProfileId] The ID of the linked trusted IAM profile to be used when obtaining the IAM access token.
-     *    At most one of iamProfileCrn or iamProfileId may be specified.
-     *    If neither one is specified, then the default IAM profile defined for the compute resource will be used.
-     * @param {string} [options.url] The VPC Instance Metadata Service's base endpoint URL. Default value: "http://169.254.169.254"
-     * @constructor
+     * @param options - Configuration options.
+     * This should be an object containing these fields:
+     * - url: (optional) the endpoint URL for the VPC Instance Metadata Service (default value: "http://169.254.169.254")
+     * - iamProfileCrn: (optional) the CRN of the linked IAM trusted profile to be used to obtain the IAM access token
+     * - iamProfileId: (optional) the ID of the linked IAM trusted profile to be used to obtain the IAM access token
+     *
+     * @remarks
+     * At most one of "iamProfileCrn" or "iamProfileId" may be specified. If neither one is specified,
+     * then the default IAM profile defined for the compute resource will be used.
      */
     constructor(options: Options);
     /**
-     * Setter for the "trusted_profile" parameter to use when fetching the bearer token from the IAM token server.
-     * @param {string} iamProfileCrn A string that makes up the iamProfileCrn parameter
+     * Sets the CRN of the IAM trusted profile to use when fetching the access token from the IAM token server.
+     * @param iamProfileCrn - the CRN of the IAM trusted profile
      */
     setIamProfileCrn(iamProfileCrn: string): void;
     /**
-     * Setter for the "trusted_profile" parameter to use when fetching the bearer token from the IAM token server.
-     * @param {string} iamProfileId A string that makes up the iamProfileId parameter
+     * Sets the Id of the IAM trusted profile to use when fetching the access token from the IAM token server.
+     * @param iamProfileId - the ID of the IAM trusted profile
      */
     setIamProfileId(iamProfileId: string): void;
     protected requestToken(): Promise<any>;

package/es/auth/token-managers/vpc-instance-token-manager.js

@@ -1,5 +1,5 @@
 /**
- * (C) Copyright IBM Corp. 2021.
+ * (C) Copyright IBM Corp. 2021, 2022.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -32,17 +32,17 @@ const METADATA_SERVICE_VERSION = '2021-09-20';
  */
 export class VpcInstanceTokenManager extends JwtTokenManager {
     /**
-     * Create a new [[VpcInstanceTokenManager]] instance.
+     * Create a new VpcInstanceTokenManager instance.
      *
-     * @param {object} [options] Configuration options.
-     * @param {string} [options.iamProfileCrn] The CRN of the linked trusted IAM profile to be used as the identity of the compute resource.
-     *    At most one of iamProfileCrn or iamProfileId may be specified.
-     *    If neither one is specified, then the default IAM profile defined for the compute resource will be used.
-     * @param {string} [options.iamProfileId] The ID of the linked trusted IAM profile to be used when obtaining the IAM access token.
-     *    At most one of iamProfileCrn or iamProfileId may be specified.
-     *    If neither one is specified, then the default IAM profile defined for the compute resource will be used.
-     * @param {string} [options.url] The VPC Instance Metadata Service's base endpoint URL. Default value: "http://169.254.169.254"
-     * @constructor
+     * @param options - Configuration options.
+     * This should be an object containing these fields:
+     * - url: (optional) the endpoint URL for the VPC Instance Metadata Service (default value: "http://169.254.169.254")
+     * - iamProfileCrn: (optional) the CRN of the linked IAM trusted profile to be used to obtain the IAM access token
+     * - iamProfileId: (optional) the ID of the linked IAM trusted profile to be used to obtain the IAM access token
+     *
+     * @remarks
+     * At most one of "iamProfileCrn" or "iamProfileId" may be specified. If neither one is specified,
+     * then the default IAM profile defined for the compute resource will be used.
      */
     constructor(options) {
         // all parameters are optional
@@ -60,15 +60,15 @@ export class VpcInstanceTokenManager extends JwtTokenManager {
         }
     }
     /**
-     * Setter for the "trusted_profile" parameter to use when fetching the bearer token from the IAM token server.
-     * @param {string} iamProfileCrn A string that makes up the iamProfileCrn parameter
+     * Sets the CRN of the IAM trusted profile to use when fetching the access token from the IAM token server.
+     * @param iamProfileCrn - the CRN of the IAM trusted profile
      */
     setIamProfileCrn(iamProfileCrn) {
         this.iamProfileCrn = iamProfileCrn;
     }
     /**
-     * Setter for the "trusted_profile" parameter to use when fetching the bearer token from the IAM token server.
-     * @param {string} iamProfileId A string that makes up the iamProfileId parameter
+     * Sets the Id of the IAM trusted profile to use when fetching the access token from the IAM token server.
+     * @param iamProfileId - the ID of the IAM trusted profile
      */
     setIamProfileId(iamProfileId) {
         this.iamProfileId = iamProfileId;

package/es/auth/utils/get-authenticator-from-environment.d.ts

@@ -1,5 +1,5 @@
 /**
- * (C) Copyright IBM Corp. 2019, 2021.
+ * (C) Copyright IBM Corp. 2019, 2022.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -22,7 +22,7 @@ import { Authenticator } from '../authenticators';
  * 2. Environment variables
  * 3. VCAP Services (Cloud Foundry)
  *
- * @param {string} serviceName The service name prefix.
+ * @param serviceName - the service name prefix.
  *
  */
 export declare function getAuthenticatorFromEnvironment(serviceName: string): Authenticator;

package/es/auth/utils/get-authenticator-from-environment.js

@@ -1,5 +1,5 @@
 /**
- * (C) Copyright IBM Corp. 2019, 2021.
+ * (C) Copyright IBM Corp. 2019, 2022.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -23,7 +23,7 @@ import { readExternalSources } from './read-external-sources';
  * 2. Environment variables
  * 3. VCAP Services (Cloud Foundry)
  *
- * @param {string} serviceName The service name prefix.
+ * @param serviceName - the service name prefix.
  *
  */
 export function getAuthenticatorFromEnvironment(serviceName) {

package/es/auth/utils/helpers.d.ts

@@ -1,5 +1,5 @@
 /**
- * (C) Copyright IBM Corp. 2019, 2021.
+ * (C) Copyright IBM Corp. 2019, 2022.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -16,66 +16,68 @@
 /**
  * Compute and return a Basic Authorization header from a username and password.
  *
- * @param {string} username - The username or client id
- * @param {string} password - The password or client secret
- * @returns {string} - A Basic Auth header with format "Basic <encoded-credentials>"
+ * @param username - The username or client id
+ * @param password - The password or client secret
+ * @returns a Basic Auth header with format "Basic <encoded-credentials>"
  */
 export declare function computeBasicAuthHeader(username: string, password: string): string;
 /**
- * Checks credentials for common user mistakes of copying {, }, or " characters from the documentation
+ * Checks credentials for common user mistakes of copying \{, \}, or \" characters from the documentation
  *
- * @param {object} obj - The options object holding credentials
- * @param {string[]} credsToCheck - An array containing the keys of the credentials to check for problems
- * @returns {string | null} - Returns a string with the error message if there were problems, null if not
+ * @param obj - the options object holding credentials
+ * @param credsToCheck - an array containing the keys of the credentials to check for problems
+ * @returns a string with the error message if there were problems, null if not
  */
 export declare function checkCredentials(obj: any, credsToCheck: string[]): Error | null;
 /**
- * @param {object} options - A configuration options object.
- * @param {string[]} requiredOptions - The list of properties that must be specified.
+ * Validates "options".
+ * @param options - a configuration options object
+ * @param requiredOptions - the list of properties that must be present in "options"
+ *
+ * @throws Error: "options" failed validation
  */
 export declare function validateInput(options: any, requiredOptions: string[]): void;
 /**
- * Get the current time
+ * Gets the current time.
  *
- * @returns {number} - Returns the current time in seconds.
+ * @returns the current time in seconds.
  */
 export declare function getCurrentTime(): number;
 /**
- * Check for only one of two elements being defined.
+ * Checks for only one of two elements being defined.
  * Returns true if a is defined and b is undefined,
  * or vice versa. Returns false if both are defined
  * or both are undefined.
  *
- * @param {any} a - The first object
- * @param {any} b - The second object
- * @returns {boolean}
+ * @param a - The first object
+ * @param b - The second object
+ * @returns true if and only if exactly one of a or b is defined
  */
 export declare function onlyOne(a: any, b: any): boolean;
 /**
- * Remove a given suffix if it exists.
+ * Removes a given suffix if it exists.
+ *
+ * @param str - the base string to operate on
+ * @param suffix - the suffix to remove, if present
  *
- * @param {string} str - The base string to operate on
- * @param {string} suffix - The suffix to remove, if present
- * @returns {string}
+ * @returns the substring of "str" that remains after the suffix is removed
  */
 export declare function removeSuffix(str: string, suffix: string): string;
 /**
- * Check for at least one of two elements being defined.
- * Returns true if a or b is defined. Returns false if
- * both are undefined.
+ * Checks for at least one of two elements being defined.
  *
- * @param {any} a - The first object
- * @param {any} b - The second object
- * @returns {boolean}
+ * @param a - the first object
+ * @param b - the second object
+ * @returns true if a or b is defined; false if both are undefined
  */
 export declare function atLeastOne(a: any, b: any): boolean;
 /**
- * Verify that both properties are not specified.
- * Returns true if only a, only b, or neither is defined.
- * Returns false if both are defined.
+ * Verifies that both properties are not specified.
+ *
+ * @param a - The first object
+ * @param b - The second object
  *
- * @param {any} a - The first object
- * @param {any} b - The second object
- * @returns {boolean}
+ * @returns  false if a and b are both defined, true otherwise
+
  */
 export declare function atMostOne(a: any, b: any): boolean;