Merge branch 'v4.0.0-branch' into add-promise-support

Author: dpopp07

CHANGELOG.md

@@ -1,3 +1,26 @@
+# [3.18.0](https://github.com/watson-developer-cloud/node-sdk/compare/v3.17.0...v3.18.0) (2019-02-06)
+
+
+### Features
+
+* **compare-comply:** new constants and new model properties added ([d9dc7cc](https://github.com/watson-developer-cloud/node-sdk/commit/d9dc7cc))
+* **discovery:** add method `getStopwordListStatus` ([ea9eaf9](https://github.com/watson-developer-cloud/node-sdk/commit/ea9eaf9))
+* **speech-to-text:** optional parameter `force` added to the method `upgradeAcousticModel` ([ceaa843](https://github.com/watson-developer-cloud/node-sdk/commit/ceaa843))
+
+# [3.17.0](https://github.com/watson-developer-cloud/node-sdk/compare/v3.16.1...v3.17.0) (2019-02-04)
+
+
+### Features
+
+* enable reading credentials from ibm-credentials.env file ([ce02aa8](https://github.com/watson-developer-cloud/node-sdk/commit/ce02aa8))
+
+## [3.16.1](https://github.com/watson-developer-cloud/node-sdk/compare/v3.16.0...v3.16.1) (2019-01-19)
+
+
+### Bug Fixes
+
+* fix `getTransactionId` method for the `RecognizeStream` class ([e5bbe2c](https://github.com/watson-developer-cloud/node-sdk/commit/e5bbe2c))
+
 # [3.16.0](https://github.com/watson-developer-cloud/node-sdk/compare/v3.15.4...v3.16.0) (2019-01-17)
 
 

README.md

@@ -86,14 +86,55 @@ Watson services are migrating to token-based Identity and Access Management (IAM
 - In other instances, you authenticate by providing the **[username and password](#username-and-password)** for the service instance.
 
 ### Getting credentials
+
 To find out which authentication to use, view the service credentials. You find the service credentials for authentication the same way for all Watson services:
 
-1. Go to the IBM Cloud [Dashboard](https://console.bluemix.net/dashboard/apps?category=ai) page.
-1. Either click an existing Watson service instance or click [**Create resource > AI**](https://console.bluemix.net/catalog/?category=ai) and create a service instance.
-1. Click **Show** to view your service credentials.
-1. Copy the `url` and either `apikey` or `username` and `password`.
+1.  Go to the IBM Cloud [Dashboard](https://cloud.ibm.com/) page.
+2.  Either click an existing Watson service instance in your [resource list](https://cloud.ibm.com/resources) or click [**Create resource > AI**](https://cloud.ibm.com/catalog?category=ai) and create a service instance.
+3. Click on the **Manage** item in the left nav bar of your service instance.
+
+On this page, you should be able to see your credentials for accessing your service instance.
+
+In your code, you can use these values in the service constructor or with a method call after instantiating your service.
+
+### Supplying credentials
+
+There are two ways to supply the credentials you found above to the SDK for authentication:
+
+#### Credentials file (easier!)
+
+With a credentials file, you just need to put the file in the right place and the SDK will do the work of parsing it and authenticating. You can get this file by clicking the **Download** button for the credentials in the **Manage** tab of your service instance.
+
+The file downloaded will be called `ibm-credentials.env`. This is the name the SDK will search for and **must** be preserved unless you want to configure the file path (more on that later). The SDK will look for your `ibm-credentials.env` file in the following places (in order):
+
+- Directory provided by the environment variable `IBM_CREDENTIALS_FILE`
+- Your system's home directory
+- Your current working directory (the directory Node is executed from)
+
+As long as you set that up correctly, you don't have to worry about setting any authentication options in your code. So, for example, if you created and downloaded the credential file for your Discovery instance, you just need to do the following:
+
+```js
+const DiscoveryV1 = require('watson-developer-cloud/discovery/v1');
+const discovery = new DiscoveryV1({ version: '2019-02-01' });
+```
+
+And that's it!
+
+If you're using more than one service at a time in your code and get two different `ibm-credentials.env` files, just put the contents together in one `ibm-credentials.env` file and the SDK will handle assigning credentials to their appropriate services.
+
+If you would like to configure the location/name of your credential file, you can set an environment variable called `IBM_CREDENTIALS_FILE`. **This will take precedence over the locations specified above.** Here's how you can do that:
+
+```bash
+export IBM_CREDENTIALS_FILE="<path>"
+```
+
+where `<path>` is something like `/home/user/Downloads/<file_name>.env`. If you just provide a path to a directory, the SDK will look for a file called `ibm-credentials.env` in that directory.
+
+#### Manually
+
+The SDK also supports setting credentials manually in your code. You will either use IAM credentials or Basic Authentication (username/password) credentials.
 
-### IAM
+##### IAM
 
 Some services use token-based Identity and Access Management (IAM) authentication. IAM authentication uses a service API key to get an access token that is passed with the call. Access tokens are valid for approximately one hour and must be regenerated.
 
@@ -102,7 +143,7 @@ You supply either an IAM service **API key** or an **access token**:
 - Use the API key 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 access token if you want to manage the lifecycle yourself. For details, see [Authenticating with IAM tokens](https://console.bluemix.net/docs/services/watson/getting-started-iam.html). If you want to switch to API key, override your stored IAM credentials with an IAM API key.
 
-#### Supplying the IAM API key
+###### Supplying the IAM API key
 
 ```js
 // in the constructor, letting the SDK manage the IAM token
@@ -114,7 +155,7 @@ const discovery = new DiscoveryV1({
 });
 ```
 
-#### Supplying the access token
+###### Supplying the access token
 
 ```js
 // in the constructor, assuming control of managing IAM token

UPGRADE-4.0.md

@@ -1,5 +1,7 @@
 # Upgrading to watson-developer-cloud@4.0
 - [Breaking changes]
+   - [Methods no longer return stream]
+   - [Error Handling Compatibility]
    - [Removed Services]
    - [Constructor Compatibility]
    - [Discovery Compatibility]
@@ -12,6 +14,21 @@
 
 
 ## Breaking changes
+### Methods no longer return stream
+Previously, if a callback was not provided, each service method would return a pipeable stream. Now, this will no longer happen. This should not affect many users, as authenticating with IAM already prevented methods from returning streams.
+
+### Error Handling Compatibility
+The logic that formats errors returned from a service has been changed. That means that the Error object returned now has a different structure. If there is logic in your code that parses the error returned from service methods, this will need to change. The new structure is outlined below.
+
+The object returned is of class `Error` and has the following properties:
+- `name`: Short title describing the error. Ex) 'Not Found'
+- `code`: HTTP status code. Ex) 404
+- `message`: More descriptive error message. Ex) Model not found.
+- `body`: Full error object returned by the service, stringified. If the object cannot be stringified due to a circular reference, it will be left as an object 
+- `headers`: Object containing response headers returned from the service, including the transaction id
+
+If a request is made but no response is received (very rare), `error.body` will be an instance of [HTTP.ClientRequest](https://nodejs.org/api/http.html#http_class_http_clientrequest).
+
 ### Removed Services
 The following services have been deprecated for an extended period of time and will no longer be supported in the SDK:
 - Dialog