ibm-cloud-sdk-core 4.2.5 → 4.3.1

package/build/docs/ibm-cloud-sdk-core.vpcinstancetokenmanager._constructor_.md

@@ -14,9 +14,39 @@ constructor(options: Options);
 
 ## Parameters
 
-|  Parameter | Type | Description |
-|  --- | --- | --- |
-|  options | Options | Configuration options. This should be an object containing these fields: - url: (optional) the endpoint URL for the VPC Instance Metadata Service (default value: "http://169.254.169.254") - iamProfileCrn: (optional) the CRN of the linked IAM trusted profile to be used to obtain the IAM access token - iamProfileId: (optional) the ID of the linked IAM trusted profile to be used to obtain the IAM access token |
+<table><thead><tr><th>
+
+Parameter
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+options
+
+
+</td><td>
+
+Options
+
+
+</td><td>
+
+Configuration options. This should be an object containing these fields: - url: (optional) the endpoint URL for the VPC Instance Metadata Service (default value: "http://169.254.169.254") - iamProfileCrn: (optional) the CRN of the linked IAM trusted profile to be used to obtain the IAM access token - iamProfileId: (optional) the ID of the linked IAM trusted profile to be used to obtain the IAM access token
+
+
+</td></tr>
+</tbody></table>
 
 ## Remarks
 

package/build/docs/ibm-cloud-sdk-core.vpcinstancetokenmanager.md

@@ -15,16 +15,112 @@ export declare class VpcInstanceTokenManager extends JwtTokenManager
 
 ## Constructors
 
-|  Constructor | Modifiers | Description |
-|  --- | --- | --- |
-|  [(constructor)(options)](./ibm-cloud-sdk-core.vpcinstancetokenmanager._constructor_.md) |  | Create a new VpcInstanceTokenManager instance. |
+<table><thead><tr><th>
+
+Constructor
+
+
+</th><th>
+
+Modifiers
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+[(constructor)(options)](./ibm-cloud-sdk-core.vpcinstancetokenmanager._constructor_.md)
+
+
+</td><td>
+
+
+</td><td>
+
+Create a new VpcInstanceTokenManager instance.
+
+
+</td></tr>
+</tbody></table>
 
 ## Methods
 
-|  Method | Modifiers | Description |
-|  --- | --- | --- |
-|  [isTokenExpired()](./ibm-cloud-sdk-core.vpcinstancetokenmanager.istokenexpired.md) | <code>protected</code> | Returns true iff the currently-cached IAM access token is expired. We'll consider an access token as expired when we reach its IAM server-reported expiration time minus our expiration window (10 secs). We do this to avoid using an access token that might expire in the middle of a long-running transaction within an IBM Cloud service. |
-|  [requestToken()](./ibm-cloud-sdk-core.vpcinstancetokenmanager.requesttoken.md) | <code>protected</code> |  |
-|  [setIamProfileCrn(iamProfileCrn)](./ibm-cloud-sdk-core.vpcinstancetokenmanager.setiamprofilecrn.md) |  | Sets the CRN of the IAM trusted profile to use when fetching the access token from the IAM token server. |
-|  [setIamProfileId(iamProfileId)](./ibm-cloud-sdk-core.vpcinstancetokenmanager.setiamprofileid.md) |  | Sets the Id of the IAM trusted profile to use when fetching the access token from the IAM token server. |
+<table><thead><tr><th>
+
+Method
+
+
+</th><th>
+
+Modifiers
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+[isTokenExpired()](./ibm-cloud-sdk-core.vpcinstancetokenmanager.istokenexpired.md)
+
+
+</td><td>
+
+`protected`
+
+
+</td><td>
+
+Returns true iff the currently-cached IAM access token is expired. We'll consider an access token as expired when we reach its IAM server-reported expiration time minus our expiration window (10 secs). We do this to avoid using an access token that might expire in the middle of a long-running transaction within an IBM Cloud service.
+
+
+</td></tr>
+<tr><td>
+
+[requestToken()](./ibm-cloud-sdk-core.vpcinstancetokenmanager.requesttoken.md)
+
+
+</td><td>
+
+`protected`
+
+
+</td><td>
+
+
+</td></tr>
+<tr><td>
+
+[setIamProfileCrn(iamProfileCrn)](./ibm-cloud-sdk-core.vpcinstancetokenmanager.setiamprofilecrn.md)
+
+
+</td><td>
+
+
+</td><td>
+
+Sets the CRN of the IAM trusted profile to use when fetching the access token from the IAM token server.
+
+
+</td></tr>
+<tr><td>
+
+[setIamProfileId(iamProfileId)](./ibm-cloud-sdk-core.vpcinstancetokenmanager.setiamprofileid.md)
+
+
+</td><td>
+
+
+</td><td>
+
+Sets the Id of the IAM trusted profile to use when fetching the access token from the IAM token server.
+
 
+</td></tr>
+</tbody></table>

package/build/docs/ibm-cloud-sdk-core.vpcinstancetokenmanager.setiamprofilecrn.md

@@ -14,10 +14,39 @@ setIamProfileCrn(iamProfileCrn: string): void;
 
 ## Parameters
 
-|  Parameter | Type | Description |
-|  --- | --- | --- |
-|  iamProfileCrn | string | the CRN of the IAM trusted profile |
+<table><thead><tr><th>
 
+Parameter
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+iamProfileCrn
+
+
+</td><td>
+
+string
+
+
+</td><td>
+
+the CRN of the IAM trusted profile
+
+
+</td></tr>
+</tbody></table>
 **Returns:**
 
 void

package/build/docs/ibm-cloud-sdk-core.vpcinstancetokenmanager.setiamprofileid.md

@@ -14,10 +14,39 @@ setIamProfileId(iamProfileId: string): void;
 
 ## Parameters
 
-|  Parameter | Type | Description |
-|  --- | --- | --- |
-|  iamProfileId | string | the ID of the IAM trusted profile |
+<table><thead><tr><th>
 
+Parameter
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+iamProfileId
+
+
+</td><td>
+
+string
+
+
+</td><td>
+
+the ID of the IAM trusted profile
+
+
+</td></tr>
+</tbody></table>
 **Returns:**
 
 void

package/build/docs/index.md

@@ -6,7 +6,24 @@
 
 ## Packages
 
-|  Package | Description |
-|  --- | --- |
-|  [ibm-cloud-sdk-core](./ibm-cloud-sdk-core.md) |  |
+<table><thead><tr><th>
 
+Package
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+[ibm-cloud-sdk-core](./ibm-cloud-sdk-core.md)
+
+
+</td><td>
+
+
+</td></tr>
+</tbody></table>

package/docs/ibm-cloud-sdk-core.api.json

@@ -1,7 +1,7 @@
 {
   "metadata": {
     "toolPackage": "@microsoft/api-extractor",
-    "toolVersion": "7.41.0",
+    "toolVersion": "7.43.1",
     "schemaVersion": 1011,
     "oldestForwardsCompatibleVersion": 1001,
     "tsdocConfig": {
@@ -6951,6 +6951,36 @@
               "isStatic": false,
               "isProtected": true,
               "isAbstract": false
+            },
+            {
+              "kind": "Property",
+              "canonicalReference": "ibm-cloud-sdk-core!TokenManager#userAgent:member",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "protected userAgent: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Public",
+              "name": "userAgent",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isStatic": false,
+              "isProtected": true,
+              "isAbstract": false
             }
           ],
           "implementsTokenRanges": []

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

@@ -1,5 +1,5 @@
 /**
- * Copyright 2021, 2023 IBM Corp. All Rights Reserved.
+ * (C) Copyright IBM Corp. 2021, 2024.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

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

@@ -1,5 +1,5 @@
 /**
- * Copyright 2021, 2023 IBM Corp. All Rights Reserved.
+ * (C) Copyright IBM Corp. 2021, 2024.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -24,6 +24,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 import { atLeastOne } from '../utils/helpers';
 import { readCrTokenFile } from '../utils/file-reading-helpers';
+import { buildUserAgent } from '../../lib/build-user-agent';
 import { IamRequestBasedTokenManager } from './iam-request-based-token-manager';
 const DEFAULT_CR_TOKEN_FILEPATH1 = '/var/run/secrets/tokens/vault-token';
 const DEFAULT_CR_TOKEN_FILEPATH2 = '/var/run/secrets/tokens/sa-token';
@@ -71,6 +72,7 @@ export class ContainerTokenManager extends IamRequestBasedTokenManager {
         }
         // construct form data for the cr token use case of iam token management
         this.formData.grant_type = 'urn:ibm:params:oauth:grant-type:cr-token';
+        this.userAgent = buildUserAgent('container-authenticator');
     }
     /**
      * Sets the "crTokenFilename" field

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

@@ -1,5 +1,5 @@
 /**
- * (C) Copyright IBM Corp. 2019, 2023.
+ * (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.

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

@@ -1,5 +1,5 @@
 /**
- * (C) Copyright IBM Corp. 2019, 2023.
+ * (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.
@@ -15,6 +15,7 @@
  */
 import extend from 'extend';
 import { validateInput } from '../utils/helpers';
+import { buildUserAgent } from '../../lib/build-user-agent';
 import { JwtTokenManager } from './jwt-token-manager';
 /**
  * Token Manager of CloudPak for data.
@@ -54,11 +55,13 @@ export class Cp4dTokenManager extends JwtTokenManager {
         this.username = options.username;
         this.password = options.password;
         this.apikey = options.apikey;
+        this.userAgent = buildUserAgent('cp4d-authenticator');
     }
     requestToken() {
         // these cannot be overwritten
         const requiredHeaders = {
             'Content-Type': 'application/json',
+            'User-Agent': this.userAgent,
         };
         const parameters = {
             options: {

package/es/auth/token-managers/iam-request-based-token-manager.js

@@ -125,7 +125,8 @@ export class IamRequestBasedTokenManager extends JwtTokenManager {
     requestToken() {
         // these cannot be overwritten
         const requiredHeaders = {
-            'Content-type': 'application/x-www-form-urlencoded',
+            'Content-Type': 'application/x-www-form-urlencoded',
+            'User-Agent': this.userAgent,
         };
         // If both the clientId and secret were specified by the user, then use them.
         if (this.clientId && this.clientSecret) {

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

@@ -1,5 +1,5 @@
 /**
- * (C) Copyright IBM Corp. 2019, 2023.
+ * (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.

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

@@ -1,5 +1,5 @@
 /**
- * (C) Copyright IBM Corp. 2019, 2023.
+ * (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.
@@ -14,6 +14,7 @@
  * limitations under the License.
  */
 import { validateInput } from '../utils/helpers';
+import { buildUserAgent } from '../../lib/build-user-agent';
 import { IamRequestBasedTokenManager } from './iam-request-based-token-manager';
 /**
  * The IAMTokenManager takes an api key and performs the necessary interactions with
@@ -49,5 +50,6 @@ export class IamTokenManager extends IamRequestBasedTokenManager {
         this.formData.apikey = this.apikey;
         this.formData.grant_type = 'urn:ibm:params:oauth:grant-type:apikey';
         this.formData.response_type = 'cloud_iam';
+        this.userAgent = buildUserAgent('iam-authenticator');
     }
 }

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

@@ -1,5 +1,5 @@
 /**
- * (C) Copyright IBM Corp. 2023.
+ * (C) Copyright IBM Corp. 2023, 2024.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

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

@@ -1,5 +1,5 @@
 /**
- * (C) Copyright IBM Corp. 2023.
+ * (C) Copyright IBM Corp. 2023, 2024.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -15,6 +15,7 @@
  */
 import extend from 'extend';
 import { validateInput } from '../utils/helpers';
+import { buildUserAgent } from '../../lib/build-user-agent';
 import { JwtTokenManager } from './jwt-token-manager';
 /**
  * This is the path associated with the operation used to obtain
@@ -47,11 +48,13 @@ export class McspTokenManager extends JwtTokenManager {
         this.tokenName = 'token';
         validateInput(options, this.requiredOptions);
         this.apikey = options.apikey;
+        this.userAgent = buildUserAgent('mcsp-authenticator');
     }
     requestToken() {
         const requiredHeaders = {
             Accept: 'application/json',
             'Content-Type': 'application/json',
+            'User-Agent': this.userAgent,
         };
         const parameters = {
             options: {

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

@@ -39,6 +39,7 @@ export type TokenManagerOptions = {
  */
 export declare class TokenManager {
     protected url: string;
+    protected userAgent: string;
     protected disableSslVerification: boolean;
     protected headers: OutgoingHttpHeaders;
     protected requestWrapperInstance: RequestWrapper;

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

@@ -24,6 +24,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 import logger from '../../lib/logger';
 import { atMostOne, getCurrentTime } from '../utils/helpers';
+import { buildUserAgent } from '../../lib/build-user-agent';
 import { JwtTokenManager } from './jwt-token-manager';
 const DEFAULT_IMS_ENDPOINT = 'http://169.254.169.254';
 const METADATA_SERVICE_VERSION = '2022-03-01';
@@ -59,6 +60,7 @@ export class VpcInstanceTokenManager extends JwtTokenManager {
         if (options.iamProfileId) {
             this.iamProfileId = options.iamProfileId;
         }
+        this.userAgent = buildUserAgent('vpc-instance-authenticator');
     }
     /**
      * Sets the CRN of the IAM trusted profile to use when fetching the access token from the IAM token server.
@@ -99,6 +101,7 @@ export class VpcInstanceTokenManager extends JwtTokenManager {
                     method: 'POST',
                     headers: {
                         'Content-Type': 'application/json',
+                        'User-Agent': this.userAgent,
                         Accept: 'application/json',
                         Authorization: `Bearer ${instanceIdentityToken}`,
                     },
@@ -122,6 +125,7 @@ export class VpcInstanceTokenManager extends JwtTokenManager {
                     method: 'PUT',
                     headers: {
                         'Content-Type': 'application/json',
+                        'User-Agent': this.userAgent,
                         Accept: 'application/json',
                         'Metadata-Flavor': 'ibm',
                     },

package/es/auth/utils/file-reading-helpers.d.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright 2021, 2023 IBM Corp. All Rights Reserved.
+ * Copyright 2021, 2024 IBM Corp. All Rights Reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

package/es/auth/utils/file-reading-helpers.js

@@ -1,5 +1,5 @@
 /**
- * Copyright 2021, 2023 IBM Corp. All Rights Reserved.
+ * Copyright 2021, 2024 IBM Corp. All Rights Reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

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

@@ -1,6 +1,6 @@
 /* eslint-disable no-restricted-syntax */
 /**
- * (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.
@@ -15,8 +15,8 @@
  * limitations under the License.
  */
 import camelcase from 'camelcase';
-import isEmpty from 'lodash.isempty';
 import logger from '../../lib/logger';
+import { isEmptyObject } from '../../lib/helper';
 import { readCredentialsFile } from './file-reading-helpers';
 /**
  * Read properties stored in external sources like Environment Variables,
@@ -42,10 +42,10 @@ function getProperties(serviceName) {
     // only get properties from one source, return null if none found
     let properties = null;
     properties = filterPropertiesByServiceName(readCredentialsFile(), serviceName);
-    if (isEmpty(properties)) {
+    if (isEmptyObject(properties)) {
         properties = filterPropertiesByServiceName(process.env, serviceName);
     }
-    if (isEmpty(properties)) {
+    if (isEmptyObject(properties)) {
         properties = getPropertiesFromVCAP(serviceName);
     }
     return properties;

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

@@ -1,5 +1,5 @@
 /**
- * (C) Copyright IBM Corp. 2014, 2023.
+ * (C) Copyright IBM Corp. 2014, 2024.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -61,6 +61,7 @@ export declare class BaseService {
     protected baseOptions: BaseServiceOptions;
     private authenticator;
     private requestWrapperInstance;
+    private defaultUserAgent;
     /**
      * Configuration values for a service.
      *

package/es/lib/base-service.js

@@ -1,5 +1,5 @@
 /**
- * (C) Copyright IBM Corp. 2014, 2023.
+ * (C) Copyright IBM Corp. 2014, 2024.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -13,10 +13,12 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import extend from 'extend';
 import { checkCredentials, readExternalSources } from '../auth';
 import { stripTrailingSlash } from './helper';
 import logger from './logger';
 import { RequestWrapper } from './request-wrapper';
+import { buildUserAgent } from './build-user-agent';
 /**
  * Common functionality shared by generated service classes.
  *
@@ -70,6 +72,7 @@ export class BaseService {
             throw new Error('Authenticator must be set.');
         }
         this.authenticator = options.authenticator;
+        this.defaultUserAgent = buildUserAgent();
     }
     /**
      * Get the instance of the authenticator set on the service.
@@ -197,6 +200,11 @@ export class BaseService {
         if (!serviceUrl || typeof serviceUrl !== 'string') {
             return Promise.reject(new Error('The service URL is required'));
         }
+        // make sure the outbound request contains a User-Agent header
+        const userAgent = {
+            'User-Agent': this.defaultUserAgent,
+        };
+        parameters.defaultOptions.headers = extend(true, {}, userAgent, parameters.defaultOptions.headers);
         return this.authenticator.authenticate(parameters.defaultOptions).then(() => 
         // resolve() handles rejection as well, so resolving the result of sendRequest should allow for proper handling later
         this.requestWrapperInstance.sendRequest(parameters));

package/es/lib/build-user-agent.d.ts

@@ -0,0 +1,21 @@
+/**
+ * (C) Copyright IBM Corp. 2024.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Returns a string suitable as a value for the User-Agent header
+ * @param componentName optional name of a component to be included in the returned string
+ * @returns the user agent header value
+ */
+export declare function buildUserAgent(componentName?: string): string;

package/es/lib/build-user-agent.js

@@ -0,0 +1,27 @@
+/**
+ * (C) Copyright IBM Corp. 2024.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+const os = require('os');
+const { version } = require('../package.json');
+/**
+ * Returns a string suitable as a value for the User-Agent header
+ * @param componentName optional name of a component to be included in the returned string
+ * @returns the user agent header value
+ */
+export function buildUserAgent(componentName = null) {
+    const subComponent = componentName ? `/${componentName}` : '';
+    const userAgent = `ibm-node-sdk-core${subComponent}-${version} os.name=${os.platform()} os.version=${os.release()} node.version=${process.version}`;
+    return userAgent;
+}