nylas 8.1.0 โ†’ 8.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/README.md +117 -46
  2. package/lib/cjs/resources/messages.js +1 -1
  3. package/lib/cjs/utils.js +1 -1
  4. package/lib/cjs/version.js +1 -1
  5. package/lib/esm/resources/messages.js +1 -1
  6. package/lib/esm/utils.js +1 -1
  7. package/lib/esm/version.js +1 -1
  8. package/lib/types/version.d.ts +1 -1
  9. package/package.json +1 -1
package/README.md CHANGED
@@ -2,59 +2,63 @@
2
2
  <a href="https://www.nylas.com/">
3
3
  <img src="/diagrams/nylas-logo.png" alt="Nylas" height="80" />
4
4
  </a>
5
-
5
+
6
6
  <h1>Nylas Node.js SDK</h1>
7
-
7
+
8
8
  <p>
9
- <strong>The official Node.js SDK for the Nylas Communications Platform</strong>
9
+ <strong>The official Node.js SDK for Nylas โ€” the infrastructure that powers communications</strong>
10
10
  </p>
11
-
11
+
12
12
  <p>
13
13
  <a href="https://www.npmjs.com/package/nylas"><img src="https://img.shields.io/npm/v/nylas" alt="npm version" /></a>
14
14
  <a href="https://codecov.io/gh/nylas/nylas-nodejs"><img src="https://codecov.io/gh/nylas/nylas-nodejs/branch/main/graph/badge.svg?token=94IMGU4F09" alt="code coverage" /></a>
15
15
  <a href="https://www.npmjs.com/package/nylas"><img src="https://img.shields.io/npm/dm/nylas" alt="downloads" /></a>
16
16
  <a href="LICENSE.txt"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="license" /></a>
17
17
  </p>
18
-
18
+
19
19
  <p>
20
- <a href="https://developer.nylas.com/docs/v3/sdks/node/">๐Ÿ“– Documentation</a> โ€ข
21
- <a href="https://dashboard.nylas.com/register">๐Ÿš€ Get Started</a> โ€ข
22
- <a href="https://github.com/orgs/nylas-samples/repositories?q=&type=all&language=javascript">๐Ÿ’ก Examples</a> โ€ข
23
- <a href="https://developer.nylas.com/docs/api/">๐Ÿ“š API Reference</a>
20
+ <a href="https://developer.nylas.com/docs/v3/sdks/node/">๐Ÿ“– SDK Guide</a> ยท
21
+ <a href="https://developer.nylas.com/docs/api/v3/">๐Ÿ“š API Reference</a> ยท
22
+ <a href="https://dashboard-v3.nylas.com/register">๐Ÿš€ Sign up</a> ยท
23
+ <a href="https://github.com/orgs/nylas-samples/repositories?q=node">๐Ÿ’ก Samples</a> ยท
24
+ <a href="https://forums.nylas.com">๐Ÿ’ฌ Forum</a>
24
25
  </p>
25
26
  </div>
26
27
 
27
28
  <br />
28
29
 
29
- This is the GitHub repository for the Nylas Node SDK. 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/).
30
+ The official Node.js SDK for [Nylas](https://developer.nylas.com/docs/v3/) โ€” the infrastructure that powers communications. Integrate with Gmail, Microsoft, IMAP, Zoom, and 250+ email, calendar, and meeting providers in 5 minutes. Covers [Email](https://developer.nylas.com/docs/v3/email/), [Calendar](https://developer.nylas.com/docs/v3/calendar/), [Contacts](https://developer.nylas.com/docs/v3/email/contacts/), [Scheduler](https://developer.nylas.com/docs/v3/scheduler/), [Notetaker](https://developer.nylas.com/docs/v3/notetaker/), and [Agent Accounts](https://developer.nylas.com/docs/v3/agent-accounts/).
30
31
 
31
- The Nylas Communications Platform provides REST APIs for [Email](https://developer.nylas.com/docs/connectivity/email/), [Calendar](https://developer.nylas.com/docs/connectivity/calendar/), and [Contacts](https://developer.nylas.com/docs/connectivity/contacts/), and the Node SDK is the quickest way to build your integration using JavaScript.
32
+ This repository is for contributors and anyone installing the SDK from source. If you just want to use the SDK in your app, head straight to the [**Node.js SDK guide**](https://developer.nylas.com/docs/v3/sdks/node/) on developer.nylas.com.
32
33
 
33
- Here are some resources to help you get started:
34
+ ## Get started
34
35
 
35
- - [Sign up for your free Nylas account](https://dashboard.nylas.com/register)
36
- - [Sign up for the Nylas v3 Beta program to access the v3 Dashboard](https://info.nylas.com/apiv3betasignup.html?utm_source=github&utm_medium=devrel-surfaces&utm_campaign=&utm_content=node-sdk-upgrade)
37
- - [Nylas API v3 Quickstart Guide](https://developer.nylas.com/docs/v3-beta/v3-quickstart/)
38
- - [Nylas SDK Reference](https://nylas-nodejs-sdk-reference.pages.dev/)
39
- - [Nylas API Reference](https://developer.nylas.com/docs/api/)
40
- - [Nylas Samples repo for code samples and example applications](https://github.com/orgs/nylas-samples/repositories?q=&type=all&language=javascript)
36
+ 1. [Sign up for a free Nylas account](https://dashboard-v3.nylas.com/register) and grab your API key from the [Nylas Dashboard](https://dashboard-v3.nylas.com/).
37
+ 2. Read the [Getting started guide](https://developer.nylas.com/docs/v3/getting-started/) for the core concepts (applications, grants, API keys).
38
+ 3. Install the SDK and make your first request โ€” see below.
41
39
 
42
- ## โš™๏ธ Install
40
+ You can also bootstrap from the terminal:
43
41
 
44
- **Note:** The Nylas Node SDK requires Node.js v16 or later.
42
+ ```bash
43
+ brew install nylas/nylas-cli/nylas
44
+ nylas init
45
+ ```
45
46
 
46
- ### Set up using npm
47
+ More options in the [CLI getting-started guide](https://cli.nylas.com/guides/getting-started).
47
48
 
48
- To run the Nylas Node SDK, first install [Node](https://nodejs.org/en/download/) and [npm](https://www.npmjs.com/get-npm) on your machine.
49
+ ## โš™๏ธ Install
49
50
 
50
- Then, head to the nearest command line and run the following:
51
- `npm install nylas`
51
+ > **Requirements:** Node.js v18 or later.
52
52
 
53
- Alternatively, you can use [Yarn](https://yarnpkg.com/en/) to install the Nylas Node SDK by running the `yarn add nylas` command.
53
+ ```bash
54
+ npm install nylas
55
+ # or
56
+ yarn add nylas
57
+ ```
54
58
 
55
- ### Build from source
59
+ The package ships its own TypeScript types โ€” no `@types/nylas` needed. It's a hybrid ESM + CommonJS package, so both `import` and `require` work.
56
60
 
57
- To install this package from source, clone this repo and run `npm install` from inside the project directory.
61
+ To install from source:
58
62
 
59
63
  ```bash
60
64
  git clone https://github.com/nylas/nylas-nodejs.git
@@ -62,48 +66,115 @@ cd nylas-nodejs
62
66
  npm install
63
67
  ```
64
68
 
65
- ## โšก๏ธ Usage
66
-
67
- To use this SDK, you must first [get a free Nylas account](https://dashboard.nylas.com/register).
68
-
69
- 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/).
69
+ ### Runtime support
70
70
 
71
- 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=).
71
+ Tested on Node.js 18+. Also runs on AWS Lambda, Cloudflare Workers, and Vite/edge environments โ€” see the [`examples/`](examples/) directory for working setups.
72
72
 
73
- ### ๐Ÿš€ Making Your First Request
73
+ ## โšก๏ธ Usage
74
74
 
75
- You access Nylas resources (messages, calendars, events, contacts) through 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.
75
+ You access Nylas resources (messages, calendars, events, contacts, โ€ฆ) through an instance of `Nylas`. Initialize it with your API key โ€” and optionally an `apiUri` matching your [data residency](https://developer.nylas.com/docs/dev-guide/platform/data-residency/).
76
76
 
77
77
  ```typescript
78
78
  import Nylas from "nylas";
79
+ // or: const Nylas = require("nylas").default;
79
80
 
80
81
  const nylas = new Nylas({
81
- apiKey: "NYLAS_API_KEY",
82
+ apiKey: process.env.NYLAS_API_KEY,
83
+ apiUri: process.env.NYLAS_API_URI, // e.g. https://api.us.nylas.com
84
+ timeout: 30, // optional, in seconds
82
85
  });
83
86
  ```
84
87
 
85
- 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:
88
+ Once initialized, use it to make requests against a [grant](https://developer.nylas.com/docs/v3/auth/) (an authenticated end-user account):
86
89
 
87
90
  ```typescript
88
- nylas.calendars.list({ identifier: "GRANT_ID" }).then(calendars => {
89
- console.log(calendars);
91
+ const calendars = await nylas.calendars.list({
92
+ identifier: process.env.NYLAS_GRANT_ID,
90
93
  });
94
+ console.log(calendars);
95
+ ```
96
+
97
+ ### Error handling
98
+
99
+ The SDK throws typed errors you can catch and inspect. Every API error carries a `requestId` and `flowId` โ€” include both when filing a support ticket so we can trace the request end-to-end.
100
+
101
+ ```typescript
102
+ import { NylasApiError, NylasOAuthError, NylasSdkTimeoutError } from "nylas";
103
+
104
+ try {
105
+ await nylas.calendars.list({ identifier: grantId });
106
+ } catch (err) {
107
+ if (err instanceof NylasApiError) {
108
+ console.error(err.statusCode, err.type, err.message, err.requestId, err.flowId);
109
+ } else if (err instanceof NylasSdkTimeoutError) {
110
+ console.error("Timed out:", err.url, err.timeout);
111
+ } else {
112
+ throw err;
113
+ }
114
+ }
91
115
  ```
92
116
 
93
- ## ๐Ÿ“š Documentation
117
+ Step-by-step walkthroughs in the SDK guide:
94
118
 
95
- 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.
119
+ - [Send and receive email](https://developer.nylas.com/docs/v3/sdks/node/send-email/)
120
+ - [Read messages and threads](https://developer.nylas.com/docs/v3/sdks/node/read-messages-threads/)
121
+ - [Manage events on a calendar](https://developer.nylas.com/docs/v3/sdks/node/manage-events/)
122
+ - [Manage contacts](https://developer.nylas.com/docs/v3/sdks/node/manage-contacts/)
123
+ - [Manage folders and labels](https://developer.nylas.com/docs/v3/sdks/node/manage-folders-labels/)
124
+ - [Test webhooks locally](https://developer.nylas.com/docs/v3/sdks/node/webhook-testing/)
96
125
 
97
- ## โœจ Upgrading from 6.x
126
+ ## ๐Ÿ’ก Examples
98
127
 
99
- See [UPGRADE.md](UPGRADE.md) for instructions on upgrading from 6.x to 7.x.
128
+ Runnable examples live in [`examples/`](examples/) โ€” including [agent accounts](examples/agent-accounts/), [attachments](examples/attachments/) (incl. large attachments), [calendars](examples/calendars/), [folders](examples/folders/), [grants](examples/grants/), [messages](examples/messages/), [notetakers](examples/notetakers/), and edge runtimes ([AWS Lambda](examples/aws-lambda/), [Cloudflare + Vite](examples/cloudflare-vite-calendars/), [generic edge](examples/edge-environment/)).
100
129
 
101
- **Note**: The Node SDK v7.x is not compatible with the Nylas API earlier than v3-beta.
130
+ For full sample apps and product quickstarts, browse [**nylas-samples** on GitHub](https://github.com/orgs/nylas-samples/repositories?q=node) โ€” every official SDK has Email, Calendar, Contacts, Scheduler, and Webhooks quickstarts.
131
+
132
+ ## ๐Ÿค– AI agents
133
+
134
+ [nylas/skills](https://github.com/nylas/skills) drops Nylas into Claude Code, Cursor, Codex, and other agents that support the skills format:
135
+
136
+ ```bash
137
+ npx skills add nylas/skills
138
+ /plugin marketplace add nylas/skills # Claude Code
139
+ ```
140
+
141
+ The CLI also installs an MCP server for Claude Desktop, Claude Code, Cursor, Windsurf, or VS Code:
142
+
143
+ ```bash
144
+ brew install nylas/nylas-cli/nylas
145
+ nylas mcp install
146
+ ```
147
+
148
+ Walkthrough: [give AI agents email access via MCP](https://cli.nylas.com/guides/give-ai-agents-email-access-via-mcp).
149
+
150
+ ## ๐Ÿ“š Reference
151
+
152
+ - **SDK guide:** [developer.nylas.com/docs/v3/sdks/node](https://developer.nylas.com/docs/v3/sdks/node/)
153
+ - **API reference:** [developer.nylas.com/docs/api/v3](https://developer.nylas.com/docs/api/v3/)
154
+ - **TypeDoc reference:** [nylas-nodejs-sdk-reference.pages.dev](https://nylas-nodejs-sdk-reference.pages.dev/) โ€” generated method/class docs for this SDK
155
+ - **Webhooks (notifications):** [developer.nylas.com/docs/v3/notifications](https://developer.nylas.com/docs/v3/notifications/)
156
+ - **Auth flows:** [developer.nylas.com/docs/v3/auth](https://developer.nylas.com/docs/v3/auth/)
157
+ - **Dev guide & best practices:** [developer.nylas.com/docs/dev-guide](https://developer.nylas.com/docs/dev-guide/)
158
+ - **Changelog:** [CHANGELOG.md](CHANGELOG.md)
159
+
160
+ ## โœจ Upgrading
161
+
162
+ See [`CHANGELOG.md`](CHANGELOG.md) for per-release notes. Older upgrade guidance lives in [`UPGRADE.md`](UPGRADE.md).
102
163
 
103
164
  ## ๐Ÿ’™ Contributing
104
165
 
105
- Please refer to [Contributing](Contributing.md) for information about how to make contributions to this project. We welcome questions, bug reports, and pull requests.
166
+ Issues, ideas, and pull requests welcome โ€” see [Contributing.md](Contributing.md). Before opening a large change, please open an issue or post in the [forum](https://forums.nylas.com) so we can sanity-check the direction.
167
+
168
+ ## ๐Ÿ”’ Security
169
+
170
+ Found a vulnerability? Please **don't** open a public issue. Report it through our [Vulnerability Disclosure Policy](https://www.nylas.com/security/vulnerability-disclosure-policy/).
171
+
172
+ ## ๐Ÿ”— Other Nylas SDKs
173
+
174
+ - [nylas-python](https://github.com/nylas/nylas-python) ยท `pip install nylas`
175
+ - [nylas-ruby](https://github.com/nylas/nylas-ruby) ยท `gem install nylas`
176
+ - [nylas-java](https://github.com/nylas/nylas-java) ยท Maven / Gradle (Kotlin too)
106
177
 
107
178
  ## ๐Ÿ“ License
108
179
 
109
- This project is licensed under the terms of the MIT license. Please refer to [LICENSE](LICENSE.txt) for the full terms.
180
+ MIT โ€” see [LICENSE.txt](LICENSE.txt).
package/lib/cjs/resources/messages.js CHANGED
@@ -162,7 +162,7 @@ class Messages extends resource_js_1.Resource {
162
162
  ...requestBody,
163
163
  attachments: undefined,
164
164
  };
165
- form.append('message', JSON.stringify((0, utils_js_1.objKeysToSnakeCase)(messagePayload)));
165
+ form.append('message', JSON.stringify((0, utils_js_1.objKeysToSnakeCase)(messagePayload, ['metadata'])));
166
166
  // Add a separate form field for each attachment
167
167
  if (requestBody.attachments && requestBody.attachments.length > 0) {
168
168
  requestBody.attachments.map((attachment, index) => {
package/lib/cjs/utils.js CHANGED
@@ -249,7 +249,7 @@ function calculateTotalPayloadSize(requestBody) {
249
249
  ...requestBody,
250
250
  attachments: undefined,
251
251
  };
252
- const messagePayloadString = JSON.stringify(objKeysToSnakeCase(messagePayloadWithoutAttachments));
252
+ const messagePayloadString = JSON.stringify(objKeysToSnakeCase(messagePayloadWithoutAttachments, ['metadata']));
253
253
  totalSize += Buffer.byteLength(messagePayloadString, 'utf8');
254
254
  // Add attachment sizes
255
255
  const attachmentSize = requestBody.attachments?.reduce((total, attachment) => {
package/lib/cjs/version.js CHANGED
@@ -2,4 +2,4 @@
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.SDK_VERSION = void 0;
4
4
  // This file is generated by scripts/exportVersion.js
5
- exports.SDK_VERSION = '8.1.0';
5
+ exports.SDK_VERSION = '8.1.1';
package/lib/esm/resources/messages.js CHANGED
@@ -159,7 +159,7 @@ export class Messages extends Resource {
159
159
  ...requestBody,
160
160
  attachments: undefined,
161
161
  };
162
- form.append('message', JSON.stringify(objKeysToSnakeCase(messagePayload)));
162
+ form.append('message', JSON.stringify(objKeysToSnakeCase(messagePayload, ['metadata'])));
163
163
  // Add a separate form field for each attachment
164
164
  if (requestBody.attachments && requestBody.attachments.length > 0) {
165
165
  requestBody.attachments.map((attachment, index) => {
package/lib/esm/utils.js CHANGED
@@ -204,7 +204,7 @@ export function calculateTotalPayloadSize(requestBody) {
204
204
  ...requestBody,
205
205
  attachments: undefined,
206
206
  };
207
- const messagePayloadString = JSON.stringify(objKeysToSnakeCase(messagePayloadWithoutAttachments));
207
+ const messagePayloadString = JSON.stringify(objKeysToSnakeCase(messagePayloadWithoutAttachments, ['metadata']));
208
208
  totalSize += Buffer.byteLength(messagePayloadString, 'utf8');
209
209
  // Add attachment sizes
210
210
  const attachmentSize = requestBody.attachments?.reduce((total, attachment) => {
package/lib/esm/version.js CHANGED
@@ -1,2 +1,2 @@
1
1
  // This file is generated by scripts/exportVersion.js
2
- export const SDK_VERSION = '8.1.0';
2
+ export const SDK_VERSION = '8.1.1';
package/lib/types/version.d.ts CHANGED
@@ -1 +1 @@
1
- export declare const SDK_VERSION = "8.1.0";
1
+ export declare const SDK_VERSION = "8.1.1";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "nylas",
3
- "version": "8.1.0",
3
+ "version": "8.1.1",
4
4
  "description": "A NodeJS wrapper for the Nylas REST API for email, contacts, and calendar.",
5
5
  "main": "lib/cjs/nylas.js",
6
6
  "types": "lib/types/nylas.d.ts",