Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/gautamsi/ews-javascript-api

EWS API for TypeScript/JavaScript - ported from OfficeDev/ews-managed-api - node, cordova, meteor, Ionic, Electron, Outlook Add-Ins
https://github.com/gautamsi/ews-javascript-api

cordova ews ews-api exchange-web-services ionic ionic3 meteor outlook-addin

Last synced: 4 days ago
JSON representation

EWS API for TypeScript/JavaScript - ported from OfficeDev/ews-managed-api - node, cordova, meteor, Ionic, Electron, Outlook Add-Ins

Awesome Lists containing this project

README 

        
ews-javascript-api 

==================

## Exchange Web Service in JavaScript/TypeScript.



## Support

Contact @gautamsi for support. Use [![Gitter](https://badges.gitter.im/gautamsi/ews-javascript-api.svg)](https://gitter.im/gautamsi/ews-javascript-api?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) for 1:1 support and paid support. Also looking for sponsors to fund remaining development on this. 



===========================================================================================    

## Office 365 OAuth Support is built in

see demo repo https://github.com/ewsjs/oauth-demo which has working example - https://github.com/ewsjs/oauth-demo/blob/main/examples/msal-node-samples/auth-code/index.js to find out how to use oAuth Token from msal.



## March 2023 Update:

fixes and typing cleanups, see 0.12.0 below



## July 2019 Update:  

You can now use this in Ionic, Cordova, Browser based process (where CORS is disabled), Outlook Add-in or Mail apps. see [`ews-js-api-browser`](https://github.com/gautamsi/ews-js-api-browser) for more detail



>(planning to rename this to @ewsjs/ewsjs);



# Current State:

* Almost all methods in ExchangeService class is comple with respect to c# counterpart ([based on commit#31951f4 ](https://github.com/OfficeDev/ews-managed-api/commit/31951f456519786e41232fa9ff6a3ab20b56cac3)

    * some method skipped as they are not for client side code or are diaognostic methods. 

* Roadmap to 1.0 Beta:

    * ~~ReWrite XHR/Request and Promise see #94~~ done

    * ~~Rewrite Autodiscover code with fresh Promise approach, this code was my work in very beginning and poorly written, strategy and TypeScript features improved over time which this code isn't taking any advantage of.~~ done

    * use `async/await` and move to `@ewsjs/*` namespace

    * chain `@ewsjs/xhr` to wrap all exports from `@ewsjs/ews`

    * Add jsdoc comment to remaining exported class

* Roadmap to 1.0

    * fix bugs from Beta

    * complete code improvement based on diff from original snapshot

    * basic tests to be introduced to prevent breaking changes

    * Add documentation with sample code for each operation in ExchangeService methods

    * Integrate ntlm and cookies authentication code in main library 

* Beyond 1.0 

    * ~Add npm based typings support for lates TypeScript based workflow~ completed in `0.9.0`

    * minified version for any developer need 

    * String Null check to improve reliability, TypeScript 2.0 feature

    * Complete jsdoc comment in 

    * Complete code for new features introduced after the snapshot I was working on

    * Add OAuth authentication with Azure AD (needs admin created APP in Azure AD)

    * Break into components to have better performance and download

    * enable non Node scenarios

    * trimmed version for Outlook Mail APP supported EWS calls  



===========================================================================================



# Whats new v0.15.0

* Added helper class for Exchange Online/Office 365 OAuth with Exchange RBAC with Apps Support (This is latest Microsoft Guideline)

    - This RBAC method is APP only which uses Client Credential Flow and not user specific token

    - You can still get user specific access token by delegation and pass token to `OAuthCredentials`

* updated `@ewsjs/xhr` version to `3.1.0` (dependency audit update)



```ts

import { ExchangeService, OAuthCredentials, ExchangeVersion } from "ews-javascript-api";

import { EwsOAuthHelper } from "ews-javascript-api/lib/EwsOAuthHelper";



const oAuthHelper = new EwsOAuthHelper({ clientId: '', clientSecret: '', tenantId: '' });

const token = await oAuthHelper.getAppAccessToken();

const ews = new ExchangeService(ExchangeVersion.);

ews.Credentials =new OAuthCredentials(token.accessToken);

await ews.();

```

> you will still need to update expired access token by calling `oAuthHelper.getAppAccessToken()`, you can safely run this when you want to use ews as this can return cached token which is not expired



# Whats new v0.14.0

* Updated implementation of `@ewsjs/ntlm-client` to continue support ntlm with node 18+ (dependency of `@ewsjs/xhr`)

* This fixes latest support for ntlm with node 18/20+

* This also fixes security warning of `new Buffer(...)` in the underlying library



# Whats new v0.13.0 **BREAKING CHANGES**

* Security update: removed fetch and bluebird dependency

* removed `XHRDefault` and `ConfigurationApi.ConfigurePromise` exported methods

* Exported XHRApi from `@ewsjs/xhr` to make it easier to use

* Using default implementation of `XhrApi` from `@ewsjs/xhr` instead of using `fetch`



# Whats new v0.12.0

* fixed `WellKnownFolderNames` to be `StringPropertyDefinition` type instead of `Generic` which microsoft has changed long back. Part of this was fixed by #414 (thanks @klinki)

* fixes #416 and also cleans up other typing issues

* Security update: updated all dependency to latest version.



# Whats new v0.11.0

* **BREAKING** dependencies upgraded to latest version of commonjs module (still avoiding pure esm modules). The code is now compiled to es6 target, must use nodejs version >= 10

* Security update: updated all dependency to latest version.



# Whats new v0.10.0

* new/fix: #324 Autodiscover is back again, improved and supports DNS fallback using Autodiscover SRV records

* new: #320 Allow access to `HttpResponseHeaders`, you can use `.HttpResponseHeaders` to get fresh header from last call to ews service.

  *  you can also add a delegate (callback) for `.OnResponseHeadersCaptured` which is called after each call to service and when headers are returned.



* **Breaking Changes**:  `.HttpHeaders` is now Disctionary instance, compatible with c# disctionary. you can no longer do `service.HttpHeaders[] = value`. do this instead `service.HttpHeaders.Add("header", "value"); `



* fix: #322 you can now delete tasks properly



[See older change in CHANGELOG.md](./CHANGELOG.md)



===========================================================================================



EWS managed API for TypeScript/JavaScript - code ported from OfficeDev/ews-managed-api. availbale for nodejs, browser and mobile devices (cordova).  



Pluggable XHRApi adapter to replace client (browser) based XHR call with server brokered call (example coming soon). Example Ruby on rails, PHP or any server side framework where c# or nodejs is not available



Works with **Office 365/Exchange Online** and on-premises Exchange (2007 - 2016)



## Authentication

* Basic - inbuilt

* OAuth - inbuilt (see https://stackoverflow.com/a/43785262/5884960 for more details on how to use.)

* NTLM and NTLMv2 - using [@ewsjs/xhr](https://github.com/ewsjs/xhr) 

* Cookies/FBA Authentication with TMG/ISA - using [@ewsjs/xhr](https://github.com/ewsjs/xhr) 



> use SSL for basic authentication  

NTLM and Cookies Authentication works with nodejs only



> **NTLM** issue with `invalid tagName` gibrish character is due to gzip encoding, see #334. 

> 

> **Solution** use `gzip: true` in `XhrApi({ gzip: true })` constructor options of `@ewsjs/xhr`.



## Modules

* commonjs module for NodeJs

* AMD module for other scenarios* (not documented yet)



~~All http call is wrapped in promise using default BlueBird promise.  You can also interchange compatible promise api.~~

Code sample from [EWS Managed API 2.1.](https://msdn.microsoft.com/en-us/library/office/jj536567.aspx) should work with little modificaion to Promise format   



## async/await latest nodejs

You can also leverage new async/await feature of nodejs (>7.0.6) or in TypeScript transpilation with es5/es6 code.  



## Documentation

Api document generated using TypeDoc and is hosted at [ews-javascript-api.github.io/api](http://ews-javascript-api.github.io/api).  ** outdated

Check [Wiki](https://github.com/gautamsi/ews-javascript-api/wiki) for more details



keep track of what is coming in [backlog](https://github.com/gautamsi/ews-javascript-api/milestones/backlog), keep eye on [milestones](https://github.com/gautamsi/ews-javascript-api/milestones) when I start working on it 



# Getting Started

## install

```shell

[sudo] npm install ews-javascript-api

``` 



## use

```javascript

//classic Javascript style

var ews = require('ews-javascript-api');

var exch = new ews.ExchangeService(ews.ExchangeVersion.Exchange2013);

//ES6 TypeScript style

import {ExchangeService, AutodiscoverService, Folder, Item, ExchangeVersion} from "ews-javascript-api";

var exch = new ExchangeService(ExchangeVersion.Exchange2013);

```

## Autodiscover user settings (** Working again as of 0.10 **)

```javascript

//import ews module

var ews = require('ews-javascript-api');

//create AutodiscoverService object

var autod = new ews.AutodiscoverService(new ews.Uri("https://autodiscover-s.outlook.com/autodiscover/autodiscover.svc"), ews.ExchangeVersion.Exchange2010);

//you can omit url and it will autodiscover the url, version helps throw error on client side for unsupported operations.example - //var autod = new ews.AutodiscoverService(ews.ExchangeVersion.Exchange2010);

//set credential for service

autod.Credentials = new ews.WebCredentials("userName", "password");

//create array to include list of desired settings

var settings = [

ews.UserSettingName.InternalEwsUrl,

ews.UserSettingName.ExternalEwsUrl,

ews.UserSettingName.UserDisplayName,

ews.UserSettingName.UserDN,

ews.UserSettingName.EwsPartnerUrl,

ews.UserSettingName.DocumentSharingLocations,

ews.UserSettingName.MailboxDN,

ews.UserSettingName.ActiveDirectoryServer,

ews.UserSettingName.CasVersion,

ews.UserSettingName.ExternalWebClientUrls,

ews.UserSettingName.ExternalImap4Connections,

ews.UserSettingName.AlternateMailboxes

];

//get the setting

autod.GetUserSettings(["[email protected]", "[email protected]"], settings)

.then(function (response) {

    //do what you want with user settings    

    var tabcount = 0;

    var tabs = function () { return ews.StringHelper.Repeat("\t", tabcount); };

    console.log(autod.Url.ToString());

	//uncoment next line to see full response from autodiscover, you will need to add var util = require('util');

	//console.log(util.inspect(response, { showHidden: false, depth: null, colors: true }));

    for (var _i = 0, _a = response.Responses; _i < _a.length; _i++) {

        var resp = _a[_i];

        console.log(ews.StringHelper.Format("{0}settings for email: {1}", tabs(), resp.SmtpAddress));

        tabcount++;

        for (var setting in resp.Settings) {

            console.log(ews.StringHelper.Format("{0}{1} = {2}", tabs(), ews.UserSettingName[setting], resp.Settings[setting]));

        }

        tabcount--;

    }

}, function (e) {

    //log errors or do something with errors

});

```



## Example EWS operations

Example of user availability

```javascript

var ews = require('ews-javascript-api');

//create ExchangeService object

var exch = new ews.ExchangeService(ews.ExchangeVersion.Exchange2013);

exch.Credentials = new ews.WebCredentials("userName", "password");

//set ews endpoint url to use

exch.Url = new ews.Uri("https://outlook.office365.com/Ews/Exchange.asmx"); // you can also use exch.AutodiscoverUrl



var attendee =[ new ews.AttendeeInfo("[email protected]"), new ews.AttendeeInfo("[email protected]")];

//create timewindow object o request avaiability suggestions for next 48 hours, DateTime and TimeSpan object is created to mimic portion of .net datetime/timespan object using momentjs

var timeWindow = new ews.TimeWindow(ews.DateTime.Now, ews.DateTime.Now.AddDays(2)); 

exch.GetUserAvailability(attendee, timeWindow, ews.AvailabilityData.FreeBusyAndSuggestions)

.then(function (availabilityResponse) {

    //do what you want with user availability

}, function (errors) {

    //log errors or do something with errors

});

        

```



# Use with React Native



there is some issues with how react native exposes native browser methods, here are changes needs to be done to us `ews-js-api-browser` with react native. 

    Add following lines to some place before requiring `ews-js-api-browser`. you need to use `@xmldom/xmldom` and `base-64` packages.

```js

if (!global.DOMParser) {

    global.DOMParser = require('@xmldom/xmldom').DOMParser;

}

if (!global.atob || !global.btoa) {

    global.atob = require('base-64').decode;

    global.btoa = require('base-64').encode;

}

```



# Porting status



Review Core/ExchangeService methods in api document, Any method not marked private oe internal (internal marker is in description of method) is posted and can be used, open issue if it doe snot work



## List of ExchangeService methods available  

> ArchiveItems  

AutodiscoverUrl  

BindToGroupItems  

BindToItems  

ConvertId   

ConvertIds   

CopyItems  

CreateItems  

DeleteItems  

ExpandGroup  

FindAppointments  

FindFolders  

FindItems  

GetAttachments  

GetClientAccessToken   

GetPasswordExpirationDate  

GetRoomLists  

GetRooms   

GetUserAvailability  

GetUserOofSettings  

GetUserOofSettings   

LoadPropertiesForItems  

MarkAsJunk  

MoveItems  

ResolveName  

SetTeamMailbox   

SetUserOofSettings 

SetUserOofSettings   

SubscribeToPullNotifications   

SubscribeToStreamingNotifications   

SubscribeToStreamingNotificationsOnAllFolders  

SyncFolderHierarchy   

SyncFolderItems  

UnpinTeamMailbox   

UpdateItems  

GetInboxRules   

UpdateInboxRules   

AddDelegates   

GetDelegates  

RemoveDelegates   

UpdateDelegates   

GetUserRetentionPolicyTags    

FindConversation   

FindGroupConversation   

GetConversationItems   

GetGroupConversationItems   

EnableAlwaysCategorizeItemsInConversations   

DisableAlwaysCategorizeItemsInConversations   

EnableAlwaysDeleteItemsInConversations   

DisableAlwaysDeleteItemsInConversations   

EnableAlwaysMoveItemsInConversations   

DisableAlwaysMoveItemsInConversations   

MoveItemsInConversations   

CopyItemsInConversations   

DeleteItemsInConversations   

SetReadStateForItemsInConversations   

SetRetentionPolicyForItemsInConversations   

SetFlagStatusForItemsInConversations    

GetAppManifests    

GetAppMarketplaceUrl   

DisableApp   

InstallApp   

UninstallApp   

GetDiscoverySearchConfiguration   

GetHoldOnMailboxes   

GetNonIndexableItemDetails   

GetNonIndexableItemStatistics   

GetSearchableMailboxes   

SearchMailboxes   

SetHoldOnMailboxes   



## List of Folder object methods available



> BindToFolder  

CopyFolder  

CreateFolder  

DeleteFolder  

EmptyFolder  

FindFolders  

FindItems  

Load  

LoadPropertiesForFolder  

MarkAllItemsAsRead  

MarkAllItemsAsUnread  

RemoveExtendedProperty  

SetExtendedProperty  

MoveFolder  

Save  

UpdateFolder 



## List of Item object methods available



>ArchiveItem  

BindToItem  

CopyItem[s]  

CreateItem  

DeleteItem[s]  

FindAppointments  

FindItems  

LoadPropertiesForItems  

MarkAsJunk  

MoveItem  

SendItem  

Save  

UpdateItem[s]   

RemoveExtendedProperty  

SetExtendedProperty  

AcceptTentatively  *[Appointment]*  

AcceptTentatively  *[Appointment]*  

Decline            *[Appointment]*   



## Use in Cordova

AMD module for require.js to be included in build system, bower module and related documentation will be published.



# Tests

in progress....



# License

Licensed under MIT