Resolving review comments, Adding polyfilling for node env, Fixing issue #129

Author: muthurathinam-m

CONTRIBUTING.md

@@ -1,6 +1,4 @@
-Contribute to this documentation
-
-Thank you for your interest in our documentation!
+# Contributing
 
 * [Ways to contribute](#ways-to-contribute)
 * [Contribute using GitHub](#contribute-using-github)
@@ -101,10 +99,10 @@ To make the contribution process as seamless as possible, follow these steps.
 
 #### To create a new branch
 
-1.	Open Git Bash.
-2.	At the Git Bash command prompt, type `git pull upstream master:<new branch name>`. This creates a new branch locally that is copied from the latest MicrosoftGraph master branch.
-3.	At the Git Bash command prompt, type `git push origin <new branch name>`. This alerts GitHub to the new branch. You should now see the new branch in your fork of the repository on GitHub.
-4.	At the Git Bash command prompt, type `git checkout <new branch name>` to switch to your new branch.
+1.Open Git Bash.
+2.At the Git Bash command prompt, type `git pull upstream master:<new branch name>`. This creates a new branch locally that is copied from the latest MicrosoftGraph master branch.
+3.At the Git Bash command prompt, type `git push origin <new branch name>`. This alerts GitHub to the new branch. You should now see the new branch in your fork of the repository on GitHub.
+4.At the Git Bash command prompt, type `git checkout <new branch name>` to switch to your new branch.
 
 #### Add new content or edit existing content
 
@@ -117,7 +115,7 @@ The files in `C:\Users\<yourusername>\<repo name>` are a working copy of the new
     git add .
     git commit -v -a -m "<Describe the changes made in this commit>"
 
-The `add` command adds your changes to a staging area in preparation for committing them to the repository. The period after the `add` command specifies that you want to stage all of the files that you added or modified, checking subfolders recursively. (If you don't want to commit all of the changes, you can add specific files. You can also undo a commit. For help, type `git add -help` or `git status`.)
+The `add` command adds your changes to a staging area in preparation for committing them to the repository. The period after the `add` command specifies that you want to stage all of the files that you added or modified, checking sub folders recursively. (If you don't want to commit all of the changes, you can add specific files. You can also undo a commit. For help, type `git add -help` or `git status`.)
 
 The `commit` command applies the staged changes to the repository. The switch `-m` means you are providing the commit comment in the command line. The -v and -a switches can be omitted. The -v switch is for verbose output from the command, and -a does what you already did with the add command.
 
@@ -129,13 +127,13 @@ When you're finished with your work and are ready to have it merged into the mai
 
 #### To submit a pull request to the main repository
 
-1.	In the Git Bash command prompt, type `git push origin <new branch name>`. In your local repository, `origin` refers to your GitHub repository that you cloned the local repository from. This command pushes the current state of your new branch, including all commits made in the previous steps, to your GitHub fork.
-2.	On the GitHub site, navigate in your fork to the new branch.
-3.	Choose the **Pull Request** button at the top of the page.
-4.	Verify the Base branch is `microsoftgraph/<repo name>@master` and the Head branch is `<your username>/<repo name>@<branch name>`.
-5.	Choose the **Update Commit Range** button.
-6.	Add a title to your pull request, and describe all the changes you're making.
-7.	Submit the pull request.
+1.In the Git Bash command prompt, type `git push origin <new branch name>`. In your local repository, `origin` refers to your GitHub repository that you cloned the local repository from. This command pushes the current state of your new branch, including all commits made in the previous steps, to your GitHub fork.
+2.On the GitHub site, navigate in your fork to the new branch.
+3.Choose the **Pull Request** button at the top of the page.
+4.Verify the Base branch is `microsoftgraph/<repo name>@master` and the Head branch is `<your username>/<repo name>@<branch name>`.
+5.Choose the **Update Commit Range** button.
+6.Add a title to your pull request, and describe all the changes you're making.
+7.Submit the pull request.
 
 One of the site administrators will process your pull request. Your pull request will surface on the microsoftgraph/<repo name> site under Issues. When the pull request is accepted, the issue will be resolved.
 

README.md

@@ -17,9 +17,27 @@ The Microsoft Graph JavaScript client library is a lightweight wrapper around th
 npm install @microsoft/microsoft-graph-client
 ```
 
+import `@microsoft/microsoft-graph-client` into your module.
+
+```typescript
+import { Client } from "@microsoft/microsoft-graph-client";
+```
+
+In case your environment have support for or have polyfill for [Fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) [[support](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API#Browser_compatibility)] and [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) [[support](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise#Browser_compatibility)], import `./node_modules/@microsoft/microsoft-graph-client/lib/src/core/index` into your module which doesn't have polyfills for these.
+
+```typescript
+import {Client} from "./node_modules/@microsoft/microsoft-graph-client/lib/src/core/index";
+```
+
 ### Via Script Tag
 
-Include [lib/graph-js-sdk-web.js](./lib/graph-js-sdk-web.js) in your page.
+Include [lib/graph-js-sdk-core.js](./lib/graph-js-sdk-core.js) in your page.
+
+```HTML
+<script type="text/javascript" src="graph-js-sdk-core.js"></script>
+```
+
+In case your browser doesn't have support for [Fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) [[support](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API#Browser_compatibility)] and [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) [[support](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise#Browser_compatibility)], you can polyfill them and include as above or you can use [lib/graph-js-sdk-web.js](./lib/graph-js-sdk-web.js) which includes polyfills.
 
 ```HTML
 <script type="text/javascript" src="graph-js-sdk-web.js"></script>
@@ -33,7 +51,7 @@ Register your application to use Microsoft Graph API using one of the following
 supported authentication portals:
 
 * [Microsoft Application Registration Portal](https://apps.dev.microsoft.com):
-  Register a new application that works with Microsoft Account and/or
+  Register a new application that works with Microsoft Accounts and/or
   organizational accounts using the unified V2 Authentication Endpoint.
 * [Microsoft Azure Active Directory](https://manage.windowsazure.com): Register
   a new application in your tenant's Active Directory to support work or school
@@ -42,9 +60,37 @@ supported authentication portals:
 ### 2. Authenticate for the Microsoft Graph service
 
 The Microsoft Graph JavaScript Client Library has an adapter implementation ([MSALAuthenticationProvider](src/MSALAuthenticationProvider.ts)) for [MSAL](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/lib/msal-core) (Microsoft Authentication Library) which takes care of getting the `accessToken`. MSAL library does not ship with this library, user have to include it externally (For including MSAL, refer [this](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/lib/msal-core#installation)).
-Creating an instance of MSALAuthenticationProvider,
+
+> **Note:** MSAL is supported only for frontend applications, for server-side authentication you have to implement your own AuthenticationProvider. Refer implementing [Custom Authentication Provider](./docs/CustomAuthenticationProvider.md).
+
+#### Creating an instance of MSALAuthenticationProvider in browser environment
+
+Refer devDependencies in [package.json](./package.json) for the compatible msal version and update that version in below.
+
+```html
+<script src="https://secure.aadcdn.microsoftonline-p.com/lib/<version>/js/msal.min.js"></script>
+```
+
+```typescript
+const clientID = 'your_client_id'; // Client Id of the registered application
+const graphScopes = ["user.read", "mail.send"]; // An array of graph scopes
+const options = { // An Optional options for initializing the MSAL @see https://github.com/AzureAD/microsoft-authentication-library-for-js/wiki/MSAL-basics#configuration-options
+    redirectUri: "Your redirect URI"
+};
+const authProvider = new MicrosoftGraph.MSALAuthenticationProvider(clientId, scopes, options);
+```
+
+#### Creating an instance of MSALAuthenticationProvider in node environment
+
+Refer devDependencies in [package.json](./package.json) for the compatible msal version and update that version in below.
+
+```cmd
+npm install msal@<version>
+```
 
 ```typescript
+import { MSALAuthenticationProvider } from "./node_modules/@microsoft/microsoft-graph-client/lib/src/MSALAuthenticationProvider";
+
 const clientID = 'your_client_id'; // Client Id of the registered application
 const graphScopes = ["user.read", "mail.send"]; // An array of graph scopes
 const options = { // An Optional options for initializing the MSAL @see https://github.com/AzureAD/microsoft-authentication-library-for-js/wiki/MSAL-basics#configuration-options
@@ -53,26 +99,40 @@ const options = { // An Optional options for initializing the MSAL @see https://
 const authProvider = new MSALAuthenticationProvider(clientId, scopes, options);
 ```
 
-User can integrate own preferred authentication library by implementing `IAuthenticationProvider` interface.
+User can integrate own preferred authentication library by implementing `IAuthenticationProvider` interface. Refer implementing [Custom Authentication Provider](./docs/CustomAuthenticationProvider.md).
 
 ### 3. Initialize a Microsoft Graph Client object with an authentication provider
 
-An instance of the **Client** class handles requests to Microsoft Graph API and processing the responses. To create a new instance of this class, you need to provide an instance of [`IAuthenticationProvider`](src/IAuthenticationProvider.ts) which needs to be passed as a value for `authProvider` key in [`Options`](src/IOptions.ts) to a static initializer method `Client.init`.
+An instance of the **Client** class handles requests to Microsoft Graph API and processing the responses. To create a new instance of this class, you need to provide an instance of [`IAuthenticationProvider`](src/IAuthenticationProvider.ts) which needs to be passed as a value for `authProvider` key in [`ClientOptions`](src/IClientOptions.ts) to a static initializer method `Client.initWithMiddleware`.
+
+#### For browser environment
+
+```typescript
+const options = {
+    authProvider // An instance created from previous step
+};
+const Client = MicrosoftGraph.Client;
+const client = Client.initWithMiddleware(options);
+```
+
+#### For node environment
 
 ```typescript
+import { Client } from "@microsoft/microsoft-graph-client";
+
 const options = {
     authProvider // An instance created from previous step
 };
-const client = MicrosoftGraph.Client.init(options);
+const client = Client.initWithMiddleware(options);
 ```
 
-For more information on initializing client, refer [this](./docs/CreatingClientInstance.md).
+For more information on initializing client, refer [this document](./docs/CreatingClientInstance.md).
 
 ### 4. Make requests to the graph
 
-Once you have authentication setup and an instance of Client, you can begin to make calls to the service. All requests should be start with `client.api(path)` and end with an action.
+Once you have authentication setup and an instance of Client, you can begin to make calls to the service. All requests should be start with `client.api(path)` and end with an [action](./docs/Actions.md).
 
-Getting user details,
+Getting user details
 
 ```typescript
 try {
@@ -143,4 +203,4 @@ This project has adopted the [Microsoft Open Source Code of Conduct](https://ope
 
 ## Third Party Notices
 
-See [Third Party Notices](https://github.com/microsoftgraph/msgraph-sdk-javascript/blob/master/THIRD%20PARTY%20NOTICES) for information on the packages that are included in the [package.json](https://github.com/microsoftgraph/msgraph-sdk-javascript/blob/master/package.json)
+See [Third Party Notices](./THIRD%20PARTY%20NOTICES) for information on the packages that are included in the [package.json](./package.json)

THIRD PARTY NOTICES

@@ -2,6 +2,10 @@ This file is based on or incorporates material from the projects listed below (T
 reserves all other rights not expressly granted under this agreement, whether by implication, estoppel or otherwise.  
 
 tslib
+
+isomorphic-fetch
+
+es6-promise
 
 Provided for Informational Purposes Only 
 

docs/CreatingClientInstance.md

@@ -6,7 +6,7 @@ Initialization of the Client can be done in one of below two ways
 
 In order to instantiate a Client object, one has to pass in the `authProvider` or `middleware` chain in [ClientOptions](../src/IClientOptions.ts).
 
-### 1. Default Middleware chain
+### Option A. Default Middleware chain
 
 Pass an instance of a class which implementing [AuthenticationProvider](../src/IAuthenticationProvider.ts) interface as `authProvider` in [ClientOptions](../src/IClientOptions.ts), which will instantiate the Client with default set of middleware chain.
 
@@ -32,7 +32,7 @@ const client = Client.initWithMiddleware(clientOptions);
 
 Refer, [custom authentication provider](./CustomAuthenticationProvider.md) for more detailed information.
 
-### 2. Custom Middleware chain
+### Option B. Custom Middleware chain
 
 Want to have complete control over the request and the response objects, one can provide his own chain of middleware.
 Have to pass first middleware in the chain as `middleware` in [ClientOptions](../src/IClientOptions.ts).

docs/CustomMiddlewareChain.md

@@ -8,12 +8,10 @@ As name suggests it comes in middle of something and that is request and respons
 
 ### Implement Middlewares
 
-Create own set of middlewares by implementing [Middleware](../src/IMiddleware.ts) interface. Here two middlewares are created one for handling Logging and another for handling http request and response.
+Create a custom middleware pipeline by implementing the [Middleware](../src/IMiddleware.ts) interface. The following examples demonstrate how to create a custom logging middleware and how to create a custom http request a response handler.
 
 First middleware is passed with the context object containing request, and other middleware specific options. One has to explicitly make call to execute method of the next middleware with context object once the current middleware work is over.
 
-NOTE: Http message handler should set the response object in the context object.
-
 ```typescript
 // MyLoggingHandler.ts
 import { Middleware } from "@microsoft/microsoft-graph-client";
@@ -32,7 +30,7 @@ export class MyLoggingHandler implements Middleware {
                 url = context.request.url;
             }
             console.log(url);
-            await this.nextMiddleware.execute(context);
+            return await this.nextMiddleware.execute(context);
         } catch(error) {
             throw error;
         }
@@ -44,6 +42,8 @@ export class MyLoggingHandler implements Middleware {
 }
 ```
 
+> **Note:** Http message handler should set the response object in the context object.
+
 ```typescript
 // MyHttpMessageHandler.ts
 import { Middleware } from "@microsoft/microsoft-graph-client";
@@ -55,6 +55,7 @@ export class MyHttpMessageHandler implements Middleware {
             let response = await fetch(context.request, context.options);
             // Set the response back in the context
             context.response = response;
+            return;
         } catch (error) {
             throw error;
         }

docs/GettingRawResponse.md

@@ -2,29 +2,15 @@
 
 Steps for getting the raw response [i.e [Response Object](https://developer.mozilla.org/en-US/docs/Web/API/Response)]
 
-**Initialize the Client**
+## Initialize the Client
 
-```typescript
-const options = {
-    authProvider: yourAuthProvider
-};
-const client = MicrosoftGraph.Client.init(options);
-```
-
-**Save request to get the raw response before calling action**
-
-The graph request will be returned for all the method calls except for actions, because they makes call to the server, so have to save the copy of graph request instance before calling actions
-
-```typescript
-const graphRequest = client.api("/me").select("displayName")
-let response = await graphRequest.get();
-```
+Refer [this documentation](../CreatingClientInstance.md) for initializing the client.
 
-**Get the raw response**
+## Getting Raw Response by setting ResponseType
 
-Use `.getRawResponse()` method to get the raw response
+To get the raw response set the responseType of a request to ResponseType.RAW.
 
 ```typescript
-let rawResponse = graphRequest.getRawResponse();
+const rawResponse = client.api("/me").select("displayName").responseType(ResponseType.RAW).get();
 console.log(rawResponse);
 ```