ibm-cloud-sdk-core - npm Package Compare versions

Comparing version 1.3.0 to 2.0.0

auth/authenticators/authenticator-interface.d.ts

@@ -18,8 +18,26 @@ /**
 import { OutgoingHttpHeaders } from 'http';
+/**
+ * The request object containing the headers property that
+ * authentication information will be added to.
+ */
 export interface AuthenticateOptions {
+    /**
+     * Headers to augment with authentication information.
+     */
     headers?: OutgoingHttpHeaders;
     [propName: string]: any;
 }
+/**
+ * This interface defines the common methods associated with an Authenticator
+ * implementation.
+ */
 export interface AuthenticatorInterface {
-    authenticate(options: AuthenticateOptions): Promise<void | Error>;
+    /**
+     * Add authentication information to the specified request.
+     *
+     * @param {object} requestOptions The request to augment with authentication information.
+     * @param {object.<string, string>} requestOptions.headers The headers the
+     *   authentication information will be added to.
+     */
+    authenticate(requestOptions: AuthenticateOptions): Promise<void | Error>;
 }

auth/authenticators/authenticator-interface.js

@@ -18,2 +18,1 @@ "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=authenticator-interface.js.map

auth/authenticators/authenticator.d.ts

@@ -17,10 +17,24 @@ /**
 import { AuthenticateOptions, AuthenticatorInterface } from './authenticator-interface';
+/**
+ * Base Authenticator class for other Authenticators to extend. Not intended
+ * to be used as a stand-alone authenticator.
+ */
 export declare class Authenticator implements AuthenticatorInterface {
     /**
-     * Base Authenticator Class
+     * Create a new Authenticator instance.
      *
-     * Provides the Base Authenticator class for others to extend.
+     * @throws {Error} The `new` keyword was not used to create construct the
+     *   authenticator.
      */
     constructor();
-    authenticate(options: AuthenticateOptions): Promise<void | Error>;
+    /**
+     * Augment the request with authentication information.
+     *
+     * @param {object} requestOptions - The request to augment with authentication information.
+     * @param {object.<string, string>} requestOptions.headers - The headers the
+     *   authentication information will be added too.
+     * @throws {Error} - The authenticate method was not implemented by a
+     *   subclass.
+     */
+    authenticate(requestOptions: AuthenticateOptions): Promise<void | Error>;
 }

auth/authenticators/authenticator.js

@@ -18,7 +18,12 @@ "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Base Authenticator class for other Authenticators to extend. Not intended
+ * to be used as a stand-alone authenticator.
+ */
 var Authenticator = /** @class */ (function () {
     /**
-     * Base Authenticator Class
+     * Create a new Authenticator instance.
      *
-     * Provides the Base Authenticator class for others to extend.
+     * @throws {Error} The `new` keyword was not used to create construct the
+     *   authenticator.
      */
@@ -30,3 +35,12 @@ function Authenticator() {
     }
-    Authenticator.prototype.authenticate = function (options) {
+    /**
+     * Augment the request with authentication information.
+     *
+     * @param {object} requestOptions - The request to augment with authentication information.
+     * @param {object.<string, string>} requestOptions.headers - The headers the
+     *   authentication information will be added too.
+     * @throws {Error} - The authenticate method was not implemented by a
+     *   subclass.
+     */
+    Authenticator.prototype.authenticate = function (requestOptions) {
         var error = new Error('Should be implemented by subclass!');
@@ -38,2 +52,1 @@ return Promise.reject(error);
 exports.Authenticator = Authenticator;
-//# sourceMappingURL=authenticator.js.map

auth/authenticators/basic-authenticator.d.ts

@@ -17,23 +17,44 @@ /**
 import { Authenticator } from './authenticator';
-import { AuthenticateOptions, AuthenticatorInterface } from './authenticator-interface';
+import { AuthenticateOptions } from './authenticator-interface';
+/** Configuration options for basic authentication. */
 export declare type Options = {
+    /** The username to be used in basic authorization. */
     username: string;
+    /** The password to be used in basic authorization. */
     password: string;
 };
-export declare class BasicAuthenticator extends Authenticator implements AuthenticatorInterface {
+/**
+ * The BasicAuthenticator is used to add basic authentication information to
+ *   requests.
+ *
+ * Basic Authorization will be sent as an Authorization header in the form:
+ *
+ *     Authorization: Basic <encoded username and password>
+ *
+ */
+export declare class BasicAuthenticator extends Authenticator {
     protected requiredOptions: string[];
-    private username;
-    private password;
+    protected authHeader: {
+        Authorization: string;
+    };
     /**
-     * Basic Authenticator Class
+     * Create a new BasicAuthenticator instance.
      *
-     * Handles the Basic Authentication pattern.
+     * @param {object} options Configuration options for basic authentication.
+     * @param {string} options.username The username portion of basic authentication.
+     * @param {string} options.password The password portion of basic authentication.
+     * @throws {Error} The configuration options are not valid.
+     */
+    constructor(options: Options);
+    /**
+     * Add basic authentication information to `request`. The basic authentication information
+     * will be set in the Authorization property of`request.headers` in the form:
      *
-     * @param {Object} options
-     * @param {String} options.username
-     * @param {String} options.password
-     * @constructor
+     *     Authorization: Basic <encoded username and password>
+     *
+     * @param {object} requestOptions - The request to augment with authentication information.
+     * @param {object.<string, string>} requestOptions.headers - The headers the
+     *   authentication information will be added too.
      */
-    constructor(options: Options);
-    authenticate(options: AuthenticateOptions): Promise<void>;
+    authenticate(requestOptions: AuthenticateOptions): Promise<void | Error>;
 }

auth/authenticators/basic-authenticator.js

@@ -34,13 +34,20 @@ "use strict";
 var authenticator_1 = require("./authenticator");
+/**
+ * The BasicAuthenticator is used to add basic authentication information to
+ *   requests.
+ *
+ * Basic Authorization will be sent as an Authorization header in the form:
+ *
+ *     Authorization: Basic <encoded username and password>
+ *
+ */
 var BasicAuthenticator = /** @class */ (function (_super) {
     __extends(BasicAuthenticator, _super);
     /**
-     * Basic Authenticator Class
+     * Create a new BasicAuthenticator instance.
      *
-     * Handles the Basic Authentication pattern.
-     *
-     * @param {Object} options
-     * @param {String} options.username
-     * @param {String} options.password
-     * @constructor
+     * @param {object} options Configuration options for basic authentication.
+     * @param {string} options.username The username portion of basic authentication.
+     * @param {string} options.password The password portion of basic authentication.
+     * @throws {Error} The configuration options are not valid.
      */
@@ -51,12 +58,21 @@ function BasicAuthenticator(options) {
         utils_1.validateInput(options, _this.requiredOptions);
-        _this.username = options.username;
-        _this.password = options.password;
+        var username = options.username, password = options.password;
+        var authHeaderString = utils_1.computeBasicAuthHeader(username, password);
+        _this.authHeader = { Authorization: authHeaderString };
         return _this;
     }
-    BasicAuthenticator.prototype.authenticate = function (options) {
+    /**
+     * Add basic authentication information to `request`. The basic authentication information
+     * will be set in the Authorization property of`request.headers` in the form:
+     *
+     *     Authorization: Basic <encoded username and password>
+     *
+     * @param {object} requestOptions - The request to augment with authentication information.
+     * @param {object.<string, string>} requestOptions.headers - The headers the
+     *   authentication information will be added too.
+     */
+    BasicAuthenticator.prototype.authenticate = function (requestOptions) {
         var _this = this;
-        return new Promise(function (resolve, reject) {
-            var authHeaderString = utils_1.computeBasicAuthHeader(_this.username, _this.password);
-            var authHeader = { Authorization: authHeaderString };
-            options.headers = extend(true, {}, options.headers, authHeader);
+        return new Promise(function (resolve) {
+            requestOptions.headers = extend(true, {}, requestOptions.headers, _this.authHeader);
             resolve();
@@ -68,2 +84,1 @@ });
 exports.BasicAuthenticator = BasicAuthenticator;
-//# sourceMappingURL=basic-authenticator.js.map

auth/authenticators/bearer-token-authenticator.d.ts

@@ -17,21 +17,47 @@ /**
 import { Authenticator } from './authenticator';
-import { AuthenticateOptions, AuthenticatorInterface } from './authenticator-interface';
+import { AuthenticateOptions } from './authenticator-interface';
+/** Configuration options for bearer authentication. */
 export declare type Options = {
+    /** The bearer token to be added to requests. */
     bearerToken: string;
 };
-export declare class BearerTokenAuthenticator extends Authenticator implements AuthenticatorInterface {
+/**
+ * The BearerTokenAuthenticator will set a user-provided bearer token
+ *   in requests.
+ *
+ * The bearer token will be sent as an Authorization header in the form:
+ *
+ *      Authorization: Bearer <bearer-token>
+ */
+export declare class BearerTokenAuthenticator extends Authenticator {
     protected requiredOptions: string[];
     private bearerToken;
     /**
-     * Bearer Token Authenticator Class
+     * Create a new BearerTokenAuthenticator instance.
      *
-     * Handles the Bearer Token pattern.
+     * @param {object} options Configuration options for bearer authentication.
+     * @param {string} options.bearerToken The bearer token to be added
+     *   to requests.
+     * @throws {Error} The configuration bearerToken is not valid, or unspecified.
+     */
+    constructor(options: Options);
+    /**
+     * Set a new bearer token to be sent in subsequent requests.
      *
-     * @param {Object} options
-     * @param {String} options.bearerToken - bearer token to pass in header
-     * @constructor
+     * @param {string} bearerToken The bearer token that will be sent in service
+     *   requests.
      */
-    constructor(options: Options);
     setBearerToken(bearerToken: string): void;
-    authenticate(options: AuthenticateOptions): Promise<void>;
+    /**
+     * Add a bearer token to the `request`. The bearer token information
+     * will be set in the Authorization property of`request.headers` in the form:
+     *
+     *      Authorization: Bearer <bearer-token>
+     *
+     * @param {object} requestOptions - The request to augment with authentication
+     *   information.
+     * @param {object.<string, string>} requestOptions.headers - The headers the
+     *   authentication information will be added to.
+     */
+    authenticate(requestOptions: AuthenticateOptions): Promise<void>;
 }

auth/authenticators/bearer-token-authenticator.js

@@ -34,12 +34,19 @@ "use strict";
 var authenticator_1 = require("./authenticator");
+/**
+ * The BearerTokenAuthenticator will set a user-provided bearer token
+ *   in requests.
+ *
+ * The bearer token will be sent as an Authorization header in the form:
+ *
+ *      Authorization: Bearer <bearer-token>
+ */
 var BearerTokenAuthenticator = /** @class */ (function (_super) {
     __extends(BearerTokenAuthenticator, _super);
     /**
-     * Bearer Token Authenticator Class
+     * Create a new BearerTokenAuthenticator instance.
      *
-     * Handles the Bearer Token pattern.
-     *
-     * @param {Object} options
-     * @param {String} options.bearerToken - bearer token to pass in header
-     * @constructor
+     * @param {object} options Configuration options for bearer authentication.
+     * @param {string} options.bearerToken The bearer token to be added
+     *   to requests.
+     * @throws {Error} The configuration bearerToken is not valid, or unspecified.
      */
@@ -53,10 +60,27 @@ function BearerTokenAuthenticator(options) {
     }
+    /**
+     * Set a new bearer token to be sent in subsequent requests.
+     *
+     * @param {string} bearerToken The bearer token that will be sent in service
+     *   requests.
+     */
     BearerTokenAuthenticator.prototype.setBearerToken = function (bearerToken) {
         this.bearerToken = bearerToken;
     };
-    BearerTokenAuthenticator.prototype.authenticate = function (options) {
+    /**
+     * Add a bearer token to the `request`. The bearer token information
+     * will be set in the Authorization property of`request.headers` in the form:
+     *
+     *      Authorization: Bearer <bearer-token>
+     *
+     * @param {object} requestOptions - The request to augment with authentication
+     *   information.
+     * @param {object.<string, string>} requestOptions.headers - The headers the
+     *   authentication information will be added to.
+     */
+    BearerTokenAuthenticator.prototype.authenticate = function (requestOptions) {
         var _this = this;
-        return new Promise(function (resolve, reject) {
+        return new Promise(function (resolve) {
             var authHeader = { Authorization: "Bearer " + _this.bearerToken };
-            options.headers = extend(true, {}, options.headers, authHeader);
+            requestOptions.headers = extend(true, {}, requestOptions.headers, authHeader);
             resolve();
@@ -68,2 +92,1 @@ });
 exports.BearerTokenAuthenticator = BearerTokenAuthenticator;
-//# sourceMappingURL=bearer-token-authenticator.js.map

auth/authenticators/cloud-pak-for-data-authenticator.d.ts

@@ -18,7 +18,19 @@ /**
 import { BaseOptions, TokenRequestBasedAuthenticator } from './token-request-based-authenticator';
+/** Configuration options for CloudPakForData authentication. */
 export interface Options extends BaseOptions {
+    /** The username used to obtain a bearer token. */
     username: string;
+    /** The password used to obtain a bearer token. */
     password: string;
+    /** The URL representing the Cloud Pak for Data token service endpoint. */
     url: string;
 }
+/**
+ * The [[CloudPakForDataAuthenticator]] will use the user-supplied url, username and password values to obtain
+ * a bearer token from a token server.  When the bearer token expires, a new token is obtained from the token server.
+ *
+ * The bearer token will be sent as an Authorization header in the form:
+ *
+ *      Authorization: Bearer <bearer-token>
+ */
 export declare class CloudPakForDataAuthenticator extends TokenRequestBasedAuthenticator {
@@ -30,11 +42,16 @@ protected requiredOptions: string[];
     /**
-     * Cloud Pak for Data Authenticator Class
+     * Create a new [[CloudPakForDataAuthenticator]] instance.
      *
-     * Handles the CP4D authentication pattern:
-     * A username and password are provided and used to retrieve a bearer token.
-     *
-     * @param {Object} options
-     * @constructor
+     * @param {object} options Configuration options for CloudPakForData authentication.
+     * @param {string} options.url For HTTP token requests.
+     * @param {string} options.username The username used to obtain a bearer token.
+     * @param {string} options.password The password used to obtain a bearer token.
+     * @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] to be sent with every.
+     * @throws `Error` The username, password, and/or url are not valid, or unspecified, for Cloud Pak For Data token
+     *   requests.
      */
     constructor(options: Options);
 }

auth/authenticators/cloud-pak-for-data-authenticator.js

@@ -34,12 +34,25 @@ "use strict";
 var token_request_based_authenticator_1 = require("./token-request-based-authenticator");
+/**
+ * The [[CloudPakForDataAuthenticator]] will use the user-supplied url, username and password values to obtain
+ * a bearer token from a token server.  When the bearer token expires, a new token is obtained from the token server.
+ *
+ * The bearer token will be sent as an Authorization header in the form:
+ *
+ *      Authorization: Bearer <bearer-token>
+ */
 var CloudPakForDataAuthenticator = /** @class */ (function (_super) {
     __extends(CloudPakForDataAuthenticator, _super);
     /**
-     * Cloud Pak for Data Authenticator Class
+     * Create a new [[CloudPakForDataAuthenticator]] instance.
      *
-     * Handles the CP4D authentication pattern:
-     * A username and password are provided and used to retrieve a bearer token.
-     *
-     * @param {Object} options
-     * @constructor
+     * @param {object} options Configuration options for CloudPakForData authentication.
+     * @param {string} options.url For HTTP token requests.
+     * @param {string} options.username The username used to obtain a bearer token.
+     * @param {string} options.password The password used to obtain a bearer token.
+     * @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] to be sent with every.
+     * @throws `Error` The username, password, and/or url are not valid, or unspecified, for Cloud Pak For Data token
+     *   requests.
      */
@@ -52,4 +65,4 @@ function CloudPakForDataAuthenticator(options) {
         _this.password = options.password;
-        // the param names are shared between the authenticator and the token manager
-        // so we can just pass along the options object
+        // the param names are shared between the authenticator and the token
+        // manager so we can just pass along the options object
         _this.tokenManager = new token_managers_1.Cp4dTokenManager(options);
@@ -61,2 +74,1 @@ return _this;
 exports.CloudPakForDataAuthenticator = CloudPakForDataAuthenticator;
-//# sourceMappingURL=cloud-pak-for-data-authenticator.js.map

auth/authenticators/iam-authenticator.d.ts

@@ -18,7 +18,28 @@ /**
 import { BaseOptions, TokenRequestBasedAuthenticator } from './token-request-based-authenticator';
+/** Configuration options for IAM authentication. */
 export interface Options extends BaseOptions {
+    /** The IAM api key */
     apikey: string;
+    /**
+     * The `clientId` and `clientSecret` fields are used to form a "basic"
+     * authorization header for IAM token requests.
+     */
     clientId?: string;
+    /**
+     * The `clientId` and `clientSecret` fields are used to form a "basic"
+     * authorization header for IAM token requests.
+     */
     clientSecret?: string;
 }
+/**
+ * The [[IamAuthenticator]] will use the user-supplied `apikey`
+ * values to obtain a bearer token from a token server.  When the bearer token
+ * expires, a new token is obtained from the token server. If specified, the
+ * optional, mutually inclusive `clientId` and`clientSecret` pair can be used to
+ * influence rate-limiting for requests to the IAM token server.
+ *
+ * The bearer token will be sent as an Authorization header in the form:
+ *
+ *      Authorization: Bearer <bearer-token>
+ */
 export declare class IamAuthenticator extends TokenRequestBasedAuthenticator {
@@ -31,18 +52,27 @@ protected requiredOptions: string[];
     /**
-     * IAM Authenticator Class
      *
-     * Handles the IAM authentication pattern.
+     * Create a new [[IamAuthenticator]] instance.
      *
-     * @param {Object} options
-     * @constructor
+     * @param {object} options Configuration options for IAM authentication.
+     * @param {boolean} options.disableSslVerification A flag that indicates
+     *   whether verification of the token server's SSL certificate should be
+     *   disabled or not
+     * @param {string} options.url for HTTP token requests.
+     * @param {object<string, string>} options.headers to be sent with every
+     * @param {string} options.apikey The IAM api key.
+     * @param {string} [options.clientId] The `clientId` and `clientSecret` fields are used to form a "basic"
+     *   authorization header for IAM token requests.
+     * @param {string} [options.clientSecret] The `clientId` and `clientSecret` fields are used to form a "basic"
+     *   authorization header for IAM token requests.
+     * @throws {Error} When the configuration options are not valid.
      */
     constructor(options: Options);
     /**
-     * Setter for the Client ID and the Client Secret. Both should be provided.
-     *
-     * @param {string} clientId
-     * @param {string} clientSecret
-     * @returns {void}
+     * Setter for the mutually inclusive `clientId` and the `clientSecret`.
+     * @param {string} clientId The `clientId` and `clientSecret` fields are used to form a "basic"
+     *   authorization header for IAM token requests.
+     * @param {string} clientSecret The `clientId` and `clientSecret` fields are used to form a "basic"
+     *   authorization header for IAM token requests.
      */
     setClientIdAndSecret(clientId: string, clientSecret: string): void;
 }

auth/authenticators/iam-authenticator.js

@@ -34,11 +34,31 @@ "use strict";
 var token_request_based_authenticator_1 = require("./token-request-based-authenticator");
+/**
+ * The [[IamAuthenticator]] will use the user-supplied `apikey`
+ * values to obtain a bearer token from a token server.  When the bearer token
+ * expires, a new token is obtained from the token server. If specified, the
+ * optional, mutually inclusive `clientId` and`clientSecret` pair can be used to
+ * influence rate-limiting for requests to the IAM token server.
+ *
+ * The bearer token will be sent as an Authorization header in the form:
+ *
+ *      Authorization: Bearer <bearer-token>
+ */
 var IamAuthenticator = /** @class */ (function (_super) {
     __extends(IamAuthenticator, _super);
     /**
-     * IAM Authenticator Class
      *
-     * Handles the IAM authentication pattern.
+     * Create a new [[IamAuthenticator]] instance.
      *
-     * @param {Object} options
-     * @constructor
+     * @param {object} options Configuration options for IAM authentication.
+     * @param {boolean} options.disableSslVerification A flag that indicates
+     *   whether verification of the token server's SSL certificate should be
+     *   disabled or not
+     * @param {string} options.url for HTTP token requests.
+     * @param {object<string, string>} options.headers to be sent with every
+     * @param {string} options.apikey The IAM api key.
+     * @param {string} [options.clientId] The `clientId` and `clientSecret` fields are used to form a "basic"
+     *   authorization header for IAM token requests.
+     * @param {string} [options.clientSecret] The `clientId` and `clientSecret` fields are used to form a "basic"
+     *   authorization header for IAM token requests.
+     * @throws {Error} When the configuration options are not valid.
      */
@@ -52,4 +72,4 @@ function IamAuthenticator(options) {
         _this.clientSecret = options.clientSecret;
-        // the param names are shared between the authenticator and the token manager
-        // so we can just pass along the options object
+        // the param names are shared between the authenticator and the token
+        // manager so we can just pass along the options object
         _this.tokenManager = new token_managers_1.IamTokenManager(options);
@@ -59,7 +79,7 @@ return _this;
     /**
-     * Setter for the Client ID and the Client Secret. Both should be provided.
-     *
-     * @param {string} clientId
-     * @param {string} clientSecret
-     * @returns {void}
+     * Setter for the mutually inclusive `clientId` and the `clientSecret`.
+     * @param {string} clientId The `clientId` and `clientSecret` fields are used to form a "basic"
+     *   authorization header for IAM token requests.
+     * @param {string} clientSecret The `clientId` and `clientSecret` fields are used to form a "basic"
+     *   authorization header for IAM token requests.
      */
@@ -75,2 +95,1 @@ IamAuthenticator.prototype.setClientIdAndSecret = function (clientId, clientSecret) {
 exports.IamAuthenticator = IamAuthenticator;
-//# sourceMappingURL=iam-authenticator.js.map

auth/authenticators/index.d.ts

@@ -16,2 +16,24 @@ /**
  */
+/**
+ * @module authenticators
+ * The ibm-cloud-sdk-core module supports the following types of authentication:
+ *
+ * Basic Authentication
+ * Bearer Token
+ * Identity and Access Management (IAM)
+ * Cloud Pak for Data
+ * No Authentication
+ *
+ * The supported authentication types may vary from service to service. Each
+ * authentication type is implemented as an Authenticator for consumption by a service.
+ *
+ * classes:
+ *   AuthenticatorInterface: Implement this class to provide custom authentication schemes to services.
+ *   Authenticator: Extend this class to provide custom authentication schemes to services.
+ *   BasicAuthenticator: Authenticator for passing supplied basic authentication information to service endpoint.
+ *   BearerTokenAuthenticator: Authenticator for passing supplied bearer token to service endpoint.
+ *   CloudPakForDataAuthenticator: Authenticator for passing CP4D authentication information to service endpoint.
+ *   IAMAuthenticator: Authenticator for passing IAM authentication information to service endpoint.
+ *   NoAuthAuthenticator: Performs no authentication. Useful for testing purposes.
+ */
 export { AuthenticatorInterface } from './authenticator-interface';
@@ -18,0 +40,0 @@ export { Authenticator } from './authenticator';

auth/authenticators/index.js

@@ -32,2 +32,1 @@ "use strict";
 exports.TokenRequestBasedAuthenticator = token_request_based_authenticator_1.TokenRequestBasedAuthenticator;
-//# sourceMappingURL=index.js.map

auth/authenticators/no-auth-authenticator.d.ts

@@ -17,13 +17,11 @@ /**
 import { Authenticator } from './authenticator';
-import { AuthenticateOptions, AuthenticatorInterface } from './authenticator-interface';
-export declare class NoAuthAuthenticator extends Authenticator implements AuthenticatorInterface {
-    /**
-     * NoAuth Authenticator Class
-     *
-     * Provides a way to use a service without specifying credentials.
-     *
-     * @constructor
-     */
+import { AuthenticateOptions } from './authenticator-interface';
+/**
+ * NoAuthAuthenticator is a placeholder authenticator implementation which
+ * performs no authentication of outgoing REST API requests. It might be
+ * useful during development and testing.
+ */
+export declare class NoAuthAuthenticator extends Authenticator {
     constructor();
-    authenticate(options: AuthenticateOptions): Promise<void>;
+    authenticate(requestOptions: AuthenticateOptions): Promise<void>;
 }

auth/authenticators/no-auth-authenticator.js

@@ -32,15 +32,13 @@ "use strict";
 var authenticator_1 = require("./authenticator");
+/**
+ * NoAuthAuthenticator is a placeholder authenticator implementation which
+ * performs no authentication of outgoing REST API requests. It might be
+ * useful during development and testing.
+ */
 var NoAuthAuthenticator = /** @class */ (function (_super) {
     __extends(NoAuthAuthenticator, _super);
-    /**
-     * NoAuth Authenticator Class
-     *
-     * Provides a way to use a service without specifying credentials.
-     *
-     * @constructor
-     */
     function NoAuthAuthenticator() {
         return _super.call(this) || this;
     }
-    NoAuthAuthenticator.prototype.authenticate = function (options) {
+    NoAuthAuthenticator.prototype.authenticate = function (requestOptions) {
         // immediately proceed to request. it will probably fail
@@ -52,2 +50,1 @@ return Promise.resolve();
 exports.NoAuthAuthenticator = NoAuthAuthenticator;
-//# sourceMappingURL=no-auth-authenticator.js.map

auth/authenticators/token-request-based-authenticator.d.ts

@@ -20,6 +20,13 @@ /**
 import { Authenticator } from './authenticator';
-import { AuthenticateOptions, AuthenticatorInterface } from './authenticator-interface';
+import { AuthenticateOptions } from './authenticator-interface';
+/** Configuration options for token-based authentication. */
 export declare type BaseOptions = {
+    /** Headers to be sent with every outbound HTTP requests to token services. */
     headers?: OutgoingHttpHeaders;
+    /**
+     * A flag that indicates whether verification of the token server's SSL
+     * certificate should be disabled or not.
+     */
     disableSslVerification?: boolean;
+    /** Endpoint for HTTP token requests. */
     url?: string;
@@ -29,3 +36,14 @@ /** Allow additional request config parameters */
 };
-export declare class TokenRequestBasedAuthenticator extends Authenticator implements AuthenticatorInterface {
+/**
+ * Class for common functionality shared by token-request authenticators.
+ * [[TokenRequestBasedAuthenticator]]s use token managers to retrieve, store,
+ * and refresh tokens. Not intended to be used as stand-alone authenticator,
+ * but as parent class to authenticators that have their own token manager
+ * implementations.
+ *
+ * The tokens will be added as an Authorization headers in the form:
+ *
+ *      Authorization: Bearer <bearer-token>
+ */
+export declare class TokenRequestBasedAuthenticator extends Authenticator {
     protected tokenManager: JwtTokenManager;
@@ -36,25 +54,41 @@ protected url: string;
     /**
-     * Request Based Authenticator Class
+     * Create a new [[TokenRequestBasedAuthenticator]] instance with an internal [[JwtTokenManager]].
      *
-     * Handles authentication patterns that invoke requests for bearer tokens.
-     *
-     * @param {Object} options
-     * @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] to be sent with every
+     *   outbound HTTP requests to token services.
      */
     constructor(options: BaseOptions);
     /**
-     * Setter for the disableSslVerification property.
+     * Set the flag that indicates whether verification of the server's SSL
+     * certificate should be disabled or not.
      *
-     * @param {boolean} value - the new value for the disableSslVerification property
-     * @returns {void}
+     * @param {boolean} value A flag that indicates whether verification of the
+     *   token server's SSL certificate should be disabled or not.
      */
     setDisableSslVerification(value: boolean): void;
     /**
-     * Set a completely new set of headers.
+     * Set headers.
      *
-     * @param {OutgoingHttpHeaders} headers - the new set of headers as an object
-     * @returns {void}
+     * @param {object<string, string>} headers Default headers to be sent with
+     *   every Cloud Pak For Data token request. Overwrites previous default headers.
      */
     setHeaders(headers: OutgoingHttpHeaders): void;
-    authenticate(options: AuthenticateOptions): Promise<void | Error>;
+    /**
+     * Adds bearer token information to `request`. The bearer token information
+     * will be set in the Authorization property of`request.headers` in the form:
+     *
+     *     Authorization: Bearer <bearer-token>
+     *
+     * @param {object} requestOptions - The request to augment with authentication
+     *   information.
+     * @param {object.<string, string>} requestOptions.headers - The headers the
+     *   authentication information will be added too. Overrides default headers
+     *   where there's conflict.
+     */
+    authenticate(requestOptions: AuthenticateOptions): Promise<void | Error>;
 }

auth/authenticators/token-request-based-authenticator.js

@@ -34,11 +34,25 @@ "use strict";
 var authenticator_1 = require("./authenticator");
+/**
+ * Class for common functionality shared by token-request authenticators.
+ * [[TokenRequestBasedAuthenticator]]s use token managers to retrieve, store,
+ * and refresh tokens. Not intended to be used as stand-alone authenticator,
+ * but as parent class to authenticators that have their own token manager
+ * implementations.
+ *
+ * The tokens will be added as an Authorization headers in the form:
+ *
+ *      Authorization: Bearer <bearer-token>
+ */
 var TokenRequestBasedAuthenticator = /** @class */ (function (_super) {
     __extends(TokenRequestBasedAuthenticator, _super);
     /**
-     * Request Based Authenticator Class
+     * Create a new [[TokenRequestBasedAuthenticator]] instance with an internal [[JwtTokenManager]].
      *
-     * Handles authentication patterns that invoke requests for bearer tokens.
-     *
-     * @param {Object} options
-     * @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] to be sent with every
+     *   outbound HTTP requests to token services.
      */
@@ -51,4 +65,2 @@ function TokenRequestBasedAuthenticator(options) {
         _this.headers = options.headers || {};
-        // this class must be extended by a subclass - the JwtTokenManager
-        // will fail upon requesting a token
         _this.tokenManager = new token_managers_1.JwtTokenManager(options);
@@ -58,6 +70,7 @@ return _this;
     /**
-     * Setter for the disableSslVerification property.
+     * Set the flag that indicates whether verification of the server's SSL
+     * certificate should be disabled or not.
      *
-     * @param {boolean} value - the new value for the disableSslVerification property
-     * @returns {void}
+     * @param {boolean} value A flag that indicates whether verification of the
+     *   token server's SSL certificate should be disabled or not.
      */
@@ -71,6 +84,6 @@ TokenRequestBasedAuthenticator.prototype.setDisableSslVerification = function (value) {
     /**
-     * Set a completely new set of headers.
+     * Set headers.
      *
-     * @param {OutgoingHttpHeaders} headers - the new set of headers as an object
-     * @returns {void}
+     * @param {object<string, string>} headers Default headers to be sent with
+     *   every Cloud Pak For Data token request. Overwrites previous default headers.
      */
@@ -85,6 +98,18 @@ TokenRequestBasedAuthenticator.prototype.setHeaders = function (headers) {
     };
-    TokenRequestBasedAuthenticator.prototype.authenticate = function (options) {
+    /**
+     * Adds bearer token information to `request`. The bearer token information
+     * will be set in the Authorization property of`request.headers` in the form:
+     *
+     *     Authorization: Bearer <bearer-token>
+     *
+     * @param {object} requestOptions - The request to augment with authentication
+     *   information.
+     * @param {object.<string, string>} requestOptions.headers - The headers the
+     *   authentication information will be added too. Overrides default headers
+     *   where there's conflict.
+     */
+    TokenRequestBasedAuthenticator.prototype.authenticate = function (requestOptions) {
         return this.tokenManager.getToken().then(function (token) {
             var authHeader = { Authorization: "Bearer " + token };
-            options.headers = extend(true, {}, options.headers, authHeader);
+            requestOptions.headers = extend(true, {}, requestOptions.headers, authHeader);
             return;
@@ -96,2 +121,1 @@ });
 exports.TokenRequestBasedAuthenticator = TokenRequestBasedAuthenticator;
-//# sourceMappingURL=token-request-based-authenticator.js.map

auth/index.js

@@ -24,2 +24,1 @@ "use strict";
 __export(require("./utils"));
-//# sourceMappingURL=index.js.map

auth/token-managers/cp4d-token-manager.d.ts

@@ -17,5 +17,9 @@ /**
 import { JwtTokenManager, TokenManagerOptions } from './jwt-token-manager';
+/** Configuration options for CP4D token retrieval. */
 interface Options extends TokenManagerOptions {
+    /** The endpoint for CP4D token requests. */
     url: string;
+    /** The username portion of basic authentication. */
     username: string;
+    /** The password portion of basic authentication. */
     password: string;
@@ -35,2 +39,8 @@ }
 }
+/**
+ * Token Manager of CloudPak for data.
+ *
+ * The Token Manager performs basic auth with a username and password
+ * to acquire CP4D tokens.
+ */
 export declare class Cp4dTokenManager extends JwtTokenManager {
@@ -41,22 +51,18 @@ protected requiredOptions: string[];
     /**
-     * ICP Token Manager Service
+     * Create a new [[Cp4dTokenManager]] instance.
      *
-     * Retreives and stores ICP access tokens.
-     *
-     * @param {Object} options
-     * @param {String} options.username
-     * @param {String} options.password
-     * @param {String} options.accessToken - user-managed access token
-     * @param {String} options.url - URL for the CP4D cluster
-     * @param {Boolean} options.disableSslVerification - disable SSL verification for token request
+     * @param {object} options Configuration options.
+     * @param {string} options.username The username portion of basic authentication.
+     * @param {string} options.password The password portion of basic authentication.
+     * @param {string} options.url The endpoint for CP4D 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.
      * @constructor
      */
     constructor(options: Options);
-    /**
-     * Request an CP4D token using a basic auth header.
-     *
-     * @returns {Promise}
-     */
     protected requestToken(): Promise<any>;
 }
 export {};

auth/token-managers/cp4d-token-manager.js

@@ -34,15 +34,22 @@ "use strict";
 var jwt_token_manager_1 = require("./jwt-token-manager");
+/**
+ * Token Manager of CloudPak for data.
+ *
+ * The Token Manager performs basic auth with a username and password
+ * to acquire CP4D tokens.
+ */
 var Cp4dTokenManager = /** @class */ (function (_super) {
     __extends(Cp4dTokenManager, _super);
     /**
-     * ICP Token Manager Service
+     * Create a new [[Cp4dTokenManager]] instance.
      *
-     * Retreives and stores ICP access tokens.
-     *
-     * @param {Object} options
-     * @param {String} options.username
-     * @param {String} options.password
-     * @param {String} options.accessToken - user-managed access token
-     * @param {String} options.url - URL for the CP4D cluster
-     * @param {Boolean} options.disableSslVerification - disable SSL verification for token request
+     * @param {object} options Configuration options.
+     * @param {string} options.username The username portion of basic authentication.
+     * @param {string} options.password The password portion of basic authentication.
+     * @param {string} options.url The endpoint for CP4D 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.
      * @constructor
@@ -64,7 +71,2 @@ */
     }
-    /**
-     * Request an CP4D token using a basic auth header.
-     *
-     * @returns {Promise}
-     */
     Cp4dTokenManager.prototype.requestToken = function () {
@@ -88,2 +90,1 @@ // these cannot be overwritten
 exports.Cp4dTokenManager = Cp4dTokenManager;
-//# sourceMappingURL=cp4d-token-manager.js.map

auth/token-managers/iam-token-manager.d.ts

@@ -17,2 +17,3 @@ /**
 import { JwtTokenManager, TokenManagerOptions } from './jwt-token-manager';
+/** Configuration options for IAM token retrieval. */
 interface Options extends TokenManagerOptions {
@@ -23,9 +24,7 @@ apikey: string;
 }
-export interface IamTokenData {
-    access_token: string;
-    refresh_token: string;
-    token_type: string;
-    expires_in: number;
-    expiration: number;
-}
+/**
+ * The IAMTokenManager takes an api key and performs the necessary interactions with
+ * the IAM token service to obtain and store a suitable bearer token. Additionally, the IAMTokenManager
+ * will retrieve bearer tokens via basic auth using a supplied `clientId` and `clientSecret` pair.
+ */
 export declare class IamTokenManager extends JwtTokenManager {
@@ -37,10 +36,17 @@ protected requiredOptions: string[];
     /**
-     * IAM Token Manager Service
      *
-     * Retreives and stores IAM access tokens.
+     * Create a new [[IamTokenManager]] instance.
      *
-     * @param {Object} options
-     * @param {String} options.apikey
-     * @param {String} options.iamAccessToken
-     * @param {String} options.iamUrl - url of the iam api to retrieve tokens from
+     * @param {object} options Configuration options.
+     * @param {string} options.apikey The IAM api key.
+     * @param {string} [options.clientId] The `clientId` and `clientSecret` fields are used to form a "basic"
+     *   authorization header for IAM token requests.
+     * @param {string} [options.clientSecret] The `clientId` and `clientSecret` fields are used to form a "basic"
+     *   authorization header for IAM token requests.
+     * @param {string} [url='https://iam.cloud.ibm.com/identity/token'] The IAM endpoint for 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.
      * @constructor
@@ -50,3 +56,3 @@ */
     /**
-     * Set the IAM 'client_id' and 'client_secret' values.
+     * Set the IAM `clientId` and `clientSecret` values.
      * These values are used to compute the Authorization header used
@@ -57,4 +63,4 @@ * when retrieving the IAM access token.
      *
-     * @param {string} clientId - The client id
-     * @param {string} clientSecret - The client secret
+     * @param {string} clientId - The client id.
+     * @param {string} clientSecret - The client secret.
      * @returns {void}
@@ -61,0 +67,0 @@ */

auth/token-managers/iam-token-manager.js

@@ -49,13 +49,25 @@ "use strict";
 var CLIENT_ID_SECRET_WARNING = 'Warning: Client ID and Secret must BOTH be given, or the header will not be included.';
+/**
+ * The IAMTokenManager takes an api key and performs the necessary interactions with
+ * the IAM token service to obtain and store a suitable bearer token. Additionally, the IAMTokenManager
+ * will retrieve bearer tokens via basic auth using a supplied `clientId` and `clientSecret` pair.
+ */
 var IamTokenManager = /** @class */ (function (_super) {
     __extends(IamTokenManager, _super);
     /**
-     * IAM Token Manager Service
      *
-     * Retreives and stores IAM access tokens.
+     * Create a new [[IamTokenManager]] instance.
      *
-     * @param {Object} options
-     * @param {String} options.apikey
-     * @param {String} options.iamAccessToken
-     * @param {String} options.iamUrl - url of the iam api to retrieve tokens from
+     * @param {object} options Configuration options.
+     * @param {string} options.apikey The IAM api key.
+     * @param {string} [options.clientId] The `clientId` and `clientSecret` fields are used to form a "basic"
+     *   authorization header for IAM token requests.
+     * @param {string} [options.clientSecret] The `clientId` and `clientSecret` fields are used to form a "basic"
+     *   authorization header for IAM token requests.
+     * @param {string} [url='https://iam.cloud.ibm.com/identity/token'] The IAM endpoint for 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.
      * @constructor
@@ -82,3 +94,3 @@ */
     /**
-     * Set the IAM 'client_id' and 'client_secret' values.
+     * Set the IAM `clientId` and `clientSecret` values.
      * These values are used to compute the Authorization header used
@@ -89,4 +101,4 @@ * when retrieving the IAM access token.
      *
-     * @param {string} clientId - The client id
-     * @param {string} clientSecret - The client secret
+     * @param {string} clientId - The client id.
+     * @param {string} clientSecret - The client secret.
      * @returns {void}
@@ -134,2 +146,1 @@ */
 exports.IamTokenManager = IamTokenManager;
-//# sourceMappingURL=iam-token-manager.js.map

auth/token-managers/index.d.ts

@@ -16,4 +16,19 @@ /**
  */
+/**
+ * @module token-managers
+ * The ibm-cloud-sdk-core module supports the following types of token authentication:
+ *
+ * Identity and Access Management (IAM)
+ * Cloud Pak for Data
+ *
+ * The token managers sit inside of an authenticator and do the work to retrieve
+ * tokens where as the authenticators add these tokens to the actual request.
+ *
+ * classes:
+ *   IamTokenManager: Token Manager of CloudPak for data.
+ *   Cp4dTokenManager: Authenticator for passing IAM authentication information to service endpoint.
+ *   JwtTokenManager: A class for shared functionality for parsing, storing, and requesting JWT tokens.
+ */
 export { IamTokenManager } from './iam-token-manager';
 export { Cp4dTokenManager } from './cp4d-token-manager';
 export { JwtTokenManager } from './jwt-token-manager';

auth/token-managers/index.js

@@ -18,2 +18,17 @@ "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * @module token-managers
+ * The ibm-cloud-sdk-core module supports the following types of token authentication:
+ *
+ * Identity and Access Management (IAM)
+ * Cloud Pak for Data
+ *
+ * The token managers sit inside of an authenticator and do the work to retrieve
+ * tokens where as the authenticators add these tokens to the actual request.
+ *
+ * classes:
+ *   IamTokenManager: Token Manager of CloudPak for data.
+ *   Cp4dTokenManager: Authenticator for passing IAM authentication information to service endpoint.
+ *   JwtTokenManager: A class for shared functionality for parsing, storing, and requesting JWT tokens.
+ */
 var iam_token_manager_1 = require("./iam-token-manager");
@@ -25,2 +40,1 @@ exports.IamTokenManager = iam_token_manager_1.IamTokenManager;
 exports.JwtTokenManager = jwt_token_manager_1.JwtTokenManager;
-//# sourceMappingURL=index.js.map

auth/token-managers/jwt-token-manager.d.ts

@@ -19,5 +19,12 @@ /**
 import { RequestWrapper } from '../../lib/request-wrapper';
+/** Configuration options for JWT token retrieval. */
 export declare type TokenManagerOptions = {
+    /** The endpoint for token requests. */
     url?: string;
+    /** Headers to be sent with every service token request. */
     headers?: OutgoingHttpHeaders;
+    /**
+     * A flag that indicates whether verification of
+     *   the server's SSL certificate should be disabled or not.
+     */
     disableSslVerification?: boolean;
@@ -27,2 +34,8 @@ /** Allow additional request config parameters */
 };
+/**
+ * A class for shared functionality for parsing, storing, and requesting
+ * JWT tokens. Intended to be used as a parent to be extended for token
+ * request management. Child classes should implement `requestToken()`
+ * to retrieve the bearer token from intended sources.
+ */
 export declare class JwtTokenManager {
@@ -37,20 +50,17 @@ protected url: string;
     /**
-     * Token Manager Service
-     *
-     * Retreives and stores JSON web tokens.
-     *
-     * @param {Object} options
-     * @param {String} options.url - url of the api to retrieve tokens from
-     * @param {String} [options.accessToken] - user-managed access token
+     * 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.
      */
     constructor(options: TokenManagerOptions);
     /**
-     * This function returns a Promise that resolves with an access token, if successful.
-     * The source of the token is determined by the following logic:
-     * 1. If user provides their own managed access token, assume it is valid and send it
-     * 2. a) If this class is managing tokens and does not yet have one, make a request for one
-     *    b) If this class is managing tokens and the token has expired, request a new one
-     * 3. If this class is managing tokens and has a valid token stored, send it
-     *
+     * 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.
      */
@@ -61,3 +71,4 @@ getToken(): Promise<any>;
      *
-     * @param {boolean} value - the new value for the disableSslVerification property
+     * @param {boolean} value - the new value for the disableSslVerification
+     *   property
      * @returns {void}
@@ -64,0 +75,0 @@ */

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

@@ -25,12 +25,19 @@ "use strict";
 }
+/**
+ * A class for shared functionality for parsing, storing, and requesting
+ * JWT tokens. Intended to be used as a parent to be extended for token
+ * request management. Child classes should implement `requestToken()`
+ * to retrieve the bearer token from intended sources.
+ */
 var JwtTokenManager = /** @class */ (function () {
     /**
-     * Token Manager Service
-     *
-     * Retreives and stores JSON web tokens.
-     *
-     * @param {Object} options
-     * @param {String} options.url - url of the api to retrieve tokens from
-     * @param {String} [options.accessToken] - user-managed access token
+     * 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.
      */
@@ -52,9 +59,5 @@ function JwtTokenManager(options) {
     /**
-     * This function returns a Promise that resolves with an access token, if successful.
-     * The source of the token is determined by the following logic:
-     * 1. If user provides their own managed access token, assume it is valid and send it
-     * 2. a) If this class is managing tokens and does not yet have one, make a request for one
-     *    b) If this class is managing tokens and the token has expired, request a new one
-     * 3. If this class is managing tokens and has a valid token stored, send it
-     *
+     * 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.
      */
@@ -78,3 +81,4 @@ JwtTokenManager.prototype.getToken = function () {
      *
-     * @param {boolean} value - the new value for the disableSslVerification property
+     * @param {boolean} value - the new value for the disableSslVerification
+     *   property
      * @returns {void}
@@ -174,2 +178,1 @@ */
 exports.JwtTokenManager = JwtTokenManager;
-//# sourceMappingURL=jwt-token-manager.js.map

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

@@ -17,2 +17,13 @@ /**
 import { Authenticator } from '../authenticators';
+/**
+ * Look for external configuration of authenticator.
+ *
+ * Try to get authenticator from external sources, with the following priority:
+ * 1. Credentials file (ibm-credentials.env)
+ * 2. Environment variables
+ * 3. VCAP Services (Cloud Foundry)
+ *
+ * @param {string} serviceName The service name prefix.
+ *
+ */
 export declare function getAuthenticatorFromEnvironment(serviceName: string): Authenticator;

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

@@ -20,2 +20,13 @@ "use strict";
 var read_external_sources_1 = require("./read-external-sources");
+/**
+ * Look for external configuration of authenticator.
+ *
+ * Try to get authenticator from external sources, with the following priority:
+ * 1. Credentials file (ibm-credentials.env)
+ * 2. Environment variables
+ * 3. VCAP Services (Cloud Foundry)
+ *
+ * @param {string} serviceName The service name prefix.
+ *
+ */
 function getAuthenticatorFromEnvironment(serviceName) {
@@ -72,2 +83,1 @@ if (!serviceName) {
 exports.getAuthenticatorFromEnvironment = getAuthenticatorFromEnvironment;
-//# sourceMappingURL=get-authenticator-from-environment.js.map

auth/utils/helpers.d.ts

@@ -32,2 +32,6 @@ /**
 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.
+ */
 export declare function validateInput(options: any, requiredOptions: string[]): void;

auth/utils/helpers.js

@@ -59,2 +59,6 @@ "use strict";
 exports.checkCredentials = checkCredentials;
+/**
+ * @param {object} options - A configuration options object.
+ * @param {string[]} requiredOptions - The list of properties that must be specified.
+ */
 function validateInput(options, requiredOptions) {
@@ -75,2 +79,1 @@ // check for required params
 exports.validateInput = validateInput;
-//# sourceMappingURL=helpers.js.map

auth/utils/index.d.ts

@@ -16,2 +16,10 @@ /**
  */
+/**
+ * @module utils
+ * Helper functions used by generated SDKs.
+ *
+ * functions:
+ *   getAuthenticatorFromEnvironment: Get authenticator from external sources.
+ *   readExternalSources: Get config object from external sources.
+ */
 export * from './helpers';
@@ -18,0 +26,0 @@ export * from './read-credentials-file';

auth/utils/index.js

@@ -21,2 +21,10 @@ "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * @module utils
+ * Helper functions used by generated SDKs.
+ *
+ * functions:
+ *   getAuthenticatorFromEnvironment: Get authenticator from external sources.
+ *   readExternalSources: Get config object from external sources.
+ */
 __export(require("./helpers"));
@@ -28,2 +36,1 @@ __export(require("./read-credentials-file"));
 exports.readExternalSources = read_external_sources_1.readExternalSources;
-//# sourceMappingURL=index.js.map

auth/utils/read-credentials-file.browser.js

@@ -9,2 +9,1 @@ "use strict";
 ;
-//# sourceMappingURL=read-credentials-file.browser.js.map

auth/utils/read-credentials-file.d.ts

@@ -0,3 +1,7 @@
+/**
+ * Return a config object based on a credentials file. Credentials files can
+ * be specified filepath via the environment variable: `IBM_CREDENTIALS_FILE`.
+ */
 export declare function readCredentialsFile(): any;
 export declare function fileExistsAtPath(filepath: any): boolean;
 export declare function constructFilepath(filepath: any): string;

auth/utils/read-credentials-file.js

@@ -9,2 +9,6 @@ "use strict";
 var filename = 'ibm-credentials.env';
+/**
+ * Return a config object based on a credentials file. Credentials files can
+ * be specified filepath via the environment variable: `IBM_CREDENTIALS_FILE`.
+ */
 function readCredentialsFile() {
@@ -59,2 +63,1 @@ if (!fs.existsSync) {
 exports.constructFilepath = constructFilepath;
-//# sourceMappingURL=read-credentials-file.js.map

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

@@ -16,2 +16,11 @@ /**
  */
+/**
+ * Read properties stored in external sources like Environment Variables,
+ * the credentials file, VCAP services, etc. and return them as an
+ * object. The keys of this object will have the service name prefix removed
+ * and will be converted to lower camel case.
+ *
+ * Only one source will be used at a time.
+ * @param {string} serviceName The service name prefix.
+ */
 export declare function readExternalSources(serviceName: string): any;

auth/utils/read-external-sources.js

@@ -20,5 +20,5 @@ "use strict";
 var isEmpty = require("lodash.isempty");
-var vcapServices = require("vcap_services");
+var logger_1 = require("../../lib/logger");
 var read_credentials_file_1 = require("./read-credentials-file");
-/*
+/**
  * Read properties stored in external sources like Environment Variables,
@@ -30,2 +30,3 @@ * the credentials file, VCAP services, etc. and return them as an
  * Only one source will be used at a time.
+ * @param {string} serviceName The service name prefix.
  */
@@ -51,3 +52,3 @@ function readExternalSources(serviceName) {
     if (isEmpty(properties)) {
-        properties = getCredentialsFromCloud(serviceName);
+        properties = getPropertiesFromVCAP(serviceName);
     }
@@ -64,3 +65,3 @@ return properties;
  *
- * @param {Object} envObj - the object containing the credentials keyed by environment variables
+ * @param {object} envObj - the object containing the credentials keyed by environment variables
  * @returns {Credentials}
@@ -90,5 +91,52 @@ */
  *
+ * The function will first look for a service entry whose "name" field matches
+ * the serviceKey value. If found, return its credentials.
+ *
+ * If no match against the service entry's "name" field is found, then find the
+ * service list with a key matching the serviceKey value. If found, return the
+ * credentials of the first service in the service list.
  */
-function getCredentialsFromCloud(serviceName) {
-    var credentials = vcapServices.getCredentials(serviceName);
+function getVCAPCredentialsForService(name) {
+    if (process.env.VCAP_SERVICES) {
+        var services = JSON.parse(process.env.VCAP_SERVICES);
+        for (var _i = 0, _a = Object.keys(services); _i < _a.length; _i++) {
+            var serviceName = _a[_i];
+            for (var _b = 0, _c = services[serviceName]; _b < _c.length; _b++) {
+                var instance = _c[_b];
+                if (instance['name'] === name) {
+                    if (instance.hasOwnProperty('credentials')) {
+                        return instance.credentials;
+                    }
+                    else {
+                        logger_1.default.debug('no data read from VCAP_SERVICES');
+                        return {};
+                    }
+                }
+            }
+        }
+        for (var _d = 0, _e = Object.keys(services); _d < _e.length; _d++) {
+            var serviceName = _e[_d];
+            if (serviceName === name) {
+                if (services[serviceName].length > 0) {
+                    if (services[serviceName][0].hasOwnProperty('credentials')) {
+                        return services[serviceName][0].credentials;
+                    }
+                    else {
+                        logger_1.default.debug('no data read from VCAP_SERVICES');
+                        return {};
+                    }
+                    return services[serviceName][0].credentials || {};
+                }
+                else {
+                    logger_1.default.debug('no data read from VCAP_SERVICES');
+                    return {};
+                }
+            }
+        }
+    }
+    logger_1.default.debug('no data read from VCAP_SERVICES');
+    return {};
+}
+function getPropertiesFromVCAP(serviceName) {
+    var credentials = getVCAPCredentialsForService(serviceName);
     // infer authentication type from credentials in a simple manner
@@ -101,2 +149,1 @@ // iam is used as the default later
 }
-//# sourceMappingURL=read-external-sources.js.map

CHANGELOG.md

@@ -0,1 +1,27 @@
+# [2.0.0](https://github.com/IBM/node-sdk-core/compare/v1.3.0...v2.0.0) (2019-11-19)
+
+
+### Features
+
+* changes to node-sdk-core to work with service factory feature ([#72](https://github.com/IBM/node-sdk-core/issues/72)) ([cde4cd6](https://github.com/IBM/node-sdk-core/commit/cde4cd68e5a9910fb4f8abacd90a5a3b44b3f8f5))
+
+
+### BREAKING CHANGES
+
+* The `BaseService` will no longer look for configurations externally by default. A new factory method is provided to create an instance from external configuration.
+
+* feat: changes to node-sdk-core to work with service factory feature
+
+* `BaseService` constructor will no longer call `configureService`. 
+
+* updated test to reflect base service constructor does not call configureService
+
+* added test for getting credentials from vcap
+
+* removed `name` and `serviceVersion` because they are not referenced anymore
+
+* added comment for vcap parsing function. removed vcap_services dependency
+
+* added debug messages for when returning empty credential
+
 # [1.3.0](https://github.com/IBM/node-sdk-core/compare/v1.2.0...v1.3.0) (2019-10-22)
@@ -2,0 +28,0 @@

index.js

@@ -34,2 +34,1 @@ "use strict";
 __export(require("./test/utils"));
-//# sourceMappingURL=index.js.map

lib/base-service.d.ts

@@ -19,2 +19,5 @@ /**
 import { AuthenticatorInterface } from '../auth';
+/**
+ * Configuration values for a service.
+ */
 export interface UserOptions {
@@ -36,9 +39,17 @@ /** The Authenticator object used to authenticate requests to the service */
 }
+/**
+ * Additional service configuration.
+ */
 export interface BaseServiceOptions extends UserOptions {
+    /** Querystring to be sent with every request. If not a string will be stringified. */
     qs: any;
 }
+/**
+ * Common functionality shared by generated service classes.
+ *
+ * The base service authenticates requests via its authenticator, and sends
+ * them to the service endpoint.
+ */
 export declare class BaseService {
     static URL: string;
-    name: string;
-    serviceVersion: string;
     protected baseOptions: BaseServiceOptions;
@@ -48,11 +59,13 @@ private authenticator;
     /**
-     * Internal base class that other services inherit from
-     * @param {UserOptions} options
-     * @param {OutgoingHttpHeaders} [options.headers]
-     * @param {string} [options.url] - override default service base url
-     * @private
-     * @abstract
-     * @constructor
-     * @throws {Error}
-     * @returns {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.
+     *   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
+     *   disabled or not.
      */
@@ -69,3 +82,3 @@ constructor(userOptions: UserOptions);
      *
-     * @param {string} the base URL for the service
+     * @param {string} url The base URL for the service.
      */
@@ -76,4 +89,4 @@ setServiceUrl(url: string): void;
      *
-     * @param {string} the name of the service. Will be used to read from external
-     * configuration
+     * @param {string} serviceName The name of the service. Will be used to read from external
+     * configuration.
      */
@@ -84,10 +97,10 @@ protected configureService(serviceName: string): void;
      *
-     * @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 serviceUr
-     * @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
+     * @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:
@@ -99,4 +112,4 @@ * - string: no special processing -- the value is sent as is
      * @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
+     * @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>}
@@ -103,0 +116,0 @@ */

lib/base-service.js

@@ -23,13 +23,21 @@ "use strict";
 var request_wrapper_1 = require("./request-wrapper");
+/**
+ * Common functionality shared by generated service classes.
+ *
+ * The base service authenticates requests via its authenticator, and sends
+ * them to the service endpoint.
+ */
 var BaseService = /** @class */ (function () {
     /**
-     * Internal base class that other services inherit from
-     * @param {UserOptions} options
-     * @param {OutgoingHttpHeaders} [options.headers]
-     * @param {string} [options.url] - override default service base url
-     * @private
-     * @abstract
-     * @constructor
-     * @throws {Error}
-     * @returns {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.
+     *   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
+     *   disabled or not.
      */
@@ -70,4 +78,2 @@ function BaseService(userOptions) {
         this.authenticator = options.authenticator;
-        // temp: call the configureService method to ensure compatibility
-        this.configureService(this.name);
     }
@@ -85,3 +91,3 @@ /**
      *
-     * @param {string} the base URL for the service
+     * @param {string} url The base URL for the service.
      */
@@ -94,4 +100,4 @@ BaseService.prototype.setServiceUrl = function (url) {
      *
-     * @param {string} the name of the service. Will be used to read from external
-     * configuration
+     * @param {string} serviceName The name of the service. Will be used to read from external
+     * configuration.
      */
@@ -111,10 +117,10 @@ BaseService.prototype.configureService = function (serviceName) {
      *
-     * @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 serviceUr
-     * @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
+     * @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:
@@ -126,4 +132,4 @@ * - string: no special processing -- the value is sent as is
      * @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
+     * @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>}
@@ -161,2 +167,1 @@ */
 exports.BaseService = BaseService;
-//# sourceMappingURL=base-service.js.map

lib/content-type.js

@@ -28,4 +28,4 @@ "use strict";
  *
- * @param {Buffer} buffer with at least the first 4 bytes of the file
- * @return {String|undefined} - the contentType of undefined
+ * @param {Buffer} buffer With at least the first 4 bytes of the file
+ * @return {String|undefined} The contentType or undefined
  */
@@ -46,3 +46,3 @@ var fromHeader = function (buffer) {
  *
- * @param {String|ReadableStream|FileObject|Buffer|File} file - string filename or url, or binary File/Blob object
+ * @param {String|ReadableStream|FileObject|Buffer|File} file String filename or url, or binary File/Blob object.
  * @return {String|undefined}
@@ -58,2 +58,1 @@ */
 };
-//# sourceMappingURL=content-type.js.map

lib/helper.d.ts

@@ -74,7 +74,7 @@ /**
 /**
- * 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
+ * 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}
@@ -84,7 +84,7 @@ */
 /**
- * this function converts an object's keys to lower case
+ * 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
+ * @param {Object} obj The object to convert the keys of.
  * @returns {Object}
  */
 export declare function toLowerKeys(obj: Object): Object;

lib/helper.js

@@ -139,7 +139,7 @@ "use strict";
 /**
- * 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
+ * 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}
@@ -188,5 +188,5 @@ */
 /**
- * this function converts an object's keys to lower case
+ * 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
+ * @param {Object} obj The object to convert the keys of.
  * @returns {Object}
@@ -207,2 +207,1 @@ */
 exports.toLowerKeys = toLowerKeys;
-//# sourceMappingURL=helper.js.map

lib/logger.js

@@ -33,2 +33,1 @@ "use strict";
 };
-//# sourceMappingURL=logger.js.map

lib/querystring.js

@@ -10,3 +10,3 @@ "use strict";
  *
- * @param {Object} queryParams
+ * @param {object<string, object>} queryParams
  * @return {String}
@@ -28,2 +28,1 @@ */
 };
-//# sourceMappingURL=querystring.js.map

lib/request-wrapper.js

@@ -349,2 +349,1 @@ "use strict";
 }
-//# sourceMappingURL=request-wrapper.js.map

lib/stream-to-promise.d.ts

@@ -7,5 +7,5 @@ /// <reference types="node" />
  *
- * @param {Stream} [stream] optional stream param for when not bound to an existing stream instance
+ * @param {Stream} stream Optional stream param for when not bound to an existing stream instance.
  * @return {Promise}
  */
 export declare function streamToPromise(stream: Stream): Promise<any>;

lib/stream-to-promise.js

@@ -7,3 +7,3 @@ "use strict";
  *
- * @param {Stream} [stream] optional stream param for when not bound to an existing stream instance
+ * @param {Stream} stream Optional stream param for when not bound to an existing stream instance.
  * @return {Promise}
@@ -28,2 +28,1 @@ */
 exports.streamToPromise = streamToPromise;
-//# sourceMappingURL=stream-to-promise.js.map

package.json

 {
   "name": "ibm-cloud-sdk-core",
-  "version": "1.3.0",
+  "version": "2.0.0",
   "description": "Core functionality to support SDKs generated with IBM's OpenAPI 3 SDK Generator.",
-  "main": "./index",
+  "main": "index",
   "repository": {
@@ -31,24 +31,2 @@ "type": "git",
   },
-  "devDependencies": {
-    "@commitlint/cli": "^8.2.0",
-    "@commitlint/config-conventional": "^7.0.1",
-    "@semantic-release/changelog": "^3.0.0",
-    "@semantic-release/git": "^7.0.1",
-    "codecov": "~3.0.2",
-    "dependency-lint": "~5.0.1",
-    "eslint": "~5.0.0",
-    "eslint-config-google": "~0.9.1",
-    "eslint-config-prettier": "~2.9.0",
-    "eslint-plugin-node": "~6.0.1",
-    "eslint-plugin-prettier": "~2.6.1",
-    "jest": "^24.6.0",
-    "object.assign": "~4.1.0",
-    "prettier": "~1.13.5",
-    "semantic-release": "^15.13.24",
-    "tslint": "~5.10.0",
-    "tslint-config-prettier": "~1.13.0",
-    "tslint-eslint-rules": "^5.4.0",
-    "typedoc": "^0.15.0",
-    "typescript": "^3.4.5"
-  },
   "dependencies": {
@@ -72,4 +50,3 @@ "@types/extend": "~3.0.0",
     "object.pick": "~1.3.0",
-    "semver": "^6.2.0",
-    "vcap_services": "~0.3.4"
+    "semver": "^6.2.0"
   },
@@ -97,3 +74,3 @@ "browser": {
     "build": "tsc",
-    "prepare": "npm run build"
+    "postversion": "tsc-publish --no-checks --dry-run"
   },
@@ -105,2 +82,2 @@ "jest": {
   }
-}
+}

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Environment variable access

Supply chain risk

Package accesses environment variables, which may be a sign of credential stuffing or data theft.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Dependency count

18

decreased by-5.26%

Dev dependency count

0

decreased by-100%

Lines of code

3676

increased by13.14%

Worsened metrics

Total package byte prevSize

190918

decreased by-10.56%

Number of package files

64

decreased by-34.02%

Number of low supply chain risk alerts

8

increased by33.33%

Dependency changes

• - Removedvcap_services@~0.3.4

• - Removedvcap_services@0.3.4(transitive)