This release of the Node SDK is a major overhaul of the SDK with a focus refactoring and improving the SDK to make it more Typescript-like as well as improving the usability of the SDK by providing better and stricter type hinting as well as expected parameters. It is highly encouraged to read through the release notes, changelog, and the migration guide before upgrading as this release brings a slew of breaking changes and may not be compatible with prior versions. A full changelog and the link to the migration guide can be found at the very bottom of the post.

This major release can be broken down into three main sections: refactoring RestfulModel, improving deserialization and object creation, and improving the typing of the SDK in general.

Refactoring RestfulModel and Introducing Model superclass

As the SDK coverage grows, we need to define what a "basic" model is instead of solely using RestfulModel for every model represented in the SDK. To do this we needed to decouple the standard functionality of a model from the specific functionality/structure of a "classic" Nylas API model. A "classic" Nylas API model is a model used for endpoints like Event, Calendar, Message, etc. where we expect the object to have an id, account_id, and object field and we are expected to perform RESTful operations directly with this model. Now with the Nylas API, there are a lot of models that are representations of API objects, but don't have endpoint(s) nor are we expected to make RESTful calls directly using them. A perfect example of this are all the Contact subclasses. This allows the user to instantiate these objects without the need to pass in a NylasConnection type, which cleans up the code and produces less overhead.

The same logic was also applied to refactoring RestfulModelCollection and creating a ModelCollection superclass.

Improving Deserialization and Object Creation

Following up on the creation of the Model superclass, each model has an accompanying interface that represents an object of parameters that the model will use, as well as the proper strictness dictated by what values will always be present in any scenario (GET, POST, PUT). In the constructor of each model, we now specify that we can take in an optional props property of the Model interface's type. This helps to hint the user as to what properties they must pass in during the initialization of the object. This also helps us with the strictness of the typing in each model as now we properly outline what properties are needed at a bare minimum.

This props method property is left as optional because it allows some flexibility to the SDK user to just instantiate a type of object then either:

• performing [model].fromJSON()
• or, setting the property values individually via [model].[property] = value
  If taking this route, we initialize all the required types to a default value in order not to upset Typescript's strictness requirements.

With this, we also deprecate the RestfulModelCollection.build() method as it provides a way for the user to bypass the constructor typing requirements and pass in whatever object they want. It also does not provide any type hinting to the user when trying to initialize the object. Here's an example of the before and after:

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

// before, user can put whatever they want
const event = nylas.events.build({foo: "bar"});

// now, this way the user has to abide by EventProperties or else face a warning from Typescript

// throws warning:
const event = new Event(nylas, {foo: "bar"});

// does not throw warning
const event = new Event(nylas, {calendarId: "id", when: {startTime: 1234, endTime: 4321}});

// also does not throw warning, inits and object that has default values set
const event = new Event(nylas);

Improving SDK Typing

The biggest change we've made here is that all of the SDK methods that are meant to be used by the end users all have a non-any return type. In addition to this, the PR improves on the previous work of the refactor to ensure that we are utilizing the use of models, interfaces, and proper deserialization. With this, our support for Calendar availability has improved with the introduction of classes and types for API objects like free-busy and availability. Our support for Native Authentication and Virtual Calendars have also seen improvements as we have models to represent these objects and introduced enums to provide the user an easier time with providing things like providers and scopes without needing to refer to the API docs to see what scopes/providers are supported and to reduce user typing errors.

Changlog -- Breaking Changes

• Refactored RestfulModel and RestfulModelCollection, introduced Model and ModelCollection superclass for models that do not directly interact with the Nylas API
• Introduction of interfaces that accompany models to improve experience when instantiating API models and provides better insight on "required" fields
• Applied missing variable and return types, and applied stricter typing to improve deserialization and to adhere Typescript best practice
• Event.when is now of When type
• All Event fields for participants are now of EventParticipant type
• Several Contact fields that took an object as a value now take a corresponding Contact subclass type
• NeuralMessageOptions is now a Model class instead of an interface type
• CalendarRestfulModelCollection.freeBusy() now returns a (new) FreeBusy type instead of a JSON
• CalendarRestfulModelCollection.availability() now returns a (new) CalendarAvailability type instead of a JSON
• CalendarRestfulModelCollection.consecutiveAvailability() now returns a (new) CalendarConsecutiveAvailability type instead of a JSON
• Connect.authorize() now takes in a parameter of VirtualCalendarProperties | NativeAuthenticationProperties type (new) instead of an object and returns AuthorizationCode type (new) instead of a JSON
• Connect.token() now returns an Account type instead of a JSON
• Contact, EventConferencing, and Folder are now default exports
• Nylas has stricter parameters and introduction of defined return types
• Nylas.exchangeCodeForToken() now returns an AccessToken type that's a representation of the full API response as opposed to just the access token string
• Nylas.application() takes ApplicationDetailProperties type and returns an ApplicationDetail type
• Removed RestfulModelCollection.build() as it does not allow for proper property and type hinting in favor of instantiating via new Model()
• Removed Connect.newAccount() as it had no functionality
• Removed File.metadata() as it doesn't appear any different than making a NylasConnection.files().find() call
• Lots of new models are introduced, almost all API objects are represented as a model in the SDK now
• Introduction of Enum types

Migration Guide

The migration guide for this major release can be found on our Nylas Docs page!