nylas 6.10.0 → 7.0.0-beta.1

package/README.md

@@ -4,7 +4,6 @@
 
 # Nylas Node.js SDK  
 
-[![Travis build status](https://travis-ci.org/nylas/nylas-nodejs.svg?branch=master)](https://travis-ci.org/nylas/nylas-nodejs)
 [![codecov](https://codecov.io/gh/nylas/nylas-nodejs/branch/main/graph/badge.svg?token=94IMGU4F09)](https://codecov.io/gh/nylas/nylas-nodejs)
 
 This is the GitHub repository for the Nylas Node SDK and this repo is primarily for anyone who wants to make contributions to the SDK or install it from source. If you are looking to use Node to access the Nylas Email, Calendar, or Contacts API you should refer to our official [Node SDK Quickstart Guide](https://developer.nylas.com/docs/developer-tools/sdk/node-sdk/).
@@ -20,6 +19,10 @@ Here are some resources to help you get started:
 
 ## ⚙️ Install
 
+**Note:** The Nylas Node SDK requires Node.js v16 or later.
+
+### Set up using npm
+
 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.
 
 Then, head to the nearest command line and run the following:
@@ -27,6 +30,8 @@ Then, head to the nearest command line and run the following:
 
 Alternatively, if you prefer to use [Yarn](https://yarnpkg.com/en/), you can install the Nylas Node SDK with `yarn add nylas`
 
+### Build from source
+
 To install this package from source, clone this repo and run `npm install` from inside the project directory.
 
 ```bash
@@ -37,27 +42,34 @@ 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.
+To use this SDK, you must first [get a free Nylas account](https://dashboard.nylas.com/register).
 
-```javascript
-const Nylas = require('nylas');
+Then, follow the Quickstart guide to [set up your first app and get your API keys](https://developer.nylas.com/docs/v3-beta/v3-quickstart/).
 
-Nylas.config({
-  clientId: CLIENT_ID,
-  clientSecret: CLIENT_SECRET,
-});
+For code examples that demonstrate how to use this SDK, take a look at our [Node repos in the Nylas Samples collection](https://github.com/orgs/nylas-samples/repositories?q=&type=all&language=javascript&sort=).
+
+### 🚀 Making Your First Request
 
-const nylas = Nylas.with(ACCESS_TOKEN);
+Every resource (i.e., messages, events, contacts) is accessed via an instance of `Nylas`. The `Nylas` object must be initialized with your Nylas API key, and you can provide other additional configurations such as the Nylas API url and the timeout.
+
+```typescript
+import Nylas from "nylas";
+
+const nylas = new Nylas({
+  apiKey: "NYLAS_API_KEY",
+});
 ```
 
-Then, you can use Nylas to access information about a user's account:
-```javascript
-nylas.threads.list({}).then(threads => {
-  console.log(threads.length);
+Once initialized you can use the object to make requests for a given account's resources, for example to list all the calendars for a given account:
+```typescript
+nylas.calendars.list({ identifier: "GRANT_ID" }).then(calendars => {
+  console.log(calendars);
 });
 ```
 
-For more information about how to use the Nylas Node SDK, [take a look at our quickstart guide](https://developer.nylas.com/docs/developer-tools/sdk/node-sdk/).
+## 📚 Documentation
+
+Nylas maintains a [reference guide for the Node SDK](https://nylas-nodejs-sdk-reference.pages.dev/) to help you get familiar with the available methods and classes.
 
 ## 💙 Contributing
 

package/lib/cjs/apiClient.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_fetch_1 = require("node-fetch");
+const error_1 = require("./models/error");
+const utils_1 = require("./utils");
+const PACKAGE_JSON = require('package.json').default;
+const SDK_VERSION = PACKAGE_JSON.version;
+/**
+ * The API client for communicating with the Nylas API
+ * @ignore Not for public use
+ */
+class APIClient {
+    constructor({ apiKey, apiUri, timeout }) {
+        this.apiKey = apiKey;
+        this.serverUrl = apiUri;
+        this.timeout = timeout * 1000; // fetch timeout uses milliseconds
+    }
+    setRequestUrl({ overrides, path, queryParams, }) {
+        const url = new URL(`${overrides?.apiUri || this.serverUrl}${path}`);
+        return this.setQueryStrings(url, queryParams);
+    }
+    setQueryStrings(url, queryParams) {
+        if (queryParams) {
+            const snakeCaseParams = (0, utils_1.objKeysToSnakeCase)(queryParams, ['metadataPair']);
+            for (const [key, value] of Object.entries(snakeCaseParams)) {
+                if (key == 'metadataPair') {
+                    // The API understands a metadata_pair filter in the form of:
+                    // <key>:<value>
+                    const metadataPair = [];
+                    for (const item in value) {
+                        metadataPair.push(`${item}:${value[item]}`);
+                    }
+                    url.searchParams.set('metadata_pair', metadataPair.join(','));
+                }
+                else {
+                    url.searchParams.set(key, value);
+                }
+            }
+        }
+        return url;
+    }
+    setRequestHeaders({ headers, overrides, }) {
+        return {
+            Accept: 'application/json',
+            'User-Agent': `Nylas Node SDK v${SDK_VERSION}`,
+            Authorization: `Bearer ${overrides?.apiKey || this.apiKey}`,
+            ...headers,
+        };
+    }
+    requestOptions(optionParams) {
+        const requestOptions = {};
+        requestOptions.url = this.setRequestUrl(optionParams);
+        requestOptions.headers = this.setRequestHeaders(optionParams);
+        requestOptions.method = optionParams.method;
+        if (optionParams.body) {
+            requestOptions.body = JSON.stringify((0, utils_1.objKeysToSnakeCase)(optionParams.body));
+            requestOptions.headers['Content-Type'] = 'application/json';
+        }
+        return requestOptions;
+    }
+    newRequest(options) {
+        const newOptions = this.requestOptions(options);
+        return new node_fetch_1.Request(newOptions.url, {
+            method: newOptions.method,
+            headers: newOptions.headers,
+            body: newOptions.body,
+        });
+    }
+    async requestWithResponse(response) {
+        const text = await response.text();
+        try {
+            const responseJSON = JSON.parse(text);
+            return (0, utils_1.objKeysToCamelCase)(responseJSON);
+        }
+        catch (e) {
+            throw new Error(`Could not parse response from the server: ${text}`);
+        }
+    }
+    async request(options) {
+        const req = this.newRequest(options);
+        const controller = new AbortController();
+        const timeout = setTimeout(() => {
+            controller.abort();
+            throw new error_1.NylasSdkTimeoutError(req.url, this.timeout);
+        }, this.timeout);
+        const response = await (0, node_fetch_1.default)(req, { signal: controller.signal });
+        clearTimeout(timeout);
+        if (typeof response === 'undefined') {
+            throw new Error('Failed to fetch response');
+        }
+        // handle error response
+        if (response.status > 299) {
+            const authErrorResponse = options.path.includes('connect/token') ||
+                options.path.includes('connect/revoke');
+            const text = await response.text();
+            let error;
+            try {
+                const parsedError = JSON.parse(text);
+                const camelCaseError = (0, utils_1.objKeysToCamelCase)(parsedError);
+                if (authErrorResponse) {
+                    error = new error_1.NylasOAuthError(camelCaseError, response.status);
+                }
+                else {
+                    error = new error_1.NylasApiError(camelCaseError, response.status);
+                }
+            }
+            catch (e) {
+                throw new Error(`Received an error but could not parse response from the server: ${text}`);
+            }
+            throw error;
+        }
+        return this.requestWithResponse(response);
+    }
+}
+exports.default = APIClient;

package/lib/cjs/config.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SERVER_URL = exports.REGION_CONFIG = exports.DEFAULT_REGION = exports.Region = void 0;
+/**
+ * Enum representing the available Nylas API regions.
+ */
+var Region;
+(function (Region) {
+    Region["Us"] = "us";
+    Region["Eu"] = "eu";
+})(Region = exports.Region || (exports.Region = {}));
+/**
+ * The default Nylas API region.
+ * @default Region.Us
+ */
+exports.DEFAULT_REGION = Region.Us;
+/**
+ * The available preset configuration values for each Nylas API region.
+ */
+exports.REGION_CONFIG = {
+    [Region.Us]: {
+        nylasAPIUrl: 'https://api.us.nylas.com',
+    },
+    [Region.Eu]: {
+        nylasAPIUrl: 'https://api.eu.nylas.com',
+    },
+};
+/**
+ * The default Nylas API URL.
+ * @default https://api.us.nylas.com
+ */
+exports.DEFAULT_SERVER_URL = exports.REGION_CONFIG[exports.DEFAULT_REGION].nylasAPIUrl;

package/lib/cjs/models/applicationDetails.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/cjs/models/auth.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/cjs/models/availability.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AvailabilityMethod = void 0;
+/**
+ * Enum representing the method used to determine availability for a meeting.
+ */
+var AvailabilityMethod;
+(function (AvailabilityMethod) {
+    AvailabilityMethod["MaxFairness"] = "max-fairness";
+    AvailabilityMethod["MaxAvailability"] = "max-availability";
+})(AvailabilityMethod = exports.AvailabilityMethod || (exports.AvailabilityMethod = {}));

package/lib/cjs/models/calendars.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/cjs/models/error.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NylasSdkTimeoutError = exports.NylasOAuthError = exports.NylasApiError = exports.AbstractNylasSdkError = exports.AbstractNylasApiError = void 0;
+/**
+ * Base class for all Nylas API errors.
+ */
+class AbstractNylasApiError extends Error {
+}
+exports.AbstractNylasApiError = AbstractNylasApiError;
+/**
+ * Base class for all Nylas SDK errors.
+ */
+class AbstractNylasSdkError extends Error {
+}
+exports.AbstractNylasSdkError = AbstractNylasSdkError;
+/**
+ * Class representation of a general Nylas API error.
+ */
+class NylasApiError extends AbstractNylasApiError {
+    constructor(apiError, statusCode) {
+        super(apiError.error.message);
+        this.type = apiError.error.type;
+        this.requestId = apiError.requestId;
+        this.providerError = apiError.error.providerError;
+        this.statusCode = statusCode;
+    }
+}
+exports.NylasApiError = NylasApiError;
+/**
+ * Class representing an OAuth error returned by the Nylas API.
+ */
+class NylasOAuthError extends AbstractNylasApiError {
+    constructor(apiError, statusCode) {
+        super(apiError.errorDescription);
+        this.error = apiError.error;
+        this.errorCode = apiError.errorCode;
+        this.errorDescription = apiError.errorDescription;
+        this.errorUri = apiError.errorUri;
+        this.statusCode = statusCode;
+    }
+}
+exports.NylasOAuthError = NylasOAuthError;
+/**
+ * Error thrown when the Nylas SDK times out before receiving a response from the server
+ */
+class NylasSdkTimeoutError extends AbstractNylasSdkError {
+    constructor(url, timeout) {
+        super('Nylas SDK timed out before receiving a response from the server.');
+        this.url = url;
+        this.timeout = timeout;
+    }
+}
+exports.NylasSdkTimeoutError = NylasSdkTimeoutError;

package/lib/cjs/models/events.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/cjs/models/grants.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/cjs/models/listQueryParams.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/cjs/models/redirectUri.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/cjs/models/response.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/cjs/models/webhooks.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookTriggers = void 0;
+var WebhookTriggers;
+(function (WebhookTriggers) {
+    WebhookTriggers["CalendarCreated"] = "calendar.created";
+    WebhookTriggers["CalendarUpdated"] = "calendar.updated";
+    WebhookTriggers["CalendarDeleted"] = "calendar.deleted";
+    WebhookTriggers["EventCreated"] = "event.created";
+    WebhookTriggers["EventUpdated"] = "event.updated";
+    WebhookTriggers["EventDeleted"] = "event.deleted";
+    WebhookTriggers["GrantCreated"] = "grant.created";
+    WebhookTriggers["GrantUpdated"] = "grant.updated";
+    WebhookTriggers["GrantDeleted"] = "grant.deleted";
+    WebhookTriggers["GrantExpired"] = "grant.expired";
+    WebhookTriggers["MessageSendSuccess"] = "message.send_success";
+    WebhookTriggers["MessageSendFailed"] = "message.send_failed";
+})(WebhookTriggers = exports.WebhookTriggers || (exports.WebhookTriggers = {}));

package/lib/cjs/nylas.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const apiClient_1 = require("./apiClient");
+const config_1 = require("./config");
+const calendars_1 = require("./resources/calendars");
+const events_1 = require("./resources/events");
+const auth_1 = require("./resources/auth");
+const webhooks_1 = require("./resources/webhooks");
+const applications_1 = require("./resources/applications");
+/**
+ * The entry point to the Node SDK
+ *
+ * A Nylas instance holds a configured http client pointing to a base URL and is intended to be reused and shared
+ * across threads and time.
+ */
+class Nylas {
+    /**
+     * @param config Configuration options for the Nylas SDK
+     */
+    constructor(config) {
+        this.apiClient = new apiClient_1.default({
+            apiKey: config.apiKey,
+            apiUri: config.apiUri || config_1.DEFAULT_SERVER_URL,
+            timeout: config.timeout || 30,
+        });
+        this.applications = new applications_1.Applications(this.apiClient);
+        this.auth = new auth_1.Auth(this.apiClient);
+        this.calendars = new calendars_1.Calendars(this.apiClient);
+        this.events = new events_1.Events(this.apiClient);
+        this.webhooks = new webhooks_1.Webhooks(this.apiClient);
+        return this;
+    }
+}
+exports.default = Nylas;

package/lib/cjs/resources/applications.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Applications = void 0;
+const resource_1 = require("./resource");
+const redirectUris_1 = require("./redirectUris");
+/**
+ * Nylas Applications API
+ *
+ * This endpoint allows for getting application details as well as redirect URI operations.
+ */
+class Applications extends resource_1.Resource {
+    /**
+     * @param apiClient client The configured Nylas API client
+     */
+    constructor(apiClient) {
+        super(apiClient);
+        this.redirectUris = new redirectUris_1.RedirectUris(apiClient);
+    }
+    /**
+     * Get application details
+     * @returns The application details
+     */
+    getDetails({ overrides } = {}) {
+        return super._find({
+            path: `/v3/applications`,
+            overrides,
+        });
+    }
+}
+exports.Applications = Applications;

package/lib/cjs/resources/auth.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Auth = void 0;
+const uuid_1 = require("uuid");
+const sha256_1 = require("sha256");
+const resource_1 = require("./resource");
+const grants_1 = require("./grants");
+/**
+ * A collection of authentication related API endpoints
+ *
+ * These endpoints allow for various functionality related to authentication.
+ * Also contains the Grants API and collection of provider API endpoints.
+ */
+class Auth extends resource_1.Resource {
+    /**
+     * @param apiClient The configured Nylas API client
+     */
+    constructor(apiClient) {
+        super(apiClient);
+        this.apiClient = apiClient;
+        this.grants = new grants_1.Grants(apiClient);
+    }
+    /**
+     * Build the URL for authenticating users to your application with OAuth 2.0
+     * @param config The configuration for building the URL
+     * @return The URL for hosted authentication
+     */
+    urlForOAuth2(config) {
+        return this.urlAuthBuilder(config).toString();
+    }
+    /**
+     * Exchange an authorization code for an access token
+     * @param request The request parameters for the code exchange
+     * @return Information about the Nylas application
+     */
+    exchangeCodeForToken(request) {
+        const body = {
+            ...request,
+            grantType: 'authorization_code',
+        };
+        if (request.codeVerifier) {
+            body.codeVerifier = request.codeVerifier;
+        }
+        return this.apiClient.request({
+            method: 'POST',
+            path: `/v3/connect/token`,
+            body,
+        });
+    }
+    /**
+     * Refresh an access token
+     * @param request The refresh token request
+     * @return The response containing the new access token
+     */
+    refreshAccessToken(request) {
+        return this.apiClient.request({
+            method: 'POST',
+            path: `/v3/connect/token`,
+            body: {
+                ...request,
+                grantType: 'refresh_token',
+            },
+        });
+    }
+    /**
+     * Build the URL for authenticating users to your application with OAuth 2.0 and PKCE
+     * IMPORTANT: YOU WILL NEED TO STORE THE 'secret' returned to use it inside the CodeExchange flow
+     * @param config The configuration for building the URL
+     * @return The URL for hosted authentication
+     */
+    urlForOAuth2PKCE(config) {
+        const url = this.urlAuthBuilder(config);
+        // Add code challenge to URL generation
+        url.searchParams.set('code_challenge_method', 's256');
+        const secret = (0, uuid_1.v4)();
+        const secretHash = this.hashPKCESecret(secret);
+        url.searchParams.set('code_challenge', secret);
+        // Return the url with secret & hashed secret
+        return { secret, secretHash, url: url.toString() };
+    }
+    /**
+     * Build the URL for admin consent authentication for Microsoft
+     * @param config The configuration for building the URL
+     * @return The URL for admin consent authentication
+     */
+    urlForAdminConsent(config) {
+        const configWithProvider = { ...config, provider: 'microsoft' };
+        const url = this.urlAuthBuilder(configWithProvider);
+        url.searchParams.set('response_type', 'adminconsent');
+        url.searchParams.set('credential_id', config.credentialId);
+        return url.toString();
+    }
+    /**
+     * Revoke a token (and the grant attached to the token)
+     * @param token The token to revoke
+     * @return True if the token was revoked successfully
+     */
+    async revoke(token) {
+        await this.apiClient.request({
+            method: 'POST',
+            path: `/v3/connect/revoke`,
+            queryParams: {
+                token,
+            },
+        });
+        return true;
+    }
+    /**
+     * Detect provider from email address
+     * @param params The parameters to include in the request
+     * @return The detected provider, if found
+     */
+    async detectProvider(params) {
+        return this.apiClient.request({
+            method: 'POST',
+            path: `/v3/grants/providers/detect`,
+            queryParams: params,
+        });
+    }
+    urlAuthBuilder(config) {
+        const url = new URL(`${this.apiClient.serverUrl}/v3/connect/auth`);
+        url.searchParams.set('client_id', config.clientId);
+        url.searchParams.set('redirect_uri', config.redirectUri);
+        url.searchParams.set('access_type', config.accessType ? config.accessType : 'online');
+        url.searchParams.set('response_type', 'code');
+        if (config.provider) {
+            url.searchParams.set('provider', config.provider);
+        }
+        if (config.loginHint) {
+            url.searchParams.set('login_hint', config.loginHint);
+            if (config.includeGrantScopes) {
+                url.searchParams.set('include_grant_scopes', config.includeGrantScopes.toString());
+            }
+        }
+        if (config.scope) {
+            url.searchParams.set('scope', config.scope.join(' '));
+        }
+        if (config.prompt) {
+            url.searchParams.set('prompt', config.prompt);
+        }
+        if (config.metadata) {
+            url.searchParams.set('metadata', config.metadata);
+        }
+        if (config.state) {
+            url.searchParams.set('state', config.state);
+        }
+        return url;
+    }
+    hashPKCESecret(secret) {
+        return Buffer.from((0, sha256_1.default)(secret)).toString('base64');
+    }
+}
+exports.Auth = Auth;

package/lib/cjs/resources/calendars.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Calendars = void 0;
+const resource_1 = require("./resource");
+/**
+ * Nylas Calendar API
+ *
+ * The Nylas calendar API allows you to create new calendars or manage existing ones.
+ * A calendar can be accessed by one, or several people, and can contain events.
+ */
+class Calendars extends resource_1.Resource {
+    /**
+     * Return all Calendars
+     * @return A list of calendars
+     */
+    list({ identifier, queryParams, overrides, }) {
+        return super._list({
+            queryParams,
+            overrides,
+            path: `/v3/grants/${identifier}/calendars`,
+        });
+    }
+    /**
+     * Return a Calendar
+     * @return The calendar
+     */
+    find({ identifier, calendarId, overrides, }) {
+        return super._find({
+            path: `/v3/grants/${identifier}/calendars/${calendarId}`,
+            overrides,
+        });
+    }
+    /**
+     * Create a Calendar
+     * @return The created calendar
+     */
+    create({ identifier, requestBody, overrides, }) {
+        return super._create({
+            path: `/v3/grants/${identifier}/calendars`,
+            requestBody,
+            overrides,
+        });
+    }
+    /**
+     * Update a Calendar
+     * @return The updated Calendar
+     */
+    update({ calendarId, identifier, requestBody, overrides, }) {
+        return super._update({
+            path: `/v3/grants/${identifier}/calendars/${calendarId}`,
+            requestBody,
+            overrides,
+        });
+    }
+    /**
+     * Delete a Calendar
+     * @return The deleted Calendar
+     */
+    destroy({ identifier, calendarId, overrides, }) {
+        return super._destroy({
+            path: `/v3/grants/${identifier}/calendars/${calendarId}`,
+            overrides,
+        });
+    }
+    /**
+     * Get Availability for a given account / accounts
+     * @return The availability response
+     */
+    getAvailability({ requestBody, overrides, }) {
+        return this.apiClient.request({
+            method: 'POST',
+            path: `/v3/calendars/availability`,
+            body: requestBody,
+            overrides,
+        });
+    }
+}
+exports.Calendars = Calendars;