[66699] Node SDK v6.0.0 - major refactor release

[mrashed-dev]

Description

This PR represents the major update v6.0.0 of the Node SDK. The main theme of this major release is 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. 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.

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
• 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.application() deprecates application_name and redirect_uris in favour of camelCase
• 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

Migration Guide

//todo

License

I confirm that this contribution is made under the terms of the MIT license and that I have the authority necessary to make this contribution on behalf of its copyright owner.

[mrashed-dev]

@philrenaud @AaronDDM -- The PR contains a lot of merge conflict resolutions and already-reviewed code from previously-merged PRs that were squashed into this one. The commits that are un-reviewed are all the commits starting from Set Folder as a default export -- eeeb8ef onward.