search

gautamsi / ews-javascript-api

EWS API for TypeScript/JavaScript - ported from OfficeDev/ews-managed-api - node, cordova, meteor, Ionic, Electron, Outlook Add-Ins
MIT License
282 stars 73 forks source link
cordova ews ews-api exchange-web-services ionic ionic3 meteor outlook-addin

readme

ews-javascript-api

Exchange Web Service in JavaScript/TypeScript.

Support

Contact @gautamsi for support. Use Gitter 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 for more detail

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

Current State:

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

Whats new v0.15.0

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.<method>();

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

Whats new v0.13.0 BREAKING CHANGES

Whats new v0.12.0

Whats new v0.11.0

Whats new v0.10.0

See older change in 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

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

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. 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. ** outdated Check Wiki for more details

keep track of what is coming in backlog, keep eye on milestones when I start working on it

Getting Started

install

[sudo] npm install ews-javascript-api

use

//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 )

//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(["email1@domain.com", "email2@domain.com"], 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

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("email1@domain.com"), new ews.AttendeeInfo("email2@domain.com")];
//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.

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