Skip to content

NylasConnect class overview

The NylasConnect class is the core of the Nylas Connect library. It provides methods for OAuth authentication, token management, and grant creation and management.

import { NylasConnect } from "@nylas/connect";

const nylasConnect = new NylasConnect({
  clientId: process.env.NYLAS_CLIENT_ID!,
  redirectUri: process.env.NYLAS_REDIRECT_URI!,
  apiUrl: process.env.NYLAS_API_URL || "https://api.us.nylas.com",
  environment: "production",
  persistTokens: true,
  debug: false,
  logLevel: "error",
});

// Set up authentication state monitoring
nylasConnect.onConnectStateChange((state) => {
  console.log("Auth state changed:", state);

  switch (state.type) {
    case "connected":
      // Handle successful connection
      break;
    case "disconnected":
      // Handle disconnection
      break;
    case "error":
      // Handle authentication errors
      console.error("Auth error:", state.error);
      break;
  }
});

`ConnectConfig`

The NylasConnect constructor accepts a ConnectConfig object with the following options.

Property

Type

Default

Methods

The NylasConnect class includes the following methods. Click on any method name to view its detailed documentation.

Authentication methods

Method

Type

Default

(options: ConnectOptions = {}): Promise<ConnectResult>

(options: ConnectOptions = {}): Promise<ConnectResult>

getAuthUrl(options: ConnectOptions = {}): Promise<{ url: string; state: string; scopes: string[]; }>

getAuthUrl(options: ConnectOptions = {}): Promise<{ url: string; state: string; scopes: string[]; }>

onConnectStateChange()

(callback: ConnectStateChangeCallback) => () => void

onConnectStateChange()

(callback: ConnectStateChangeCallback) => () => void

validateToken()

validateToken()

Callback methods

Method

Type

Default

(url?: string): Promise<ConnectResult>

(url?: string): Promise<ConnectResult>

handleRedirectCallback()

(url?: string): Promise<ConnectResult>

handleRedirectCallback()

(url?: string): Promise<ConnectResult>

Grant management methods

Method

Type

Default

getConnectionStatus()

(grantId?: string): Promise<ConnectionStatus>

getConnectionStatus()

(grantId?: string): Promise<ConnectionStatus>

getGrantInfo()

getGrantInfo()

(grantId?: string): Promise<SessionData | null>

(grantId?: string): Promise<SessionData | null>

isConnected()

isConnected()

(grantId?: string): Promise<void>

(grantId?: string): Promise<void>

Utility methods

Method

Type

Default

disableDebug()

disableDebug()

enableDebug()

enableDebug()

isAutoCallbackEnabled()

isAutoCallbackEnabled()

setLogLevel()

(level: LogLevel | "off"): void

setLogLevel()

(level: LogLevel | "off"): void

Property types

`ConnectError`

ConnectError extends the standard Error interface and adds fields for better error handling.

Property	Type	Description
`code`	string	An error code for programmatic error handling.
`description`	string?	A human-readable description of the error.
`docsUrl`	string?	A link to relevant documentation.
`fix`	string?	A suggested solution for resolving the error.
`originalError`	Error?	The original error, if the `ConnectError` wraps another error.

`Environment`


Name	`Environment`
Description	Your project’s deployment environment.
Enum	`development \| staging \| production`

`ProviderScopes`

Default scope settings for different providers.

type ProviderScopes = {
  google?: GoogleScope[];
  microsoft?: MicrosoftScope[];
  yahoo?: YahooScope[];
  imap?: never;       // IMAP doesn't support scopes
  icloud?: string[];  // iCloud uses custom scopes
};

const nylasConnect = new NylasConnect({
  clientId: "<NYLAS_CLIENT_ID>",
  redirectUri: "https://yourapp.com/callback",
  defaultScopes: {
    google: ["https://www.googleapis.com/auth/gmail.readonly"],
    microsoft: ["https://graph.microsoft.com/Mail.Read"],
  },
});