docs: update upgrade docs with info about promises

Author: dpopp07

UPGRADE-4.0.md

@@ -15,7 +15,19 @@
 
 ## 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.
+Previously, if a callback was not provided, each service method would return a pipeable stream. Now, this will no longer happen. A Promise is returned instead. This should not affect many users, as authenticating with IAM already prevented methods from returning streams.
+
+### Response Handling Compatibility
+The entire response is received with the third callback (if using callbacks) or when using Promises with `return_response: true` set as a parameter. This response now has a different structure for consistency with the other Watson SDKs.
+
+The object returned has the following properties:
+- `data`: The body of the response
+- `headers`: The HTTP response headers
+- `status`: The HTTP status code
+- `statusText`: The HTTP status message
+- `request`: The actual request instance sent to the service
+- `config`: The parameters used to build the request
+
 
 ### 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.

lib/requestwrapper.ts

@@ -236,11 +236,13 @@ export function sendRequest(parameters, _callback) {
     paramsSerializer: params => {
       return querystring.stringify(params);
     },
+    // a custom httpsAgent is needed to support ICP
     httpsAgent: new https.Agent({ rejectUnauthorized }),
   };
 
   axios(requestParams)
     .then(res => {
+      // the other sdks use the interface `result` for the body
       _callback(null, res.data, res);
     })
     .catch(error => {

test/integration/assistant.v1.test.js

@@ -523,19 +523,21 @@ describe('assistant_integration', function() {
   });
 
   describe('getCounterexample()', function() {
-    it('should return a counterexample', function(done) {
+    it('should return a counterexample - using promise', function(done) {
       const params = {
         workspace_id: workspace1.workspace_id,
         text: counterexampleText,
       };
 
-      assistant.getCounterexample(params, function(err, result) {
-        if (err) {
+      assistant
+        .getCounterexample(params)
+        .then(result => {
+          expect(result.text).toBe(counterexampleText);
+          done();
+        })
+        .catch(err => {
           return done(err);
-        }
-        expect(result.text).toBe(counterexampleText);
-        done();
-      });
+        });
     });
   });
 

test/integration/text_to_speech.test.js

@@ -92,15 +92,22 @@ describe('text_to_speech_integration', function() {
       );
     });
 
-    it('listVoiceModels()', function(done) {
-      text_to_speech.listVoiceModels({}, function(err, response) {
-        // console.log(JSON.stringify(err || response, null, 2));
-        if (err) {
-          return done(err);
-        }
-        expect(Array.isArray(response.customizations)).toBe(true);
-        done();
-      });
+    it('should return promise with entire response if return_response is true (listVoiceModels)', function(done) {
+      text_to_speech
+        .listVoiceModels({ return_response: true })
+        .then(response => {
+          expect(Array.isArray(response.data.customizations)).toBe(true);
+          expect(response.data).toBeDefined();
+          expect(response.headers).toBeDefined();
+          expect(response.status).toBeDefined();
+          expect(response.statusText).toBeDefined();
+          expect(response.request).toBeDefined();
+          expect(response.config).toBeDefined();
+          done();
+        })
+        .catch(err => {
+          done(err);
+        });
     });
 
     it('listVoiceModels() with language', function(done) {