docs: README and JSDoc comments updated

README.md

@@ -165,7 +165,7 @@ Some services use token-based Identity and Access Management (IAM) authenticatio
 
 To use IAM authentication, you must use an `IamAuthenticator` or a `BearerTokenAuthenticator`.
 - Use the `IamAuthenticator` to have the SDK manage the lifecycle of the access token. The SDK requests an access token, ensures that the access token is valid, and refreshes it if necessary.
-- Use the `BearerTokenAuthenticator` if you want to manage the lifecycle yourself. For details, see [Authenticating with IAM tokens](https://cloud.ibm.com/docs/services/watson/getting-started-iam.html). If you want to switch your authenticator, you must override the `authenticator` property directly.
+- Use the `BearerTokenAuthenticator` if you want to manage the lifecycle yourself. For details, see [Authenticating with IAM tokens](https://cloud.ibm.com/docs/watson/getting-started-iam.html). If you want to switch your authenticator, you must override the `authenticator` property directly.
 
 ##### ICP
 
@@ -310,7 +310,7 @@ recognizeStream.getTransactionId().then(
 
 ## Data collection opt-out
 
-By default, [all requests are logged](https://cloud.ibm.com/docs/services/watson/getting-started-logging.html). This can be disabled of by setting the `X-Watson-Learning-Opt-Out` header when creating the service instance:
+By default, [all requests are logged](https://cloud.ibm.com/docs/watson/getting-started-logging.html). This can be disabled of by setting the `X-Watson-Learning-Opt-Out` header when creating the service instance:
 
 ```js
 const myInstance = new watson.WhateverServiceV1({
@@ -411,7 +411,7 @@ The Authorization service can generate auth tokens for situations where providin
 Tokens are valid for 1 hour and may be sent using the `X-Watson-Authorization-Token` header or the `watson-token` query param.
 Note that the token is supplied URL-encoded, and will not be accepted if it is double-encoded in a querystring.
 
-> _NOTE_: Authenticating with the `X-Watson-Authorization-Token` header or the `watson-token` query param is now deprecated. The token continues to work with Cloud Foundry services, but is not supported for services that use Identity and Access Management (IAM) authentication. For details see [Authenticating with IAM tokens](https://cloud.ibm.com/docs/services/watson?topic=watson-iam#iam) or the README in the IBM Watson SDK you use.
+> _NOTE_: Authenticating with the `X-Watson-Authorization-Token` header or the `watson-token` query param is now deprecated. The token continues to work with Cloud Foundry services, but is not supported for services that use Identity and Access Management (IAM) authentication. For details see [Authenticating with IAM tokens](https://cloud.ibm.com/docs/watson?topic=watson-iam#iam) or the README in the IBM Watson SDK you use.
 The Authorization SDK now supports returning IAM Access Tokens when instantiated with an IAM API key.
 
 ```js
@@ -454,7 +454,7 @@ function (err, token) {
 
 Use the [Assistant][assistant] service to determine the intent of a message.
 
-Note: You must first create a workspace via IBM Cloud. See [the documentation](https://cloud.ibm.com/docs/services/conversation/index.html#about) for details.
+Note: You must first create a workspace via IBM Cloud. See [the documentation](https://cloud.ibm.com/docs/conversation/index.html#about) for details.
 
 ```js
 const AssistantV2 = require('ibm-watson/assistant/v2');
@@ -484,7 +484,7 @@ assistant.message(
 
 Use the [Assistant][assistant] service to determine the intent of a message.
 
-Note: You must first create a workspace via IBM Cloud. See [the documentation](https://cloud.ibm.com/docs/services/conversation/index.html#about) for details.
+Note: You must first create a workspace via IBM Cloud. See [the documentation](https://cloud.ibm.com/docs/conversation/index.html#about) for details.
 
 ```js
 const AssistantV1 = require('ibm-watson/assistant/v1');
@@ -611,7 +611,7 @@ languageTranslator.identify(
 
 ### Natural Language Classifier
 
-Use [Natural Language Classifier](https://cloud.ibm.com/docs/services/natural-language-classifier/getting-started.html) service to create a classifier instance by providing a set of representative strings and a set of one or more correct classes for each as training. Then use the trained classifier to classify your new question for best matching answers or to retrieve next actions for your application.
+Use [Natural Language Classifier](https://cloud.ibm.com/docs/natural-language-classifier/getting-started.html) service to create a classifier instance by providing a set of representative strings and a set of one or more correct classes for each as training. Then use the trained classifier to classify your new question for best matching answers or to retrieve next actions for your application.
 
 ```js
 const NaturalLanguageClassifierV1 = require('ibm-watson/natural-language-classifier/v1');

assistant/v2.ts

@@ -520,19 +520,7 @@ namespace AssistantV2 {
     /** Arbitrary variables that can be read and written by a particular skill. */
     user_defined?: JsonObject;
     /** System context data used by the skill. */
-    system?: MessageContextSkillSystem;
-  }
-
-  /** System context data used by the skill. */
-  export interface MessageContextSkillSystem {
-    /** An encoded string representing the current conversation state. By saving this value and then sending it in
-     *  the context of a subsequent message request, you can restore the conversation to the same state. This can be
-     *  useful if you need to return to an earlier point in the conversation or resume a paused conversation after the
-     *  session has expired.
-     */
-    state?: string;
-    /** MessageContextSkillSystem accepts additional properties. */
-    [propName: string]: any;
+    system?: JsonObject;
   }
 
   /** Information specific to particular skills used by the Assistant. **Note:** Currently, only a single property named `main skill` is supported. This object contains variables that apply to the dialog skill used by the assistant. */

compare-comply/v1.ts

@@ -735,9 +735,9 @@ class CompareComplyV1 extends BaseService {
    * Run Compare and Comply methods over a collection of input documents.
    *
    * **Important:** Batch processing requires the use of the [IBM Cloud Object Storage
-   * service](https://cloud.ibm.com/docs/services/cloud-object-storage?topic=cloud-object-storage-about#about-ibm-cloud-object-storage).
+   * service](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-about#about-ibm-cloud-object-storage).
    * The use of IBM Cloud Object Storage with Compare and Comply is discussed at [Using batch
-   * processing](https://cloud.ibm.com/docs/services/compare-comply?topic=compare-comply-batching#before-you-batch).
+   * processing](https://cloud.ibm.com/docs/compare-comply?topic=compare-comply-batching#before-you-batch).
    *
    * @param {Object} params - The parameters to send to the service.
    * @param {string} params._function - The Compare and Comply method to run across the submitted input documents.

discovery/v2.ts

@@ -144,7 +144,7 @@ class DiscoveryV2 extends BaseService {
    * Query a project.
    *
    * By using this method, you can construct queries. For details, see the [Discovery
-   * documentation](https://cloud.ibm.com/docs/services/discovery-data?topic=discovery-data-query-concepts).
+   * documentation](https://cloud.ibm.com/docs/discovery-data?topic=discovery-data-query-concepts).
    *
    * @param {Object} params - The parameters to send to the service.
    * @param {string} params.projectId - The ID of the project. This information can be found from the deploy page of the
@@ -2154,6 +2154,8 @@ namespace DiscoveryV2 {
     field: string;
     /** The size of the sections the results are split into. */
     interval: number;
+    /** Identifier specified in the query request of this aggregation. */
+    name?: string;
     /** Array of numeric intervals. */
     results?: QueryHistogramAggregationResult[];
   }
@@ -2174,6 +2176,8 @@ namespace DiscoveryV2 {
     field: string;
     /** The number of top values returned. */
     count?: number;
+    /** Identifier specified in the query request of this aggregation. */
+    name?: string;
     /** Array of top values for the field. */
     results?: QueryTermAggregationResult[];
   }
@@ -2184,6 +2188,8 @@ namespace DiscoveryV2 {
     field: string;
     /** The date interval value. Valid values are seconds, minutes, hours, days, weeks, and years. */
     interval: string;
+    /** Identifier specified in the query request of this aggregation. */
+    name?: string;
     /** Array of aggregation results. */
     results?: QueryTimesliceAggregationResult[];
   }
@@ -2192,6 +2198,8 @@ namespace DiscoveryV2 {
   export interface QueryTopHitsAggregation extends QueryAggregation {
     /** The number of documents to return. */
     size: number;
+    /** Identifier specified in the query request of this aggregation. */
+    name?: string;
     hits?: QueryTopHitsAggregationResult;
   }
 

language-translator/v3.ts

@@ -76,15 +76,18 @@ class LanguageTranslatorV3 extends BaseService {
   /**
    * Translate.
    *
-   * Translates the input text from the source language to the target language.
+   * Translates the input text from the source language to the target language. A target language or translation model
+   * ID is required. The service attempts to detect the language of the source text if it is not specified.
    *
    * @param {Object} params - The parameters to send to the service.
    * @param {string[]} params.text - Input text in UTF-8 encoding. Multiple entries will result in multiple translations
    * in the response.
-   * @param {string} [params.modelId] - A globally unique string that identifies the underlying model that is used for
-   * translation.
-   * @param {string} [params.source] - Translation source language code.
-   * @param {string} [params.target] - Translation target language code.
+   * @param {string} [params.modelId] - The model to use for translation. For example, `en-de` selects the IBM provided
+   * base model for English to German translation. A model ID overrides the source and target parameters and is required
+   * if you use a custom model. If no model ID is specified, you must specify a target language.
+   * @param {string} [params.source] - Language code that specifies the language of the source document.
+   * @param {string} [params.target] - Language code that specifies the target language for translation. Required if
+   * model ID is not specified.
    * @param {OutgoingHttpHeaders} [params.headers] - Custom request headers
    * @param {Function} [callback] - The callback that handles the response
    * @returns {Promise<LanguageTranslatorV3.Response<LanguageTranslatorV3.TranslationResult>>}
@@ -610,15 +613,17 @@ class LanguageTranslatorV3 extends BaseService {
    * @param {NodeJS.ReadableStream|Buffer} params.file - The contents of the source file to translate.
    *
    * [Supported file
-   * types](https://cloud.ibm.com/docs/services/language-translator?topic=language-translator-document-translator-tutorial#supported-file-formats)
+   * types](https://cloud.ibm.com/docs/language-translator?topic=language-translator-document-translator-tutorial#supported-file-formats)
    *
    * Maximum file size: **20 MB**.
    * @param {string} params.filename - The filename for file.
    * @param {string} [params.fileContentType] - The content type of file.
-   * @param {string} [params.modelId] - The model to use for translation. `model_id` or both `source` and `target` are
-   * required.
+   * @param {string} [params.modelId] - The model to use for translation. For example, `en-de` selects the IBM provided
+   * base model for English to German translation. A model ID overrides the source and target parameters and is required
+   * if you use a custom model. If no model ID is specified, you must specify a target language.
    * @param {string} [params.source] - Language code that specifies the language of the source document.
-   * @param {string} [params.target] - Language code that specifies the target language for translation.
+   * @param {string} [params.target] - Language code that specifies the target language for translation. Required if
+   * model ID is not specified.
    * @param {string} [params.documentId] - To use a previously submitted document as the source for a new translation,
    * enter the `document_id` of the document.
    * @param {OutgoingHttpHeaders} [params.headers] - Custom request headers
@@ -919,11 +924,14 @@ namespace LanguageTranslatorV3 {
   export interface TranslateParams {
     /** Input text in UTF-8 encoding. Multiple entries will result in multiple translations in the response. */
     text: string[];
-    /** A globally unique string that identifies the underlying model that is used for translation. */
+    /** The model to use for translation. For example, `en-de` selects the IBM provided base model for English to
+     *  German translation. A model ID overrides the source and target parameters and is required if you use a custom
+     *  model. If no model ID is specified, you must specify a target language.
+     */
     modelId?: string;
-    /** Translation source language code. */
+    /** Language code that specifies the language of the source document. */
     source?: string;
-    /** Translation target language code. */
+    /** Language code that specifies the target language for translation. Required if model ID is not specified. */
     target?: string;
     headers?: OutgoingHttpHeaders;
   }
@@ -1003,7 +1011,7 @@ namespace LanguageTranslatorV3 {
     /** The contents of the source file to translate.
      *
      *  [Supported file
-     *  types](https://cloud.ibm.com/docs/services/language-translator?topic=language-translator-document-translator-tutorial#supported-file-formats)
+     *  types](https://cloud.ibm.com/docs/language-translator?topic=language-translator-document-translator-tutorial#supported-file-formats)
      *
      *  Maximum file size: **20 MB**.
      */
@@ -1012,11 +1020,14 @@ namespace LanguageTranslatorV3 {
     filename: string;
     /** The content type of file. */
     fileContentType?: TranslateDocumentConstants.FileContentType | string;
-    /** The model to use for translation. `model_id` or both `source` and `target` are required. */
+    /** The model to use for translation. For example, `en-de` selects the IBM provided base model for English to
+     *  German translation. A model ID overrides the source and target parameters and is required if you use a custom
+     *  model. If no model ID is specified, you must specify a target language.
+     */
     modelId?: string;
     /** Language code that specifies the language of the source document. */
     source?: string;
-    /** Language code that specifies the target language for translation. */
+    /** Language code that specifies the target language for translation. Required if model ID is not specified. */
     target?: string;
     /** To use a previously submitted document as the source for a new translation, enter the `document_id` of the
      *  document.
@@ -1149,6 +1160,10 @@ namespace LanguageTranslatorV3 {
     base_model_id?: string;
     /** Translation source language code. */
     source: string;
+    /** A score between 0 and 1 indicating the confidence of source language detection. A higher value indicates
+     *  greater confidence. This is returned only when the service automatically detects the source language.
+     */
+    detected_language_confidence?: number;
     /** Translation target language code. */
     target: string;
     /** The time when the document was submitted. */
@@ -1239,6 +1254,12 @@ namespace LanguageTranslatorV3 {
     word_count: number;
     /** Number of characters in the input text. */
     character_count: number;
+    /** The language code of the source text if the source language was automatically detected. */
+    detected_language?: string;
+    /** A score between 0 and 1 indicating the confidence of source language detection. A higher value indicates
+     *  greater confidence. This is returned only when the service automatically detects the source language.
+     */
+    detected_language_confidence?: number;
     /** List of translation output in UTF-8, corresponding to the input text entries. */
     translations: Translation[];
   }

lib/recognize-stream.ts

@@ -103,6 +103,8 @@ class RecognizeStream extends Duplex {
    * @param {boolean} [options.audioMetrics] - If true, requests detailed information about the signal characteristics of the input audio (detailed=false)
    * @param {number} [options.endOfPhraseSilenceTime] - If `true`, specifies the duration of the pause interval at which the service splits a transcript into multiple final results
    * @param {boolean} [options.splitTranscriptAtPhraseEnd] - If `true`, directs the service to split the transcript into multiple final results based on semantic features of the input
+   * @param {number} [options.speechDetectorSensitivity] - The sensitivity of speech activity detection that the service is to perform
+   * @param {number} [options.backgroundAudioSuppression] - The level to which the service is to suppress background audio based on its volume to prevent it from being transcribed as speech
    * @constructor
    */
   constructor(options: RecognizeStream.Options) {