ibm-cloud-sdk-core 4.0.0 → 4.0.2

package/es/auth/utils/helpers.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.
@@ -17,9 +17,9 @@ import { getMissingParams } from '../../lib/helper';
 /**
  * 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 function computeBasicAuthHeader(username, password) {
     const encodedCreds = Buffer.from(`${username}:${password}`).toString('base64');
@@ -31,11 +31,11 @@ function badCharAtAnEnd(value) {
     return (value.startsWith('{') || value.startsWith('"') || value.endsWith('}') || value.endsWith('"'));
 }
 /**
- * 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 function checkCredentials(obj, credsToCheck) {
     let errorMessage = '';
@@ -52,8 +52,11 @@ export function checkCredentials(obj, credsToCheck) {
     return 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 function validateInput(options, requiredOptions) {
     // check for required params
@@ -70,32 +73,33 @@ export function validateInput(options, requiredOptions) {
     }
 }
 /**
- * Get the current time
+ * Gets the current time.
  *
- * @returns {number} - Returns the current time in seconds.
+ * @returns the current time in seconds.
  */
 export function getCurrentTime() {
     return Math.floor(Date.now() / 1000);
 }
 /**
- * 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 function onlyOne(a, b) {
     return Boolean((a && !b) || (b && !a));
 }
 /**
- * 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 function removeSuffix(str, suffix) {
     if (str.endsWith(suffix)) {
@@ -104,25 +108,23 @@ export function removeSuffix(str, suffix) {
     return str;
 }
 /**
- * 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 function atLeastOne(a, b) {
     return Boolean(a || b);
 }
 /**
- * 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 function atMostOne(a, b) {
     return Boolean(!(a && b));

package/es/auth/utils/read-external-sources.d.ts

@@ -5,6 +5,7 @@
  * and will be converted to lower camel case.
  *
  * Only one source will be used at a time.
- * @param {string} serviceName The service name prefix.
+ *
+ * @param serviceName - the service name prefix
  */
 export declare function readExternalSources(serviceName: string): any;

package/es/auth/utils/read-external-sources.js

@@ -1,6 +1,6 @@
 /* eslint-disable no-restricted-syntax */
 /**
- * (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,7 +25,8 @@ import { readCredentialsFile } from './file-reading-helpers';
  * and will be converted to lower camel case.
  *
  * Only one source will be used at a time.
- * @param {string} serviceName The service name prefix.
+ *
+ * @param serviceName - the service name prefix
  */
 export function readExternalSources(serviceName) {
     if (!serviceName) {
@@ -57,8 +58,8 @@ function getProperties(serviceName) {
  * For example, if service.name is speech_to_text,
  * env properties are SPEECH_TO_TEXT_USERNAME and SPEECH_TO_TEXT_PASSWORD
  *
- * @param {object} envObj - the object containing the credentials keyed by environment variables
- * @returns {Credentials}
+ * @param envObj - the object containing the credentials keyed by environment variables
+ * @returns the set of credentials
  */
 function filterPropertiesByServiceName(envObj, serviceName) {
     const credentials = {};

package/es/lib/base-service.d.ts

@@ -1,5 +1,5 @@
 /**
- * (C) Copyright IBM Corp. 2014, 2021.
+ * (C) Copyright IBM Corp. 2014, 2022.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -63,40 +63,39 @@ export declare class BaseService {
     private requestWrapperInstance;
     /**
      * Configuration values for a service.
-     * @param {Authenticator} userOptions.authenticator Object used to authenticate requests to the service.
-     * @param {string} [userOptions.serviceUrl] The base url to use when contacting the service.
+     *
+     * @param userOptions - the configuration options to set on the service instance.
+     * This should be an object with the following fields:
+     * - authenticator: (required) an Object used to authenticate requests to the service.
+     * - serviceUrl: (optional) the base url to use when contacting the service.
      *   The base url may differ between IBM Cloud regions.
-     * @param {object<string, string>} [userOptions.headers] Default headers that shall be
-     *   included with every request to the service.
-     * @param {string} [userOptions.version] The API version date to use with the service,
-     *   in "YYYY-MM-DD" format.
-     * @param {boolean} [userOptions.disableSslVerification] A flag that indicates
-     *   whether verification of the token server's SSL certificate should be
+     * - headers: (optional) a set of HTTP headers that should be included with every request sent to the service
+     * - disableSslVerification: (optional) a flag that indicates whether verification of the server's SSL certificate should be
      *   disabled or not.
      */
     constructor(userOptions: UserOptions);
     /**
      * Get the instance of the authenticator set on the service.
      *
-     * @returns {Authenticator}
+     * @returns the Authenticator instance
      */
     getAuthenticator(): any;
     /**
      * Set the service URL to send requests to.
      *
-     * @param {string} url The base URL for the service.
+     * @param url - the base URL for the service.
      */
     setServiceUrl(url: string): void;
     /**
      * Set the HTTP headers to be sent in every request.
      *
-     * @param {OutgoingHttpHeaders} headers The map of headers to include in requests.
+     * @param headers - the map of headers to include in requests.
      */
     setDefaultHeaders(headers: OutgoingHttpHeaders): void;
     /**
      * Turn request body compression on or off.
      *
-     * @param {boolean} setting Will turn it on if 'true', off if 'false'.
+     * @param setting - Will turn it on if 'true', off if 'false'.
      */
     setEnableGzipCompression(setting: boolean): void;
     /**
@@ -107,7 +106,7 @@ export declare class BaseService {
     /**
      * Enable retries for unfulfilled requests.
      *
-     * @param {RetryOptions} retryOptions configuration for retries
+     * @param retryOptions - the configuration for retries
      */
     enableRetries(retryOptions?: RetryOptions): void;
     /**
@@ -117,30 +116,30 @@ export declare class BaseService {
     /**
      * Configure the service using external configuration
      *
-     * @param {string} serviceName The name of the service. Will be used to read from external
+     * @param serviceName - the name of the service. This will be used to read from external
      * configuration.
      */
     protected configureService(serviceName: string): void;
     /**
      * Wrapper around `sendRequest` that enforces the request will be authenticated.
      *
-     * @param {object} parameters Service request options passed in by user.
-     * @param {string} parameters.options.method The http method.
-     * @param {string} parameters.options.url The path portion of the URL to be appended to the serviceUrl.
-     * @param {object} [parameters.options.path] The path parameters to be inserted into the URL.
-     * @param {object} [parameters.options.qs] The querystring to be included in the URL.
-     * @param {object} [parameters.options.body] The data to be sent as the request body.
-     * @param {object} [parameters.options.form] An object containing the key/value pairs for a www-form-urlencoded request.
-     * @param {object} [parameters.options.formData] An object containing the contents for a multipart/form-data request
-     * The following processing is performed on formData values:
-     * - string: no special processing -- the value is sent as is
-     * - object: the value is converted to a JSON string before insertion into the form body
-     * - NodeJS.ReadableStream|Buffer|FileWithMetadata: sent as a file, with any associated metadata
-     * - array: each element of the array is sent as a separate form part using any special processing as described above
-     * @param {object} parameters.defaultOptions
-     * @param {string} parameters.defaultOptions.serviceUrl The base URL of the service.
-     * @param {OutgoingHttpHeaders} parameters.defaultOptions.headers Additional headers to be passed on the request.
-     * @returns {Promise<any>}
+     * @param parameters - Service request options passed in by user.
+     * This should be an object with the following fields:
+     * - options.method: the http method
+     * - options.url: the path portion of the URL to be appended to the serviceUrl
+     * - options.path: the path parameters to be inserted into the URL
+     * - options.qs: the querystring to be included in the URL
+     * - options.body: the data to be sent as the request body
+     * - options.form: an object containing the key/value pairs for a www-form-urlencoded request.
+     * - options.formData: an object containing the contents for a multipart/form-data request
+     *   The following processing is performed on formData values:
+     *     - string: no special processing -- the value is sent as is
+     *     - object: the value is converted to a JSON string before insertion into the form body
+     *     - NodeJS.ReadableStream|Buffer|FileWithMetadata: sent as a file, with any associated metadata
+     *     - array: each element of the array is sent as a separate form part using any special processing as described above
+     * - defaultOptions.serviceUrl: the base URL of the service
+     * - defaultOptions.headers: additional HTTP headers to be sent with the request
+     * @returns a Promise
      */
     protected createRequest(parameters: any): Promise<any>;
     private readOptionsFromExternalConfig;

package/es/lib/base-service.js

@@ -1,5 +1,5 @@
 /**
- * (C) Copyright IBM Corp. 2014, 2021.
+ * (C) Copyright IBM Corp. 2014, 2022.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -26,15 +26,14 @@ import { RequestWrapper } from './request-wrapper';
 export class BaseService {
     /**
      * Configuration values for a service.
-     * @param {Authenticator} userOptions.authenticator Object used to authenticate requests to the service.
-     * @param {string} [userOptions.serviceUrl] The base url to use when contacting the service.
+     *
+     * @param userOptions - the configuration options to set on the service instance.
+     * This should be an object with the following fields:
+     * - authenticator: (required) an Object used to authenticate requests to the service.
+     * - serviceUrl: (optional) the base url to use when contacting the service.
      *   The base url may differ between IBM Cloud regions.
-     * @param {object<string, string>} [userOptions.headers] Default headers that shall be
-     *   included with every request to the service.
-     * @param {string} [userOptions.version] The API version date to use with the service,
-     *   in "YYYY-MM-DD" format.
-     * @param {boolean} [userOptions.disableSslVerification] A flag that indicates
-     *   whether verification of the token server's SSL certificate should be
+     * - headers: (optional) a set of HTTP headers that should be included with every request sent to the service
+     * - disableSslVerification: (optional) a flag that indicates whether verification of the server's SSL certificate should be
      *   disabled or not.
      */
     constructor(userOptions) {
@@ -75,7 +74,7 @@ export class BaseService {
     /**
      * Get the instance of the authenticator set on the service.
      *
-     * @returns {Authenticator}
+     * @returns the Authenticator instance
      */
     getAuthenticator() {
         return this.authenticator;
@@ -83,7 +82,7 @@ export class BaseService {
     /**
      * Set the service URL to send requests to.
      *
-     * @param {string} url The base URL for the service.
+     * @param url - the base URL for the service.
      */
     setServiceUrl(url) {
         if (url) {
@@ -93,7 +92,7 @@ export class BaseService {
     /**
      * Set the HTTP headers to be sent in every request.
      *
-     * @param {OutgoingHttpHeaders} headers The map of headers to include in requests.
+     * @param headers - the map of headers to include in requests.
      */
     setDefaultHeaders(headers) {
         if (typeof headers !== 'object') {
@@ -105,7 +104,7 @@ export class BaseService {
     /**
      * Turn request body compression on or off.
      *
-     * @param {boolean} setting Will turn it on if 'true', off if 'false'.
+     * @param setting - Will turn it on if 'true', off if 'false'.
      */
     setEnableGzipCompression(setting) {
         this.requestWrapperInstance.setCompressRequestData(setting);
@@ -122,7 +121,7 @@ export class BaseService {
     /**
      * Enable retries for unfulfilled requests.
      *
-     * @param {RetryOptions} retryOptions configuration for retries
+     * @param retryOptions - the configuration for retries
      */
     enableRetries(retryOptions) {
         this.requestWrapperInstance.enableRetries(retryOptions);
@@ -136,7 +135,7 @@ export class BaseService {
     /**
      * Configure the service using external configuration
      *
-     * @param {string} serviceName The name of the service. Will be used to read from external
+     * @param serviceName - the name of the service. This will be used to read from external
      * configuration.
      */
     configureService(serviceName) {
@@ -152,23 +151,23 @@ export class BaseService {
     /**
      * Wrapper around `sendRequest` that enforces the request will be authenticated.
      *
-     * @param {object} parameters Service request options passed in by user.
-     * @param {string} parameters.options.method The http method.
-     * @param {string} parameters.options.url The path portion of the URL to be appended to the serviceUrl.
-     * @param {object} [parameters.options.path] The path parameters to be inserted into the URL.
-     * @param {object} [parameters.options.qs] The querystring to be included in the URL.
-     * @param {object} [parameters.options.body] The data to be sent as the request body.
-     * @param {object} [parameters.options.form] An object containing the key/value pairs for a www-form-urlencoded request.
-     * @param {object} [parameters.options.formData] An object containing the contents for a multipart/form-data request
-     * The following processing is performed on formData values:
-     * - string: no special processing -- the value is sent as is
-     * - object: the value is converted to a JSON string before insertion into the form body
-     * - NodeJS.ReadableStream|Buffer|FileWithMetadata: sent as a file, with any associated metadata
-     * - array: each element of the array is sent as a separate form part using any special processing as described above
-     * @param {object} parameters.defaultOptions
-     * @param {string} parameters.defaultOptions.serviceUrl The base URL of the service.
-     * @param {OutgoingHttpHeaders} parameters.defaultOptions.headers Additional headers to be passed on the request.
-     * @returns {Promise<any>}
+     * @param parameters - Service request options passed in by user.
+     * This should be an object with the following fields:
+     * - options.method: the http method
+     * - options.url: the path portion of the URL to be appended to the serviceUrl
+     * - options.path: the path parameters to be inserted into the URL
+     * - options.qs: the querystring to be included in the URL
+     * - options.body: the data to be sent as the request body
+     * - options.form: an object containing the key/value pairs for a www-form-urlencoded request.
+     * - options.formData: an object containing the contents for a multipart/form-data request
+     *   The following processing is performed on formData values:
+     *     - string: no special processing -- the value is sent as is
+     *     - object: the value is converted to a JSON string before insertion into the form body
+     *     - NodeJS.ReadableStream|Buffer|FileWithMetadata: sent as a file, with any associated metadata
+     *     - array: each element of the array is sent as a separate form part using any special processing as described above
+     * - defaultOptions.serviceUrl: the base URL of the service
+     * - defaultOptions.headers: additional HTTP headers to be sent with the request
+     * @returns a Promise
      */
     createRequest(parameters) {
         // validate serviceUrl parameter has been set

package/es/lib/content-type.js

@@ -1,6 +1,6 @@
 /* eslint-disable prettier/prettier */
 /**
- * (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.
@@ -39,8 +39,8 @@ const filenameContentTypes = {
 /**
  * Takes the beginning of an audio file and returns the associated content-type / mime type
  *
- * @param {Buffer} buffer With at least the first 4 bytes of the file
- * @return {String|undefined} The contentType or undefined
+ * @param buffer - a Buffer containing at least the first 4 bytes of the file
+ * @return sthe contentType or undefined
  */
 const fromHeader = (buffer) => {
     const headerStr = buffer
@@ -56,8 +56,8 @@ const fromHeader = (buffer) => {
  * Note: Blob and File objects include a .type property, but we're ignoring it because it's frequently either
  * incorrect (e.g. video/ogg instead of audio/ogg) or else a different format than what's expected (e.g. audio/x-wav)
  *
- * @param {String|ReadableStream|FileObject|Buffer|File} file String filename or url, or binary File/Blob object.
- * @return {String|undefined}
+ * @param file - a String filename or url, or binary File/Blob object.
+ * @returns the content type
  */
 const fromFilename = (file) => {
     const ext = extname(

package/es/lib/get-new-logger.d.ts

@@ -31,9 +31,9 @@ export interface SDKLogger {
  * Additionally, the logger will be turned on automatically if the "NODE_DEBUG"
  * environment variable is set to "axios".
  *
- * @param {string} moduleName - the namespace for the logger. The name will appear in
+ * @param moduleName - the namespace for the logger. The name will appear in
  * the logs and it will be the name used for configuring the log level.
  *
- * @returns {SDKLogger} the new logger
+ * @returns the new logger
  */
 export declare function getNewLogger(moduleName: string): SDKLogger;

package/es/lib/get-new-logger.js

@@ -24,10 +24,10 @@ import logger from 'debug';
  * Additionally, the logger will be turned on automatically if the "NODE_DEBUG"
  * environment variable is set to "axios".
  *
- * @param {string} moduleName - the namespace for the logger. The name will appear in
+ * @param moduleName - the namespace for the logger. The name will appear in
  * the logs and it will be the name used for configuring the log level.
  *
- * @returns {SDKLogger} the new logger
+ * @returns the new logger
  */
 export function getNewLogger(moduleName) {
     const debug = logger(`${moduleName}:debug`);

package/es/lib/helper.d.ts

@@ -1,5 +1,5 @@
 /**
- * (C) Copyright IBM Corp. 2014, 2021.
+ * (C) Copyright IBM Corp. 2014, 2022.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -35,31 +35,29 @@ export declare function isFileData(obj: any): obj is NodeJS.ReadableStream | Buf
 export declare function isEmptyObject(obj: any): boolean;
 /**
  * This function retrieves the content type of the input.
- * @param {NodeJS.ReadableStream|Buffer} inputData - The data to retrieve content type for.
- * @returns {string} the content type of the input.
+ * @param inputData - The data to retrieve content type for.
+ * @returns the content type of the input.
  */
 export declare function getContentType(inputData: NodeJS.ReadableStream | Buffer): Promise<string>;
 /**
- *
- * @param {string} url - the url string.
- * @returns {string}
+ * Strips trailing slashes from "url", if present.
+ * @param  url - the url string
+ * @returns the url with any trailing slashes removed
  */
 export declare function stripTrailingSlash(url: string): string;
 /**
  * Return a query parameter value from a URL
  *
- * @param {string} urlStr - the url string.
- * @param {string} param - the name of the query parameter
- *                     whose value should be returned
- * @returns {string} the value of the `param` query parameter
- * @throws if urlStr is an invalid URL
+ * @param urlStr - the url string.
+ * @param param - the name of the query parameter whose value should be returned
+ * @returns the value of the "param" query parameter
  */
 export declare function getQueryParam(urlStr: string, param: string): string;
 /**
  * Validates that all required params are provided
  * @param params - the method parameters.
  * @param requires - the required parameter names.
- * @returns {Error|null}
+ * @returns null if no errors found, otherwise an Error instance
  */
 export declare function getMissingParams(params: {
     [key: string]: any;
@@ -75,52 +73,47 @@ export declare function getMissingParams(params: {
  * If null, then the "required params" check is bypassed.
  * @param allParams - the names of all valid parameters.
  * If null, then the "valid params" check is bypassed.
- * @returns {Error|null}
+ * @returns null if no errors found, otherwise an Error instance
  */
 export declare function validateParams(params: {
     [key: string]: any;
 }, requiredParams: string[], allParams: string[]): null | Error;
 /**
  * Return true if 'text' is html
- * @param  {string} text - The 'text' to analyze
- * @returns {boolean} true if 'text' has html tags
+ * @param  text - The 'text' to analyze
+ * @returns true if 'text' has html tags
  */
 export declare function isHTML(text: string): boolean;
 /**
  * Returns the first match from formats that is key the params map
  * otherwise null
- * @param  {Object} params - The parameters.
- * @param  {string[]} requires - The keys we want to check
- * @returns {string|null}
+ * @param  params - The parameters.
+ * @param  requires - The keys we want to check
  */
 export declare function getFormat(params: {
     [key: string]: any;
 }, formats: string[]): string;
 /**
  * This function builds a `form-data` object for each file parameter.
- * @param {FileWithMetadata} fileParam The file parameter.
- * @param {NodeJS.ReadableStream|Buffer} fileParam.data The data content of the file.
- * @param {string} fileParam.filename The filename of the file.
- * @param {string} fileParam.contentType The content type of the file.
- * @returns {FileObject}
+ * @param fileParam - The FileWithMetadata instance that contains the file information
+ * @returns the FileObject instance
  */
 export declare function buildRequestFileObject(fileParam: FileWithMetadata): Promise<FileObject>;
 /**
  * This function converts an object's keys to lower case.
  * note: does not convert nested keys
- * @param {Object} obj The object to convert the keys of.
- * @returns {Object}
+ * @param obj - The object to convert the keys of.
+ * @returns the object with keys folded to lowercase
  */
 export declare function toLowerKeys(obj: Object): Object;
 /**
  * Constructs a service URL by formatting a parameterized URL.
  *
- * @param {string} parameterizedUrl URL that contains variable placeholders, e.g. '{scheme}://ibm.com'.
- * @param {Map<string, string>} defaultUrlVariables Map from variable names to default values.
+ * @param parameterizedUrl - a URL that contains variable placeholders, e.g. '\{scheme\}://ibm.com'.
+ * @param defaultUrlVariables - a Map of variable names to default values.
  *  Each variable in the parameterized URL must have a default value specified in this map.
- * @param {Map<string, string>} providedUrlVariables Map from variable names to desired values.
- *  If a variable is not provided in this map,
- *  the default variable value will be used instead.
- * @returns {string} The formatted URL with all variable placeholders replaced by values.
+ * @param providedUrlVariables - a Map of variable names to desired values.
+ *  If a variable is not provided in this map, the default variable value will be used instead.
+ * @returns the formatted URL with all variable placeholders replaced by values.
  */
 export declare function constructServiceUrl(parameterizedUrl: string, defaultUrlVariables: Map<string, string>, providedUrlVariables: Map<string, string> | null): string;