nylas 6.5.1 → 7.0.0-beta.0

package/README.md

@@ -20,7 +20,7 @@ Here are some resources to help you get started:
 
 ## ⚙️ Install
 
-To run the Nylas Node SDK, you will first need to have [Node](https://nodejs.org/en/download/) and [npm](https://www.npmjs.com/get-npm) installed on your machine.
+To install the Nylas Node SDK, you will first need to have [Node](https://nodejs.org/en/download/) and [npm](https://www.npmjs.com/get-npm) installed on your machine.
 
 Then, head to the nearest command line and run the following:
 `npm install nylas`
@@ -37,22 +37,26 @@ npm install
 
 ## ⚡️ Usage
 
-Every resource (i.e., messages, events, contacts) is accessed via an instance of `Nylas`. Before making any requests, be sure to call `config` and initialize the `Nylas` instance with your `clientId` and `clientSecret`. Then, call `with` and pass it your `accessToken`. The `accessToken` allows `Nylas` to make requests for a given account's resources.
+The SDK entrypoint and application resources (i.e., application accounts, authentication, webhooks) is accessed via an instance of `Nylas`. You can initialize a `Nylas` instance with your `clientId` and `clientSecret`.
 
 ```javascript
 const Nylas = require('nylas');
 
-Nylas.config({
+const nylasClient = new Nylas({
   clientId: CLIENT_ID,
   clientSecret: CLIENT_SECRET,
 });
+```
+
+Every account resource (i.e., messages, events, contacts) is accessed via an instance of `NylasConnection`. To initialize an instance of `NylasConnection`, call `with` on your `Nylas` instance and pass it your `accessToken`.
 
-const nylas = Nylas.with(ACCESS_TOKEN);
+```javascript
+const nylasConnection = nylasClient.with(ACCESS_TOKEN);
 ```
 
 Then, you can use Nylas to access information about a user's account:
 ```javascript
-nylas.threads.list({}).then(threads => {
+nylasConnection.threads.list().then(threads => {
   console.log(threads.length);
 });
 ```

package/lib/config.d.ts

@@ -1,3 +1,6 @@
+import { WebhookTriggers } from './models/webhook';
+import ExpressBinding from './server-bindings/express-binding';
+import AccessToken from './models/access-token';
 export declare let apiServer: string | null;
 export declare function setApiServer(newApiServer: string | null): void;
 export declare let clientSecret: string;
@@ -15,3 +18,53 @@ export declare type AuthenticateUrlConfig = {
     provider?: string;
     scopes?: string[];
 };
+export declare enum Region {
+    Us = "us",
+    Canada = "canada",
+    Ireland = "ireland",
+    Australia = "australia",
+    Staging = "staging"
+}
+export declare const DEFAULT_REGION = Region.Us;
+export declare const regionConfig: {
+    us: {
+        nylasAPIUrl: string;
+        dashboardApiUrl: string;
+        callbackDomain: string;
+        websocketDomain: string;
+        telemetryApiUrl: string;
+    };
+    canada: {
+        nylasAPIUrl: string;
+        dashboardApiUrl: string;
+        callbackDomain: string;
+        websocketDomain: string;
+        telemetryApiUrl: string;
+    };
+    ireland: {
+        nylasAPIUrl: string;
+        dashboardApiUrl: string;
+        callbackDomain: string;
+        websocketDomain: string;
+        telemetryApiUrl: string;
+    };
+    australia: {
+        nylasAPIUrl: string;
+        dashboardApiUrl: string;
+        callbackDomain: string;
+        websocketDomain: string;
+        telemetryApiUrl: string;
+    };
+    staging: {
+        nylasAPIUrl: string;
+        dashboardApiUrl: string;
+        callbackDomain: string;
+        websocketDomain: string;
+        telemetryApiUrl: string;
+    };
+};
+export declare const DEFAULT_WEBHOOK_TRIGGERS: WebhookTriggers[];
+export declare const ServerBindings: {
+    express: typeof ExpressBinding;
+};
+export declare type ExchangeCodeForTokenCallback = (error: Error | null, accessToken?: AccessToken) => void;

package/lib/config.js

@@ -1,5 +1,11 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+var _a;
 Object.defineProperty(exports, "__esModule", { value: true });
+var webhook_1 = require("./models/webhook");
+var express_binding_1 = __importDefault(require("./server-bindings/express-binding"));
 exports.apiServer = null;
 function setApiServer(newApiServer) {
     exports.apiServer = newApiServer;
@@ -10,3 +16,53 @@ function setClientSecret(newClientSecret) {
     exports.clientSecret = newClientSecret;
 }
 exports.setClientSecret = setClientSecret;
+var Region;
+(function (Region) {
+    Region["Us"] = "us";
+    Region["Canada"] = "canada";
+    Region["Ireland"] = "ireland";
+    Region["Australia"] = "australia";
+    Region["Staging"] = "staging";
+})(Region = exports.Region || (exports.Region = {}));
+exports.DEFAULT_REGION = Region.Us;
+exports.regionConfig = (_a = {},
+    _a[Region.Us] = {
+        nylasAPIUrl: 'https://api.nylas.com',
+        dashboardApiUrl: 'https://dashboard-api.nylas.com',
+        callbackDomain: 'cb.nylas.com',
+        websocketDomain: 'tunnel.nylas.com',
+        telemetryApiUrl: 'https://cli.nylas.com',
+    },
+    _a[Region.Canada] = {
+        nylasAPIUrl: 'https://canada.api.nylas.com',
+        dashboardApiUrl: 'https://canada.dashboard.nylas.com',
+        callbackDomain: 'cb.nylas.com',
+        websocketDomain: 'tunnel.nylas.com',
+        telemetryApiUrl: 'https://cli.nylas.com',
+    },
+    _a[Region.Ireland] = {
+        nylasAPIUrl: 'https://ireland.api.nylas.com',
+        dashboardApiUrl: 'https://ireland.dashboard.nylas.com',
+        callbackDomain: 'cb.nylas.com',
+        websocketDomain: 'tunnel.nylas.com',
+        telemetryApiUrl: 'https://cli.nylas.com',
+    },
+    _a[Region.Australia] = {
+        nylasAPIUrl: 'https://australia.api.nylas.com',
+        dashboardApiUrl: 'https://australia.dashboard.nylas.com',
+        callbackDomain: 'cb.nylas.com',
+        websocketDomain: 'tunnel.nylas.com',
+        telemetryApiUrl: 'https://cli.nylas.com',
+    },
+    _a[Region.Staging] = {
+        nylasAPIUrl: 'https://api-staging.nylas.com',
+        dashboardApiUrl: 'https://staging-dashboard.nylas.com',
+        callbackDomain: 'cb.nylas.com',
+        websocketDomain: 'tunnel.nylas.com',
+        telemetryApiUrl: 'https://cli.nylas.com',
+    },
+    _a);
+exports.DEFAULT_WEBHOOK_TRIGGERS = Object.values(webhook_1.WebhookTriggers);
+exports.ServerBindings = {
+    express: express_binding_1.default,
+};

package/lib/models/scheduler.d.ts

@@ -99,7 +99,7 @@ export declare type SchedulerBookingProperties = {
     calendarInviteToGuests?: boolean;
     cancellationPolicy?: string;
     confirmationEmailsToGuests?: boolean;
-    confirmationEmailToHost?: boolean;
+    confirmationEmailsToHost?: boolean;
     confirmationMethod?: string;
     minBookingNotice?: number;
     minBuffer?: number;
@@ -116,7 +116,7 @@ export declare class SchedulerBooking extends Model implements SchedulerBookingP
     calendarInviteToGuests?: boolean;
     cancellationPolicy?: string;
     confirmationEmailsToGuests?: boolean;
-    confirmationEmailToHost?: boolean;
+    confirmationEmailsToHost?: boolean;
     confirmationMethod?: string;
     minBookingNotice?: number;
     minBuffer?: number;

package/lib/models/scheduler.js

@@ -228,8 +228,8 @@ var SchedulerBooking = /** @class */ (function (_super) {
             modelKey: 'confirmationEmailsToGuests',
             jsonKey: 'confirmation_emails_to_guests',
         }),
-        confirmationEmailToHost: attributes_1.default.Boolean({
-            modelKey: 'confirmationEmailToHost',
+        confirmationEmailsToHost: attributes_1.default.Boolean({
+            modelKey: 'confirmationEmailsToHost',
             jsonKey: 'confirmation_emails_to_host',
         }),
         confirmationMethod: attributes_1.default.String({

package/lib/models/webhook.d.ts

@@ -8,6 +8,7 @@ export declare enum WebhookTriggers {
     AccountStopped = "account.stopped",
     AccountInvalid = "account.invalid",
     AccountSyncError = "account.sync_error",
+    MessageBounced = "message.bounced",
     MessageCreated = "message.created",
     MessageOpened = "message.opened",
     MessageUpdated = "message.updated",

package/lib/models/webhook.js

@@ -25,6 +25,7 @@ var WebhookTriggers;
     WebhookTriggers["AccountStopped"] = "account.stopped";
     WebhookTriggers["AccountInvalid"] = "account.invalid";
     WebhookTriggers["AccountSyncError"] = "account.sync_error";
+    WebhookTriggers["MessageBounced"] = "message.bounced";
     WebhookTriggers["MessageCreated"] = "message.created";
     WebhookTriggers["MessageOpened"] = "message.opened";
     WebhookTriggers["MessageUpdated"] = "message.updated";

package/lib/nylas.d.ts

@@ -5,28 +5,53 @@ import Connect from './models/connect';
 import RestfulModelCollection from './models/restful-model-collection';
 import ManagementModelCollection from './models/management-model-collection';
 import Webhook from './models/webhook';
-import { AuthenticateUrlConfig, NylasConfig } from './config';
+import { AuthenticateUrlConfig, ExchangeCodeForTokenCallback, NylasConfig } from './config';
 import AccessToken from './models/access-token';
 import ApplicationDetails, { ApplicationDetailsProperties } from './models/application-details';
 declare class Nylas {
-    static clientId: string;
-    static get clientSecret(): string;
-    static set clientSecret(newClientSecret: string);
-    static get apiServer(): string | null;
-    static set apiServer(newApiServer: string | null);
-    static accounts: ManagementModelCollection<ManagementAccount> | RestfulModelCollection<Account>;
-    static connect: Connect;
-    static webhooks: ManagementModelCollection<Webhook>;
-    static config(config: NylasConfig): Nylas;
-    static clientCredentials(): boolean;
-    static with(accessToken: string): NylasConnection;
-    static application(options?: ApplicationDetailsProperties): Promise<ApplicationDetails>;
-    static exchangeCodeForToken(code: string, callback?: (error: Error | null, accessToken?: string) => void): Promise<AccessToken>;
-    static urlForAuthentication(options: AuthenticateUrlConfig): string;
+    clientId: string;
+    get clientSecret(): string;
+    set clientSecret(newClientSecret: string);
+    get apiServer(): string | null;
+    set apiServer(newApiServer: string | null);
+    accounts: ManagementModelCollection<ManagementAccount> | RestfulModelCollection<Account>;
+    connect: Connect;
+    webhooks: ManagementModelCollection<Webhook>;
+    constructor(config: NylasConfig);
+    /**
+     * Checks if the Nylas instance has been configured with credentials
+     * @return True if the Nylas instance has been configured with credentials
+     */
+    clientCredentials(): boolean;
+    /**
+     * Configure a NylasConnection instance to access a user's resources
+     * @param accessToken The access token to access the user's resources
+     * @return The configured NylasConnection instance
+     */
+    with(accessToken: string): NylasConnection;
+    /**
+     * Return information about a Nylas application
+     * @param options Application details to overwrite
+     * @return Information about the Nylas application
+     */
+    application(options?: ApplicationDetailsProperties): Promise<ApplicationDetails>;
+    /**
+     * Exchange an authorization code for an access token
+     * @param code One-time authorization code from Nylas
+     * @param callback Callback before returning the access token
+     * @return The {@link AccessToken} object containing the access token and other information
+     */
+    exchangeCodeForToken(code: string, callback?: ExchangeCodeForTokenCallback): Promise<AccessToken>;
+    /**
+     * Build the URL for authenticating users to your application via Hosted Authentication
+     * @param options Configuration for the authentication process
+     * @return The URL for hosted authentication
+     */
+    urlForAuthentication(options: AuthenticateUrlConfig): string;
     /**
      * Revoke a single access token
      * @param accessToken The access token to revoke
      */
-    static revoke(accessToken: string): Promise<void>;
+    revoke(accessToken: string): Promise<void>;
 }
 export = Nylas;

package/lib/nylas.js

@@ -23,29 +23,8 @@ var webhook_1 = __importDefault(require("./models/webhook"));
 var access_token_1 = __importDefault(require("./models/access-token"));
 var application_details_1 = __importDefault(require("./models/application-details"));
 var Nylas = /** @class */ (function () {
-    function Nylas() {
-    }
-    Object.defineProperty(Nylas, "clientSecret", {
-        get: function () {
-            return config.clientSecret;
-        },
-        set: function (newClientSecret) {
-            config.setClientSecret(newClientSecret);
-        },
-        enumerable: true,
-        configurable: true
-    });
-    Object.defineProperty(Nylas, "apiServer", {
-        get: function () {
-            return config.apiServer;
-        },
-        set: function (newApiServer) {
-            config.setApiServer(newApiServer);
-        },
-        enumerable: true,
-        configurable: true
-    });
-    Nylas.config = function (config) {
+    function Nylas(config) {
+        this.clientId = '';
         if (config.apiServer && config.apiServer.indexOf('://') === -1) {
             throw new Error('Please specify a fully qualified URL for the API Server.');
         }
@@ -73,17 +52,51 @@ var Nylas = /** @class */ (function () {
             this.accounts = new restful_model_collection_1.default(account_1.default, conn);
         }
         return this;
-    };
-    Nylas.clientCredentials = function () {
+    }
+    Object.defineProperty(Nylas.prototype, "clientSecret", {
+        get: function () {
+            return config.clientSecret;
+        },
+        set: function (newClientSecret) {
+            config.setClientSecret(newClientSecret);
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Nylas.prototype, "apiServer", {
+        get: function () {
+            return config.apiServer;
+        },
+        set: function (newApiServer) {
+            config.setApiServer(newApiServer);
+        },
+        enumerable: true,
+        configurable: true
+    });
+    /**
+     * Checks if the Nylas instance has been configured with credentials
+     * @return True if the Nylas instance has been configured with credentials
+     */
+    Nylas.prototype.clientCredentials = function () {
         return this.clientId != null && this.clientSecret != null;
     };
-    Nylas.with = function (accessToken) {
+    /**
+     * Configure a NylasConnection instance to access a user's resources
+     * @param accessToken The access token to access the user's resources
+     * @return The configured NylasConnection instance
+     */
+    Nylas.prototype.with = function (accessToken) {
         if (!accessToken) {
             throw new Error('This function requires an access token');
         }
         return new nylas_connection_1.default(accessToken, { clientId: this.clientId });
     };
-    Nylas.application = function (options) {
+    /**
+     * Return information about a Nylas application
+     * @param options Application details to overwrite
+     * @return Information about the Nylas application
+     */
+    Nylas.prototype.application = function (options) {
         if (!this.clientId) {
             throw new Error('This function requires a clientId');
         }
@@ -106,7 +119,13 @@ var Nylas = /** @class */ (function () {
             return new application_details_1.default().fromJSON(res);
         });
     };
-    Nylas.exchangeCodeForToken = function (code, callback) {
+    /**
+     * Exchange an authorization code for an access token
+     * @param code One-time authorization code from Nylas
+     * @param callback Callback before returning the access token
+     * @return The {@link AccessToken} object containing the access token and other information
+     */
+    Nylas.prototype.exchangeCodeForToken = function (code, callback) {
         if (!this.clientId || !this.clientSecret) {
             throw new Error('exchangeCodeForToken() cannot be called until you provide a clientId and secret via config()');
         }
@@ -131,10 +150,11 @@ var Nylas = /** @class */ (function () {
                     errorMessage = body.message;
                 throw new Error(errorMessage);
             }
+            var accessToken = new access_token_1.default().fromJSON(body);
             if (callback) {
-                callback(null, body);
+                callback(null, accessToken);
             }
-            return new access_token_1.default().fromJSON(body);
+            return accessToken;
         }, function (error) {
             var newError = new Error(error.message);
             if (callback) {
@@ -143,7 +163,12 @@ var Nylas = /** @class */ (function () {
             throw newError;
         });
     };
-    Nylas.urlForAuthentication = function (options) {
+    /**
+     * Build the URL for authenticating users to your application via Hosted Authentication
+     * @param options Configuration for the authentication process
+     * @return The URL for hosted authentication
+     */
+    Nylas.prototype.urlForAuthentication = function (options) {
         if (!this.clientId) {
             throw new Error('urlForAuthentication() cannot be called until you provide a clientId via config()');
         }
@@ -172,15 +197,14 @@ var Nylas = /** @class */ (function () {
      * Revoke a single access token
      * @param accessToken The access token to revoke
      */
-    Nylas.revoke = function (accessToken) {
-        return Nylas.with(accessToken)
+    Nylas.prototype.revoke = function (accessToken) {
+        return this.with(accessToken)
             .request({
             method: 'POST',
             path: '/oauth/revoke',
         })
             .catch(function (err) { return Promise.reject(err); });
     };
-    Nylas.clientId = '';
     return Nylas;
 }());
 module.exports = Nylas;

package/lib/server-bindings/express-binding.d.ts

@@ -0,0 +1,18 @@
+import Nylas from '../nylas';
+import { RequestHandler, Router } from 'express';
+import { ServerBindingOptions, ServerBinding } from './server-binding';
+export default class ExpressBinding extends ServerBinding {
+    constructor(nylasClient: Nylas, options: ServerBindingOptions);
+    /**
+     * Middleware for the webhook endpoint so we can verify that Nylas is sending the events
+     */
+    webhookVerificationMiddleware(): RequestHandler;
+    /**
+     * Build middleware for an Express app with routes for:
+     * 1. '/nylas/webhook': Receiving webhook events, verifying its authenticity, and emitting webhook objects
+     * 2. '/nylas/generate-auth-url': Building the URL for authenticating users to your application via Hosted Authentication
+     * 3. '/nylas/exchange-mailbox-token': Exchange an authorization code for an access token
+     * @return The routes packaged as Express middleware
+     */
+    buildMiddleware(): Router;
+}

package/lib/server-bindings/express-binding.js

@@ -0,0 +1,163 @@
+"use strict";
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (b.hasOwnProperty(p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (_) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+var express_1 = __importDefault(require("express"));
+var server_binding_1 = require("./server-binding");
+var body_parser_1 = __importDefault(require("body-parser"));
+var routes_1 = require("../services/routes");
+var ExpressBinding = /** @class */ (function (_super) {
+    __extends(ExpressBinding, _super);
+    function ExpressBinding(nylasClient, options) {
+        return _super.call(this, nylasClient, options) || this;
+    }
+    /**
+     * Middleware for the webhook endpoint so we can verify that Nylas is sending the events
+     */
+    ExpressBinding.prototype.webhookVerificationMiddleware = function () {
+        var _this = this;
+        return function (req, res, next) {
+            var isVerified = _this.verifyWebhookSignature(req.header(server_binding_1.ServerBinding.NYLAS_SIGNATURE_HEADER), req.body);
+            if (!isVerified) {
+                return res
+                    .status(401)
+                    .send('X-Nylas-Signature failed verification 🚷 ');
+            }
+            next();
+        };
+    };
+    /**
+     * Build middleware for an Express app with routes for:
+     * 1. '/nylas/webhook': Receiving webhook events, verifying its authenticity, and emitting webhook objects
+     * 2. '/nylas/generate-auth-url': Building the URL for authenticating users to your application via Hosted Authentication
+     * 3. '/nylas/exchange-mailbox-token': Exchange an authorization code for an access token
+     * @return The routes packaged as Express middleware
+     */
+    ExpressBinding.prototype.buildMiddleware = function () {
+        var _this = this;
+        var _a, _b, _c;
+        var router = express_1.default.Router();
+        // For the Nylas webhook endpoint, we should get the raw body to use for verification
+        router.use(routes_1.DefaultPaths.webhooks, body_parser_1.default.raw({ inflate: true, type: 'application/json' }));
+        router.use(express_1.default.json(), body_parser_1.default.urlencoded({ limit: '5mb', extended: true }) // support encoded bodies
+        );
+        router.post(((_a = this.overridePaths) === null || _a === void 0 ? void 0 : _a.webhooks) || routes_1.DefaultPaths.webhooks, this.webhookVerificationMiddleware(), function (req, res) {
+            var deltas = req.body.deltas || [];
+            _this.emitDeltaEvents(deltas);
+            res.status(200).send('ok');
+        });
+        router.post(((_b = this.overridePaths) === null || _b === void 0 ? void 0 : _b.buildAuthUrl) || routes_1.DefaultPaths.buildAuthUrl, function (req, res) { return __awaiter(_this, void 0, void 0, function () {
+            var state, authUrl;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        state = '';
+                        if (!this.csrfTokenExchangeOpts) return [3 /*break*/, 2];
+                        return [4 /*yield*/, this.csrfTokenExchangeOpts.generateCsrfToken(req)];
+                    case 1:
+                        state = _a.sent();
+                        _a.label = 2;
+                    case 2: return [4 /*yield*/, this.buildAuthUrl({
+                            scopes: this.defaultScopes,
+                            clientUri: this.clientUri,
+                            emailAddress: req.body.email_address,
+                            successUrl: req.body.success_url,
+                            state: state,
+                        })];
+                    case 3:
+                        authUrl = _a.sent();
+                        res.status(200).send(authUrl);
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+        router.post(((_c = this.overridePaths) === null || _c === void 0 ? void 0 : _c.exchangeCodeForToken) ||
+            routes_1.DefaultPaths.exchangeCodeForToken, function (req, res) { return __awaiter(_this, void 0, void 0, function () {
+            var csrfToken, isValidToken, accessTokenObj, e_1;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        _a.trys.push([0, 5, , 6]);
+                        if (!this.csrfTokenExchangeOpts) return [3 /*break*/, 2];
+                        csrfToken = req.body.csrfToken;
+                        return [4 /*yield*/, this.csrfTokenExchangeOpts.validateCsrfToken(csrfToken, req)];
+                    case 1:
+                        isValidToken = _a.sent();
+                        if (!isValidToken) {
+                            return [2 /*return*/, res.status(401).send('Invalid CSRF State Token')];
+                        }
+                        _a.label = 2;
+                    case 2: return [4 /*yield*/, this.exchangeCodeForToken(req.body.token)];
+                    case 3:
+                        accessTokenObj = _a.sent();
+                        return [4 /*yield*/, this.exchangeMailboxTokenCallback(accessTokenObj, res)];
+                    case 4:
+                        _a.sent();
+                        // If the callback event already sent a response then we don't need to do anything
+                        if (!res.writableEnded) {
+                            res.status(200).send('success');
+                        }
+                        return [3 /*break*/, 6];
+                    case 5:
+                        e_1 = _a.sent();
+                        res.status(500).send(e_1.message);
+                        return [3 /*break*/, 6];
+                    case 6: return [2 /*return*/];
+                }
+            });
+        }); });
+        return router;
+    };
+    return ExpressBinding;
+}(server_binding_1.ServerBinding));
+exports.default = ExpressBinding;

package/lib/server-bindings/server-binding.d.ts

@@ -0,0 +1,65 @@
+/// <reference types="node" />
+import { Request, Response, Router } from 'express';
+import { Scope } from '../models/connect';
+import { EventEmitter } from 'events';
+import Webhook, { WebhookTriggers } from '../models/webhook';
+import { WebhookDelta } from '../models/webhook-notification';
+import AccessToken from '../models/access-token';
+import Nylas from '../nylas';
+import { OpenWebhookTunnelOptions } from '../services/tunnel';
+import { BuildAuthUrl, ExchangeCodeForToken, VerifyWebhookSignature } from '../services/routes';
+declare type Middleware = Router;
+declare type ServerRequest = Request;
+declare type ServerResponse = Response;
+declare type ExchangeMailboxTokenCallback = (accessToken: AccessToken, res: ServerResponse) => void;
+declare type CsrfTokenExchangeOptions = {
+    generateCsrfToken: (req: ServerRequest) => Promise<string>;
+    validateCsrfToken: (csrfToken: string, req: ServerRequest) => Promise<boolean>;
+};
+declare type OverridePaths = {
+    buildAuthUrl?: string;
+    exchangeCodeForToken?: string;
+    webhooks?: string;
+};
+export declare type ServerBindingOptions = {
+    defaultScopes: Scope[];
+    exchangeMailboxTokenCallback: ExchangeMailboxTokenCallback;
+    csrfTokenExchangeOpts?: CsrfTokenExchangeOptions;
+    clientUri?: string;
+    overridePaths?: OverridePaths;
+};
+export declare abstract class ServerBinding extends EventEmitter implements ServerBindingOptions {
+    nylasClient: Nylas;
+    defaultScopes: Scope[];
+    exchangeMailboxTokenCallback: ExchangeMailboxTokenCallback;
+    csrfTokenExchangeOpts?: CsrfTokenExchangeOptions;
+    clientUri?: string;
+    overridePaths?: OverridePaths;
+    static NYLAS_SIGNATURE_HEADER: string;
+    protected buildAuthUrl: BuildAuthUrl;
+    protected exchangeCodeForToken: ExchangeCodeForToken;
+    protected verifyWebhookSignature: VerifyWebhookSignature;
+    private _untypedOn;
+    private _untypedEmit;
+    protected constructor(nylasClient: Nylas, options: ServerBindingOptions);
+    abstract buildMiddleware(): Middleware;
+    on: <K extends WebhookTriggers>(event: K, listener: (payload: WebhookDelta) => void) => this;
+    emit: <K extends WebhookTriggers>(event: K, payload: WebhookDelta) => boolean;
+    /**
+     * Emit all incoming delta events
+     * @param deltas The list of delta JSON objects
+     */
+    emitDeltaEvents(deltas: Record<string, unknown>[]): void;
+    /**
+     * Start a local development websocket to get webhook events
+     * @param webhookTunnelConfig Optional configuration for setting region, triggers, and overriding callbacks
+     * @return The webhook details response from the API
+     */
+    startDevelopmentWebsocket(webhookTunnelConfig?: Partial<OpenWebhookTunnelOptions>): Promise<Webhook>;
+    /**
+     * Delta event processor to be used either by websocket or webhook
+     * @param d The delta event
+     */
+    protected handleDeltaEvent: (d: WebhookDelta) => void;
+}
+export {};

package/lib/server-bindings/server-binding.js

@@ -0,0 +1,87 @@
+"use strict";
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (b.hasOwnProperty(p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+var events_1 = require("events");
+var webhook_notification_1 = require("../models/webhook-notification");
+var tunnel_1 = require("../services/tunnel");
+var routes_1 = require("../services/routes");
+var ServerBinding = /** @class */ (function (_super) {
+    __extends(ServerBinding, _super);
+    function ServerBinding(nylasClient, options) {
+        var _a;
+        var _this = _super.call(this) || this;
+        _this._untypedOn = _this.on;
+        _this._untypedEmit = _this.emit;
+        // Taken from the best StackOverflow answer of all time https://stackoverflow.com/a/56228127
+        _this.on = function (event, listener) { return _this._untypedOn(event, listener); };
+        _this.emit = function (event, payload) { return _this._untypedEmit(event, payload); };
+        /**
+         * Delta event processor to be used either by websocket or webhook
+         * @param d The delta event
+         */
+        _this.handleDeltaEvent = function (d) {
+            d.type && _this.emit(d.type, d);
+        };
+        _this.nylasClient = nylasClient;
+        _this.defaultScopes = options.defaultScopes;
+        _this.exchangeMailboxTokenCallback = options.exchangeMailboxTokenCallback;
+        _this.csrfTokenExchangeOpts = options.csrfTokenExchangeOpts;
+        _this.clientUri = options.clientUri;
+        (_a = routes_1.Routes(nylasClient), _this.buildAuthUrl = _a.buildAuthUrl, _this.exchangeCodeForToken = _a.exchangeCodeForToken, _this.verifyWebhookSignature = _a.verifyWebhookSignature);
+        _this.overridePaths = options.overridePaths;
+        return _this;
+    }
+    /**
+     * Emit all incoming delta events
+     * @param deltas The list of delta JSON objects
+     */
+    ServerBinding.prototype.emitDeltaEvents = function (deltas) {
+        var _this = this;
+        deltas.forEach(function (d) { return _this.handleDeltaEvent(new webhook_notification_1.WebhookDelta().fromJSON(d)); });
+    };
+    /**
+     * Start a local development websocket to get webhook events
+     * @param webhookTunnelConfig Optional configuration for setting region, triggers, and overriding callbacks
+     * @return The webhook details response from the API
+     */
+    ServerBinding.prototype.startDevelopmentWebsocket = function (webhookTunnelConfig) {
+        /* eslint-disable no-console */
+        var defaultOnClose = function () {
+            return console.log('Nylas websocket client connection closed');
+        };
+        var defaultOnConnectFail = function (e) {
+            return console.log('Failed to connect Nylas websocket client', e.message);
+        };
+        var defaultOnError = function (e) {
+            return console.log('Error in Nylas websocket client', e.message);
+        };
+        var defaultOnConnect = function () {
+            return console.log('Nylas websocket client connected');
+        };
+        /* eslint-enable no-console */
+        return tunnel_1.openWebhookTunnel(this.nylasClient, {
+            onMessage: (webhookTunnelConfig === null || webhookTunnelConfig === void 0 ? void 0 : webhookTunnelConfig.onMessage) || this.handleDeltaEvent,
+            onClose: (webhookTunnelConfig === null || webhookTunnelConfig === void 0 ? void 0 : webhookTunnelConfig.onClose) || defaultOnClose,
+            onConnectFail: (webhookTunnelConfig === null || webhookTunnelConfig === void 0 ? void 0 : webhookTunnelConfig.onConnectFail) || defaultOnConnectFail,
+            onError: (webhookTunnelConfig === null || webhookTunnelConfig === void 0 ? void 0 : webhookTunnelConfig.onError) || defaultOnError,
+            onConnect: (webhookTunnelConfig === null || webhookTunnelConfig === void 0 ? void 0 : webhookTunnelConfig.onConnect) || defaultOnConnect,
+            region: webhookTunnelConfig === null || webhookTunnelConfig === void 0 ? void 0 : webhookTunnelConfig.region,
+            triggers: webhookTunnelConfig === null || webhookTunnelConfig === void 0 ? void 0 : webhookTunnelConfig.triggers,
+        });
+    };
+    ServerBinding.NYLAS_SIGNATURE_HEADER = 'x-nylas-signature';
+    return ServerBinding;
+}(events_1.EventEmitter));
+exports.ServerBinding = ServerBinding;

package/lib/services/routes.d.ts

@@ -0,0 +1,26 @@
+/// <reference types="node" />
+import { Scope } from '../models/connect';
+import Nylas from '../nylas';
+import AccessToken from '../models/access-token';
+export declare enum DefaultPaths {
+    buildAuthUrl = "/nylas/generate-auth-url",
+    exchangeCodeForToken = "/nylas/exchange-mailbox-token",
+    webhooks = "/nylas/webhook"
+}
+export declare type BuildAuthUrl = (options: BuildAuthUrlOptions) => Promise<string>;
+export declare type ExchangeCodeForToken = (code: string) => Promise<AccessToken>;
+export declare type VerifyWebhookSignature = (nylasSignature: string, rawBody: Buffer) => boolean;
+export declare type BuildAuthUrlOptions = {
+    scopes: Scope[];
+    emailAddress: string;
+    successUrl: string;
+    clientUri?: string;
+    state?: string;
+};
+declare type Routes = {
+    buildAuthUrl: BuildAuthUrl;
+    exchangeCodeForToken: ExchangeCodeForToken;
+    verifyWebhookSignature: VerifyWebhookSignature;
+};
+export declare const Routes: (nylasClient: Nylas) => Routes;
+export default Routes;

package/lib/services/routes.js

@@ -0,0 +1,95 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (_) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+var crypto_1 = __importDefault(require("crypto"));
+var DefaultPaths;
+(function (DefaultPaths) {
+    DefaultPaths["buildAuthUrl"] = "/nylas/generate-auth-url";
+    DefaultPaths["exchangeCodeForToken"] = "/nylas/exchange-mailbox-token";
+    DefaultPaths["webhooks"] = "/nylas/webhook";
+})(DefaultPaths = exports.DefaultPaths || (exports.DefaultPaths = {}));
+exports.Routes = function (nylasClient) {
+    /**
+     * Build the URL for authenticating users to your application via Hosted Authentication
+     * @param options Configuration for the authentication process
+     * @return The URL for hosted authentication
+     */
+    var buildAuthUrl = function (options) { return __awaiter(void 0, void 0, void 0, function () {
+        var scopes, emailAddress, successUrl, clientUri, state;
+        return __generator(this, function (_a) {
+            scopes = options.scopes, emailAddress = options.emailAddress, successUrl = options.successUrl, clientUri = options.clientUri, state = options.state;
+            return [2 /*return*/, nylasClient.urlForAuthentication({
+                    loginHint: emailAddress,
+                    redirectURI: (clientUri || '') + successUrl,
+                    scopes: scopes,
+                    state: state,
+                })];
+        });
+    }); };
+    /**
+     * Exchange an authorization code for an access token
+     * @param code One-time authorization code from Nylas
+     * @param callback Callback before returning the access token
+     * @return The {@link AccessToken} object containing the access token and other information
+     */
+    var exchangeCodeForToken = function (code, callback) { return __awaiter(void 0, void 0, void 0, function () {
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, nylasClient.exchangeCodeForToken(code, callback)];
+                case 1: return [2 /*return*/, _a.sent()];
+            }
+        });
+    }); };
+    /**
+     * Verify incoming webhook signature came from Nylas
+     * @param nylasSignature The signature to verify
+     * @param rawBody The raw body from the payload
+     * @return true if the webhook signature was verified from Nylas
+     */
+    var verifyWebhookSignature = function (nylasSignature, rawBody) {
+        var digest = crypto_1.default
+            .createHmac('sha256', nylasClient.clientSecret)
+            .update(rawBody)
+            .digest('hex');
+        return digest === nylasSignature;
+    };
+    return { buildAuthUrl: buildAuthUrl, exchangeCodeForToken: exchangeCodeForToken, verifyWebhookSignature: verifyWebhookSignature };
+};

package/lib/services/tunnel.d.ts

@@ -0,0 +1,29 @@
+import { client as WebSocketClient } from 'websocket';
+import { Region } from '../config';
+import Nylas from '../nylas';
+import Webhook, { WebhookTriggers } from '../models/webhook';
+import { WebhookDelta } from '../models/webhook-notification';
+export interface OpenWebhookTunnelOptions {
+    onMessage: (msg: WebhookDelta) => void;
+    onConnectFail?: (error: Error) => void;
+    onError?: (error: Error) => void;
+    onClose?: (wsClient: WebSocketClient) => void;
+    onConnect?: (wsClient: WebSocketClient) => void;
+    region?: Region;
+    triggers?: WebhookTriggers[];
+}
+/**
+ * Open a webhook tunnel and register it with the Nylas API
+ * 1. Creates a UUID
+ * 2. Opens a websocket connection to Nylas' webhook forwarding service,
+ *    with the UUID as a header
+ * 3. Creates a new webhook pointed at the forwarding service with the UUID as the path
+ *
+ * When an event is received by the forwarding service, it will push directly to this websocket
+ * connection
+ *
+ * @param nylasClient The configured Nylas application
+ * @param config Configuration for the webhook tunnel, including callback functions, region, and events to subscribe to
+ * @return The webhook details response from the API
+ */
+export declare const openWebhookTunnel: (nylasClient: Nylas, config: OpenWebhookTunnelOptions) => Promise<Webhook>;

package/lib/services/tunnel.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+var websocket_1 = require("websocket");
+var uuid_1 = require("uuid");
+var config_1 = require("../config");
+var webhook_notification_1 = require("../models/webhook-notification");
+/**
+ * Deletes the Nylas webhook
+ * @param nylasClient The Nylas application configured with the webhook
+ * @param nylasWebhook The Nylas webhook details
+ */
+var deleteTunnelWebhook = function (nylasClient, nylasWebhook) {
+    if (nylasWebhook && nylasWebhook.id) {
+        /* eslint-disable no-console */
+        console.log("Shutting down the webhook tunnel and deleting id: " + nylasWebhook.id);
+        /* eslint-enable no-console */
+        nylasClient.webhooks
+            .delete(nylasWebhook)
+            .then(function () { return process.exit(); })
+            .catch(function (err) {
+            console.warn("Error while trying to deregister the webhook " + nylasWebhook.id + ": " + err.message);
+            process.exit();
+        });
+    }
+};
+/**
+ * Create a webhook to the Nylas forwarding service which will pass messages to our websocket
+ * @param nylasClient The configured Nylas application
+ * @param callbackDomain The domain name of the callback
+ * @param tunnelPath The path to the tunnel
+ * @param triggers The list of triggers to subscribe to
+ * @return The webhook details response from the API
+ */
+var buildTunnelWebhook = function (nylasClient, callbackDomain, tunnelPath, triggers) {
+    var callbackUrl = "https://" + callbackDomain + "/" + tunnelPath;
+    return nylasClient.webhooks
+        .build({
+        callbackUrl: callbackUrl,
+        state: 'active',
+        test: true,
+        triggers: triggers,
+    })
+        .save()
+        .then(function (webhook) {
+        // Ensure that, upon all exits, delete the webhook on the Nylas application
+        process.on('SIGINT', function () { return deleteTunnelWebhook(nylasClient, webhook); });
+        process.on('SIGTERM', function () { return deleteTunnelWebhook(nylasClient, webhook); });
+        process.on('SIGBREAK', function () { return deleteTunnelWebhook(nylasClient, webhook); });
+        return webhook;
+    });
+};
+/**
+ * Open a webhook tunnel and register it with the Nylas API
+ * 1. Creates a UUID
+ * 2. Opens a websocket connection to Nylas' webhook forwarding service,
+ *    with the UUID as a header
+ * 3. Creates a new webhook pointed at the forwarding service with the UUID as the path
+ *
+ * When an event is received by the forwarding service, it will push directly to this websocket
+ * connection
+ *
+ * @param nylasClient The configured Nylas application
+ * @param config Configuration for the webhook tunnel, including callback functions, region, and events to subscribe to
+ * @return The webhook details response from the API
+ */
+exports.openWebhookTunnel = function (nylasClient, config) {
+    var triggers = config.triggers || config_1.DEFAULT_WEBHOOK_TRIGGERS;
+    var region = config.region || config_1.DEFAULT_REGION;
+    var _a = config_1.regionConfig[region], websocketDomain = _a.websocketDomain, callbackDomain = _a.callbackDomain;
+    // This UUID will map our websocket to a webhook in the forwarding server
+    var tunnelId = uuid_1.v4();
+    var client = new websocket_1.client({ closeTimeout: 60000 });
+    client.on('connectFailed', function (error) {
+        config.onConnectFail && config.onConnectFail(error);
+    });
+    client.on('connect', function (connection) {
+        config.onConnect && config.onConnect(client);
+        connection.on('error', function (error) {
+            config.onError && config.onError(error);
+        });
+        connection.on('close', function () {
+            config.onClose && config.onClose(client);
+        });
+        connection.on('message', function (message) {
+            // This shouldn't happen. If any of these are seen, open an issue
+            if (message.type === 'binary') {
+                config.onError &&
+                    config.onError(new Error('Unknown binary message received'));
+                return;
+            }
+            try {
+                var req = JSON.parse(message.utf8Data);
+                var deltas = JSON.parse(req.body).deltas;
+                deltas.forEach(function (delta) {
+                    return config.onMessage(new webhook_notification_1.WebhookDelta().fromJSON(delta));
+                });
+            }
+            catch (e) {
+                config.onError &&
+                    config.onError(new Error("Error converting Nylas websocket event to JSON: " + (e &&
+                        e.message)));
+            }
+        });
+    });
+    client.connect("wss://" + websocketDomain, undefined, undefined, {
+        'Client-Id': nylasClient.clientId,
+        'Client-Secret': nylasClient.clientSecret,
+        'Tunnel-Id': tunnelId,
+        Region: region,
+    });
+    return buildTunnelWebhook(nylasClient, callbackDomain, tunnelId, triggers);
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nylas",
-  "version": "6.5.1",
+  "version": "7.0.0-beta.0",
   "description": "A NodeJS wrapper for the Nylas REST API for email, contacts, and calendar.",
   "main": "lib/nylas.js",
   "types": "lib/nylas.d.ts",
@@ -47,7 +47,11 @@
     "backoff": "^2.5.0",
     "form-data": "^4.0.0",
     "JSONStream": "^1.3.5",
-    "node-fetch": "^2.6.1"
+    "node-fetch": "^2.6.1",
+    "express": "^4.17.13",
+    "body-parser": "^1.20.0",
+    "uuid": "^8.3.2",
+    "websocket": "^1.0.34"
   },
   "devDependencies": {
     "@babel/cli": "^7.13.16",
@@ -57,6 +61,9 @@
     "@types/backoff": "^2.5.1",
     "@types/jest": "^25.1.4",
     "@types/node-fetch": "^2.5.8",
+    "@types/uuid": "^8.3.4",
+    "@types/websocket": "^1.0.5",
+    "@types/express": "^4.17.13",
     "@typescript-eslint/eslint-plugin": "^2.25.0",
     "@typescript-eslint/parser": "^2.25.0",
     "babel-eslint": "^10.0.1",