docs: add documentation in the readme for reading credentials file

Author: dpopp07

README.md

@@ -85,14 +85,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.
 
@@ -101,7 +142,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
@@ -113,7 +154,7 @@ const discovery = new DiscoveryV1({
 });
 ```
 
-#### Supplying the access token
+###### Supplying the access token
 
 ```js
 // in the constructor, assuming control of managing IAM token

examples/.env.example

@@ -0,0 +1,2 @@
+NATURAL_LANGUAGE_UNDERSTANDING_USERNAME=username
+NATURAL_LANGUAGE_UNDERSTANDING_PASSWORD=password

lib/read-credentials-file.ts

@@ -10,13 +10,19 @@ export function readCredentialsFile() {
   // it should be the path to the file
 
   const givenFilepath: string = process.env['IBM_CREDENTIALS_FILE'] || '';
-  const homeDir: string = os.homedir();
-  const workingDir: string = process.cwd();
+  const homeDir: string = constructFilepath(os.homedir());
+  const workingDir: string = constructFilepath(process.cwd());
 
   let filepathToUse: string;
 
-  if (givenFilepath && fileExistsAtPath(givenFilepath)) {
-    filepathToUse = givenFilepath;
+  if (givenFilepath) {
+    if (fileExistsAtPath(givenFilepath)) {
+      // see if user gave a path to a file named something other than `ibm-credentials.env`
+      filepathToUse = givenFilepath;
+    } else if (fileExistsAtPath(constructFilepath(givenFilepath))) {
+      // see if user gave a path to the directory where file is located
+      filepathToUse = constructFilepath(givenFilepath);
+    }
   } else if (fileExistsAtPath(homeDir)) {
     filepathToUse = homeDir;
   } else if (fileExistsAtPath(workingDir)) {
@@ -26,14 +32,13 @@ export function readCredentialsFile() {
     return {};
   }
 
-  const credsFile = fs.readFileSync(constructFilepath(filepathToUse));
+  const credsFile = fs.readFileSync(filepathToUse);
 
   return dotenv.parse(credsFile);
 }
 
 export function fileExistsAtPath(filepath): boolean {
-  filepath = constructFilepath(filepath);
-  return fs.existsSync(filepath);
+  return fs.existsSync(filepath) && fs.lstatSync(filepath).isFile();
 }
 
 export function constructFilepath(filepath): string {

test/unit/baseService.test.js

@@ -166,7 +166,7 @@ describe('BaseService', function() {
   });
 
   it('should prefer hard-coded credentials over ibm credentials file', function() {
-    process.env.IBM_CREDENTIALS_FILE = __dirname + '../resources/ibm-credentials.env';
+    process.env.IBM_CREDENTIALS_FILE = __dirname + '/../resources/ibm-credentials.env';
     const instance = new TestService({ username: 'user', password: 'pass' });
     const actual = instance.getCredentials();
     const expected = {

test/unit/readCredentialsFile.test.js

@@ -1,14 +1,16 @@
 'use strict';
 
 const readCredentialsFunctions = require('../../lib/read-credentials-file');
+const constructFilepath = readCredentialsFunctions.constructFilepath;
+const fileExistsAtPath = readCredentialsFunctions.fileExistsAtPath;
+const readCredentialsFile = readCredentialsFunctions.readCredentialsFile;
 
 describe('read ibm credentials file', () => {
-  const locationOfActualFile = __dirname + '/../resources/ibm-credentials.env';
+  const locationOfActualFile = __dirname + '/../resources';
   process.env.IBM_CREDENTIALS_FILE = locationOfActualFile;
 
   describe('construct filepath', () => {
     const expectedPath = '/path/to/file/ibm-credentials.env';
-    const constructFilepath = readCredentialsFunctions.constructFilepath;
 
     it('should build filepath from absolute path', () => {
       const path = constructFilepath('/path/to/file/');
@@ -24,22 +26,21 @@ describe('read ibm credentials file', () => {
       const path = constructFilepath(expectedPath);
       expect(path).toBe(expectedPath);
     });
-
-    it('should append filename to existing filename', () => {
-      const path = constructFilepath('/path/to/file/wrong-file.env');
-      expect(path).toBe('/path/to/file/wrong-file.env/ibm-credentials.env');
-    });
   });
 
   describe('file exists at path', () => {
-    const fileExistsAtPath = readCredentialsFunctions.fileExistsAtPath;
     it('should return true if the file exists at the given path', () => {
-      const path = locationOfActualFile;
+      const path = constructFilepath(locationOfActualFile);
       expect(fileExistsAtPath(path)).toBe(true);
     });
 
+    it('should return false if path is correct but is not a file', () => {
+      const path = locationOfActualFile;
+      expect(fileExistsAtPath(path)).toBe(false);
+    });
+
     it('should return false if the file does not exist at the given path', () => {
-      const path = process.cwd();
+      const path = constructFilepath(process.cwd());
       expect(fileExistsAtPath(path)).toBe(false);
     });
 
@@ -50,13 +51,19 @@ describe('read ibm credentials file', () => {
   });
 
   describe('read credentials file', () => {
-    const readCredentialsFile = readCredentialsFunctions.readCredentialsFile;
     it('should return credentials as an object if file exists', () => {
       const obj = readCredentialsFile();
       expect(obj.TEST_USERNAME).toBe('123456789');
       expect(obj.TEST_PASSWORD).toBe('abcd');
     });
 
+    it('should return credentials as an object for alternate filename', () => {
+      process.env['IBM_CREDENTIALS_FILE'] = __dirname + '/../../examples/.env.example';
+      const obj = readCredentialsFile();
+      expect(obj.NATURAL_LANGUAGE_UNDERSTANDING_USERNAME).toBe('username');
+      expect(obj.NATURAL_LANGUAGE_UNDERSTANDING_PASSWORD).toBe('password');
+    });
+
     it('should return empty object if file is not found', () => {
       delete process.env['IBM_CREDENTIALS_FILE'];
       const obj = readCredentialsFile();