nylas/nylas-nodejs v6.2.0 on GitHub

This new release of the Nylas Node SDK brings a few features as well as an enhancement.

New Features

Add support for returning multiple messages by a list of message IDs (#313)
Add new field in Draft for adding files by file IDs (#314)
Add Webhook Notification models (#311)
Improved Delta support: added Delta model and two new methods; since and longpoll

Enhancements

Fix Virtual Calendar logic and serialization

Using New Features

Return multiple messages by multiple message IDs

Nylas.config({clientId: 'clientId', clientSecret: 'clientSecret'});
const nylas = Nylas.with('access_token');

const messages = await nylas.messages.findMultiple(['message_id_1', 'message_id_2']);

Add files to a `Draft` by draft IDs

const Nylas = require('nylas');
Nylas.config({clientId: 'clientId', clientSecret: 'clientSecret'});
const nylas = Nylas.with('access_token');

const draft = new Draft(nylas, {
  to: [{ name: 'Nylas Swag', email: 'swag@nylas.com' }],
  fileIdsToAttach = ["file_id_1", "file_id_2"],
});
draft.save();

Please note that this new field, fileIdsToAttach: string[] in Draft, only adds files to a draft. To remove an existing file from an already saved Draft object, it must be done on the files field. Upon saving we will make sure to merge unique values in the outgoing payload.

Delta improvements: new `Delta` and `Deltas` models, new `since()` and `longPoll()` functions

There have been a number of changes to improve Delta support in this SDK:

Delta is now of RestfulModel type representing a single Delta API object.
Deltas is a new model representing the API object that contains a set of Delta objects.
DeltaCollection is a new class that contains all delta-related operations (including latestCursor and startStream)
NylasConnection.deltas now returns a DeltaCollection object. To maintain backwards compatibility, latestCursor and startStream have been moved out of Delta and into DeltaCollection.
DeltaCollection.since(cursor: string): Promise<Deltas> returns the set of deltas since the cursor provided. (see GET /delta)
DeltaCollection.longPoll(cursor: string, timeout: string, params?: DeltaParams): Promise<DeltaLongPoll> polls the API for Deltas since the cursor provided until either the provided timeout is reached, or the server sends a response. (see GET /delta/longpoll)

To return a set of delta cursors since a specific cursor:

Nylas.config({clientId: 'clientId', clientSecret: 'clientSecret'});
const nylas = Nylas.with('access_token');

const deltas = nylas.deltas.since("CURSOR");

/*
* There are a few options you can pass in to this endpoint:
* view: string - This type of view to return within the delta objects
* includeTypes: string[] - The list of types to include in the query ('file', 'event', etc.)
* excludeTypes: string[] - The list of types to exclude in the query ('file', 'event', etc.)
*/

const deltas = nylas.deltas.since("CURSOR", {
  view: 'expanded',
  excludeTypes: ['file', 'event'],
  includeTypes: ['message'],
});

To long-poll for delta cursors since a specific cursor:

Nylas.config({clientId: 'clientId', clientSecret: 'clientSecret'});
const nylas = Nylas.with('access_token');

// long-poll for 30 seconds
nylas.deltas.longPoll("CURSOR", 30).then(deltaEmitter => {
  deltaEmitter.on('delta', delta => {
    console.log("Recieved a delta!");
    console.log(delta);
  });
});

/*
* There are a few options you can pass in to this endpoint:
* view: string - This type of view to return within the delta objects
* includeTypes: string[] - The list of types to include in the query ('file', 'event', etc.)
* excludeTypes: string[] - The list of types to exclude in the query ('file', 'event', etc.)
*/

nylas.deltas.longPoll("CURSOR", 30, {
  view: 'expanded',
  excludeTypes: ['file', 'event'],
  includeTypes: ['message'],
}).then(deltaEmitter => {
  deltaEmitter.on('delta', delta => {
    console.log("Recieved a delta!");
    console.log(delta);
  });
});

Getting the latest cursor and streaming has not changed:

Nylas.config({clientId: 'clientId', clientSecret: 'clientSecret'});
const nylas = Nylas.with('access_token');

// Get the latest cursor
const latestCursor = await nylas.deltas.latestCursor();

// Start streaming
nylas.deltas.startStream(latestCursor).then(deltaEmitter => {
  deltaEmitter.on('delta', delta => {
    console.log("Recieved a delta!");
    console.log(delta);
  });
});

New Webhook Notification models

The sample below clarifies the models, the types, and the strictness of all new Webhook Notification-related models. To better understand it, please refer to the documentation on Webhook Notifications.

webhookNotification: WebhookDelta[] = new WebhookNotification().fromJSON(webhookNotificationJSON);
/*
* Available Fields for WebhookNotification:
* WebhookNotification.deltas: WebhookDelta[]
 */

const webhookDelta: WebhookDelta = webhookNotification.deltas[0];
/*
* Available Fields for WebhookDelta:
* WebhookDelta.date: Date
* WebhookDelta.object: string
* WebhookDelta.type: string
* WebhookDelta.objectData: WebhookObjectData
 */

const webhookDeltaObjectData: WebhookObjectData = webhookDelta.objectData;
/*
* Available Fields for WebhookObjectData:
* WebhookObjectData.id: string
* WebhookObjectData.accountId: string
* WebhookObjectData.namespaceId: string
* WebhookObjectData.object: string
* WebhookObjectData.objectAttributes?: WebhookObjectAttributes
* WebhookObjectData.metadata?: MessageTrackingData
 */

const webhookDeltaObjectAttributes: WebhookObjectAttributes = webhookDeltaObjectData.objectAttributes;
/*
* Available Fields for WebhookObjectAttributes:
* WebhookObjectAttributes.action?: string
* WebhookObjectAttributes.jobStatusId?: string
* WebhookObjectAttributes.threadId?: string
* WebhookObjectAttributes.receivedDate?: Date
*/

const webhookMessageTrackingData: MessageTrackingData = webhookDeltaObjectData.metadata;
/*
* Available Fields for MessageTrackingData:
* MessageTrackingData.senderAppId: number
* MessageTrackingData.messageId: string
* MessageTrackingData.payload: string
* MessageTrackingData.threadId?: string
* MessageTrackingData.replyToMessageId?: string
* MessageTrackingData.count?: number
* MessageTrackingData.fromSelf?: boolean
* MessageTrackingData.timestamp?: Date
* MessageTrackingData.linkData?: LinkClickCount[]
* MessageTrackingData.recents?: LinkClick[]
 */

const linkData: LinkClickCount = webhookMessageTrackingData.linkData[0];
/*
* Available Fields for LinkClickCount:
* LinkClickCount.url: string
* LinkClickCount.count: number
 */

const recents = webhookMessageTrackingData.recents[0];
/*
* Available Fields for LinkClick:
* LinkClick.id: number
* LinkClick.ip: string
* LinkClick.userAgent: string
* LinkClick.timestamp: Date
* LinkClick.linkIndex?: number
 */

Virtual Calendar fixed

In order to improve the user experience with Virtual Calendar, scope and settings are no longer required to be provided in the Connect.authorize() function if the user wants to authorize a Virtual Calendar. This is done to prevent confusion as the API only accepts one specific value for the two fields in order for the call to be accepted. Below is the sample of authorizing a Virtual Calendar:

Nylas.config({clientId: 'clientId', clientSecret: 'clientSecret'});

const virtualCalendarAuth = await Nylas.connect.authorize({
  name: "Virtual Calendar Name",
  emailAddress: "virtual_account_unique_id",
  clientId: "CLIENT_ID", // Note that clientId is optional, defaults to the clientId configured above in Nylas.config()
});