ibm-cloud-sdk-core 5.0.2 → 5.1.1

package/ibm-cloud-sdk-core.d.ts

@@ -7,24 +7,21 @@ import { OutgoingHttpHeaders } from 'http';
 import { Stream } from 'stream';
 
 /**
- * Checks for at least one of two elements being defined.
+ * Checks for at least one of the given elements being defined.
  *
- * @param a - the first object
- * @param b - the second object
- * @returns true if a or b is defined; false if both are undefined
+ * @param args - The spread of arguments to check
+ * @returns true if one or more are defined; false if all are undefined
  */
-export declare function atLeastOne(a: any, b: any): boolean;
+export declare function atLeastOne(...args: any): boolean;
 
 /**
- * Verifies that both properties are not specified.
+ * Verifies that no more than one of the given elements are defined.
+ * Returns true if one or none are defined, and false otherwise.
  *
- * @param a - The first object
- * @param b - The second object
- *
- * @returns  false if a and b are both defined, true otherwise
-
+ * @param args - The spread of arguments to check
+ * @returns  false if more than one elements are defined, true otherwise
  */
-export declare function atMostOne(a: any, b: any): boolean;
+export declare function atMostOne(...args: any): boolean;
 
 /**
  * The request object containing the headers property that
@@ -49,6 +46,7 @@ export declare class Authenticator implements AuthenticatorInterface {
     static AUTHTYPE_BASIC: string;
     static AUTHTYPE_BEARERTOKEN: string;
     static AUTHTYPE_IAM: string;
+    static AUTHTYPE_IAM_ASSUME: string;
     static AUTHTYPE_CONTAINER: string;
     static AUTHTYPE_CP4D: string;
     static AUTHTYPE_NOAUTH: string;
@@ -384,7 +382,7 @@ export declare class CloudPakForDataAuthenticator extends TokenRequestBasedAuthe
 }
 
 /**
- * (C) Copyright IBM Corp. 2019, 2022.
+ * (C) Copyright IBM Corp. 2019, 2024.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -478,6 +476,12 @@ export declare class ContainerAuthenticator extends IamRequestBasedAuthenticator
      * @returns a string that indicates the authenticator's type
      */
     authenticationType(): string;
+    /**
+     * Return the most recently stored refresh token.
+     *
+     * @returns the refresh token string
+     */
+    getRefreshToken(): string;
 }
 
 /**
@@ -525,6 +529,12 @@ export declare class ContainerTokenManager extends IamRequestBasedTokenManager {
      * @param iamProfileId - the ID of the IAM trusted profile
      */
     setIamProfileId(iamProfileId: string): void;
+    /**
+     * Returns the most recently stored refresh token.
+     *
+     * @returns the refresh token
+     */
+    getRefreshToken(): string;
     /**
      * Request an IAM token using a compute resource token.
      */
@@ -687,6 +697,126 @@ export declare function getNewLogger(moduleName: string): SDKLogger;
  */
 export declare function getQueryParam(urlStr: string, param: string): string;
 
+/**
+ * The IamAssumeAuthenticator obtains an IAM access token using the IAM "get-token"
+ * operation's "assume" grant type. The authenticator obtains an initial IAM access
+ * token from a user-supplied apikey, then exchanges this initial IAM access token
+ * for another IAM access token that has "assumed the identity" of the specified
+ * trusted profile.
+ *
+ * The bearer token will be sent as an Authorization header in the form:
+ *
+ *      Authorization: Bearer \<bearer-token\>
+ */
+export declare class IamAssumeAuthenticator extends IamRequestBasedAuthenticatorImmutable {
+    protected tokenManager: IamAssumeTokenManager;
+    /**
+     *
+     * Create a new IamAssumeAuthenticator instance.
+     *
+     * @param options - Configuration options for IAM authentication.
+     * This should be an object containing these fields:
+     * - apikey: (required) the IAM api key for initial token request
+     * - iamProfileId: (optional) the ID of the trusted profile to use
+     * - iamProfileCrn: (optional) the CRN of the trusted profile to use
+     * - iamProfileName: (optional) the name of the trusted profile to use (must be specified with iamAccountId)
+     * - iamAccountId: (optional) the ID of the account the trusted profile is in (must be specified with iamProfileName)
+     * - url: (optional) the endpoint URL for the token service
+     * - disableSslVerification: (optional) a flag that indicates whether verification of the token server's SSL certificate
+     * should be disabled or not
+     * - headers: (optional) a set of HTTP headers to be sent with each request to the token service
+     * - clientId: (optional) the "clientId" and "clientSecret" fields are used to form a Basic
+     * Authorization header to be included in each request to the token service
+     * - clientSecret: (optional) the "clientId" and "clientSecret" fields are used to form a Basic
+     * Authorization header to be included in each request to the token service
+     * - scope: (optional) the "scope" parameter to use when fetching the bearer token from the token service
+     *
+     * @throws Error: the configuration options are not valid.
+     */
+    constructor(options: Options_14);
+    /**
+     * Returns the authenticator's type ('iamAssume').
+     *
+     * @returns a string that indicates the authenticator's type
+     */
+    authenticationType(): string;
+}
+
+/**
+ * The IamAssumeTokenManager takes an api key, along with trusted profile information, and performs
+ * the necessary interactions with the IAM token service to obtain and store a suitable bearer token
+ * that "assumes" the identify of the trusted profile.
+ */
+export declare class IamAssumeTokenManager extends IamRequestBasedTokenManager {
+    protected requiredOptions: string[];
+    private iamProfileId;
+    private iamProfileCrn;
+    private iamProfileName;
+    private iamAccountId;
+    private iamDelegate;
+    /**
+     *
+     * Create a new IamAssumeTokenManager instance.
+     *
+     * @param options - Configuration options.
+     * This should be an object containing these fields:
+     * - apikey: (required) the IAM api key
+     * - iamProfileId: (optional) the ID of the trusted profile to use
+     * - iamProfileCrn: (optional) the CRN of the trusted profile to use
+     * - iamProfileName: (optional) the name of the trusted profile to use (must be specified with iamAccountId)
+     * - iamAccountId: (optional) the ID of the account the trusted profile is in (must be specified with iamProfileName)
+     * - url: (optional) the endpoint URL for the IAM token service (default value: "https://iam.cloud.ibm.com")
+     * - disableSslVerification: (optional) a flag that indicates whether verification of the token server's SSL certificate
+     * should be disabled or not
+     * - headers: (optional) a set of HTTP headers to be sent with each request to the token service
+     * - clientId: (optional) the "clientId" and "clientSecret" fields are used to form a Basic
+     * Authorization header to be included in each request to the token service
+     * - clientSecret: (optional) the "clientId" and "clientSecret" fields are used to form a Basic
+     * Authorization header to be included in each request to the token service
+     * - scope: (optional) the "scope" parameter to use when fetching the bearer token from the token service
+     *
+     * @throws Error: the configuration options are not valid.
+     */
+    constructor(options: Options_13);
+    /**
+     * Request an IAM token using a standard access token and a trusted profile.
+     */
+    protected requestToken(): Promise<any>;
+    /**
+     * Extend this method from the parent class to erase the refresh token from
+     * the class - we do not want to expose it for IAM Assume authentication.
+     *
+     * @param tokenResponse - the response object from JWT service request
+     */
+    protected saveTokenInfo(tokenResponse: any): void;
+    /**
+     * Sets the IAM "scope" value.
+     * This value is sent as the "scope" form parameter in the IAM delegate request.
+     *
+     * @param scope - a space-separated string that contains one or more scope names
+     */
+    setScope(scope: string): void;
+    /**
+     * Sets the IAM "clientId" and "clientSecret" values for the IAM delegate.
+     *
+     * @param clientId - the client id.
+     * @param clientSecret - the client secret.
+     */
+    setClientIdAndSecret(clientId: string, clientSecret: string): void;
+    /**
+     * Sets the "disableSslVerification" property for the IAM delegate.
+     *
+     * @param value - the new value for the disableSslVerification property
+     */
+    setDisableSslVerification(value: boolean): void;
+    /**
+     * Sets the headers to be included in the IAM delegate's requests.
+     *
+     * @param headers - the set of headers to send with each request to the token server
+     */
+    setHeaders(headers: OutgoingHttpHeaders): void;
+}
+
 /**
  * The IamAuthenticator will use the user-supplied `apikey`
  * value to obtain a bearer token from a token server.  When the bearer token
@@ -728,6 +858,12 @@ export declare class IamAuthenticator extends IamRequestBasedAuthenticator {
      * @returns a string that indicates the authenticator's type
      */
     authenticationType(): string;
+    /**
+     * Return the most recently stored refresh token.
+     *
+     * @returns the refresh token string
+     */
+    getRefreshToken(): string;
 }
 
 /**
@@ -735,14 +871,49 @@ export declare class IamAuthenticator extends IamRequestBasedAuthenticator {
  * for authenticators that interact with the IAM token service. This authenticator
  * is not meant for use on its own.
  */
-export declare class IamRequestBasedAuthenticator extends TokenRequestBasedAuthenticator {
+export declare class IamRequestBasedAuthenticator extends IamRequestBasedAuthenticatorImmutable {
+    /**
+     * Setter for the mutually inclusive "clientId" and the "clientSecret" fields.
+     * @param clientId - the "clientId" value used to form a Basic Authorization header for IAM token requests
+     * @param clientSecret - the "clientSecret" value used to form a Basic Authorization header for IAM token requests
+     */
+    setClientIdAndSecret(clientId: string, clientSecret: string): void;
+    /**
+     * Setter for the "scope" parameter to use when fetching the bearer token from the IAM token server.
+     * @param scope - (optional) a space-separated string that specifies one or more scopes to be
+     * associated with IAM token requests
+     */
+    setScope(scope: string): void;
+    /**
+     * Set the flag that indicates whether verification of the server's SSL
+     * certificate should be disabled or not.
+     *
+     * @param value - a flag that indicates whether verification of the
+     *   token server's SSL certificate should be disabled or not.
+     */
+    setDisableSslVerification(value: boolean): void;
+    /**
+     * Set headers.
+     *
+     * @param headers - a set of HTTP headers to be sent with each outbound token server request.
+     * Overwrites previous default headers.
+     */
+    setHeaders(headers: OutgoingHttpHeaders): void;
+}
+
+/**
+ * The IamRequestBasedAuthenticatorImmutable provides shared configuration and functionality
+ * for authenticators that interact with the IAM token service. This authenticator
+ * is not meant for use on its own.
+ */
+declare class IamRequestBasedAuthenticatorImmutable extends TokenRequestBasedAuthenticatorImmutable {
     protected tokenManager: IamRequestBasedTokenManager;
     protected clientId: string;
     protected clientSecret: string;
     protected scope: string;
     /**
      *
-     * Create a new IamRequestBasedAuthenticator instance.
+     * Create a new IamRequestBasedAuthenticatorImmutable instance.
      *
      * @param options - Configuration options for IAM authentication.
      * This should be an object containing these fields:
@@ -759,24 +930,6 @@ export declare class IamRequestBasedAuthenticator extends TokenRequestBasedAuthe
      * @throws Error: the configuration options are not valid.
      */
     constructor(options: IamRequestOptions_2);
-    /**
-     * Setter for the mutually inclusive "clientId" and the "clientSecret" fields.
-     * @param clientId - the "clientId" value used to form a Basic Authorization header for IAM token requests
-     * @param clientSecret - the "clientSecret" value used to form a Basic Authorization header for IAM token requests
-     */
-    setClientIdAndSecret(clientId: string, clientSecret: string): void;
-    /**
-     * Setter for the "scope" parameter to use when fetching the bearer token from the IAM token server.
-     * @param scope - (optional) a space-separated string that specifies one or more scopes to be
-     * associated with IAM token requests
-     */
-    setScope(scope: string): void;
-    /**
-     * Return the most recently stored refresh token.
-     *
-     * @returns the refresh token string
-     */
-    getRefreshToken(): string;
 }
 
 /**
@@ -787,9 +940,9 @@ export declare class IamRequestBasedAuthenticator extends TokenRequestBasedAuthe
  * class be extended with specific implementations.
  */
 export declare class IamRequestBasedTokenManager extends JwtTokenManager {
-    private clientId;
-    private clientSecret;
-    private scope;
+    protected clientId: string;
+    protected clientSecret: string;
+    protected scope: string;
     protected refreshToken: string;
     protected formData: any;
     /**
@@ -829,12 +982,6 @@ export declare class IamRequestBasedTokenManager extends JwtTokenManager {
      * @param clientSecret - the client secret.
      */
     setClientIdAndSecret(clientId: string, clientSecret: string): void;
-    /**
-     * Returns the most recently stored refresh token.
-     *
-     * @returns the refresh token
-     */
-    getRefreshToken(): string;
     /**
      * Extend this method from the parent class to extract the refresh token from
      * the request and save it.
@@ -886,8 +1033,8 @@ declare interface IamRequestOptions_2 extends BaseOptions {
 }
 
 /**
- * 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
+ * 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 IamRequestBasedTokenManager {
@@ -913,6 +1060,12 @@ export declare class IamTokenManager extends IamRequestBasedTokenManager {
      * @throws Error: the configuration options are not valid.
      */
     constructor(options: Options_5);
+    /**
+     * Returns the most recently stored refresh token.
+     *
+     * @returns the refresh token
+     */
+    getRefreshToken(): string;
 }
 
 export declare function isEmptyObject(obj: any): boolean;
@@ -1049,16 +1202,14 @@ export declare class NoAuthAuthenticator extends Authenticator {
 }
 
 /**
- * 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.
+ * Checks that exactly one of the arguments provided is defined.
+ * Returns true if one argument is defined. Returns false if no
+ * argument are defined or if 2 or more are defined.
  *
- * @param a - The first object
- * @param b - The second object
- * @returns true if and only if exactly one of a or b is defined
+ * @param args - The spread of arguments to check
+ * @returns true if and only if exactly one argument is defined
  */
-export declare function onlyOne(a: any, b: any): boolean;
+export declare function onlyOne(...args: any): boolean;
 
 /** Configuration options for basic authentication. */
 declare type Options = {
@@ -1094,6 +1245,37 @@ declare interface Options_12 extends BaseOptions {
     url: string;
 }
 
+/** Configuration options for IAM Assume token retrieval. */
+declare interface Options_13 extends IamRequestOptions {
+    apikey: string;
+    iamProfileId?: string;
+    iamProfileCrn?: string;
+    iamProfileName?: string;
+    iamAccountId?: string;
+}
+
+/** Configuration options for IAM Assume authentication. */
+declare interface Options_14 extends IamRequestOptions_2 {
+    /** The IAM api key */
+    apikey: string;
+    /**
+     * Specify exactly one of [iamProfileId, iamProfileCrn, or iamProfileName] to
+     * identify the trusted profile whose identity should be used. If iamProfileId
+     * or iamProfileCrn is used, the trusted profile must exist in the same account.
+     * If and only if iamProfileName is used, then iamAccountId must also be
+     * specified to indicate the account that contains the trusted profile.
+     */
+    iamProfileId?: string;
+    iamProfileCrn?: string;
+    iamProfileName?: string;
+    /**
+     * If and only if iamProfileName is used to specify the trusted profile, then
+     * iamAccountId must also be specified to indicate the account that contains
+     * the trusted profile.
+     */
+    iamAccountId?: string;
+}
+
 /** Configuration options for bearer authentication. */
 declare type Options_2 = {
     /** The bearer token to be added to requests. */
@@ -1446,22 +1628,7 @@ export declare type TokenManagerOptions = {
  *
  *      Authorization: Bearer \<bearer-token\>
  */
-export declare class TokenRequestBasedAuthenticator extends Authenticator {
-    protected tokenManager: JwtTokenManager;
-    protected url: string;
-    protected headers: OutgoingHttpHeaders;
-    protected disableSslVerification: boolean;
-    /**
-     * Create a new TokenRequestBasedAuthenticator instance with an internal JwtTokenManager.
-     *
-     * @param options - Configuration options.
-     * This should be an object containing these fields:
-     * - url: (optional) the endpoint URL for the token service
-     * - disableSslVerification: (optional) a flag that indicates whether verification of the token server's SSL certificate
-     * should be disabled or not
-     * - headers: (optional) a set of HTTP headers to be sent with each request to the token service
-     */
-    constructor(options: BaseOptions);
+export declare class TokenRequestBasedAuthenticator extends TokenRequestBasedAuthenticatorImmutable {
     /**
      * Set the flag that indicates whether verification of the server's SSL
      * certificate should be disabled or not.
@@ -1477,6 +1644,35 @@ export declare class TokenRequestBasedAuthenticator extends Authenticator {
      * Overwrites previous default headers.
      */
     setHeaders(headers: OutgoingHttpHeaders): void;
+}
+
+/**
+ * Class for common functionality shared by token-request authenticators.
+ * Token-request authenticators use token managers to retrieve, store,
+ * and refresh tokens. Not intended to be used as stand-alone authenticator,
+ * but as base class to authenticators that have their own token manager
+ * implementations.
+ *
+ * The token will be added as an Authorization header in the form:
+ *
+ *      Authorization: Bearer \<bearer-token\>
+ */
+declare class TokenRequestBasedAuthenticatorImmutable extends Authenticator {
+    protected tokenManager: JwtTokenManager;
+    protected url: string;
+    protected headers: OutgoingHttpHeaders;
+    protected disableSslVerification: boolean;
+    /**
+     * Create a new TokenRequestBasedAuthenticatorImmutable instance with an internal JwtTokenManager.
+     *
+     * @param options - Configuration options.
+     * This should be an object containing these fields:
+     * - url: (optional) the endpoint URL for the token service
+     * - disableSslVerification: (optional) a flag that indicates whether verification of the token server's SSL certificate
+     * should be disabled or not
+     * - headers: (optional) a set of HTTP headers to be sent with each request to the token service
+     */
+    constructor(options: BaseOptions);
     /**
      * Adds bearer token information to "requestOptions". The bearer token information
      * will be set in the Authorization property of "requestOptions.headers" in the form:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ibm-cloud-sdk-core",
-  "version": "5.0.2",
+  "version": "5.1.1",
   "description": "Core functionality to support SDKs generated with IBM's OpenAPI SDK Generator.",
   "main": "index.js",
   "typings": "./es/index.d.ts",
@@ -67,7 +67,7 @@
     "eslint:fix": "eslint . --fix",
     "eslint:check": "eslint . --cache",
     "lint": "npm run eslint:check",
-    "lint:fix": "npm run eslint:fix",
+    "fix": "npm run eslint:fix",
     "jest": "jest",
     "test": "jest test/unit/",
     "test-travis": "jest --runInBand test/unit/",