Add SDK documentation for models and top-level files

.eslintignore

@@ -1,3 +1,4 @@
 node_modules
 lib
-example
+example
+docs

.prettierignore

@@ -1,3 +1,4 @@
 node_modules
 lib
-example
+example
+docs

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,13 +19,19 @@ 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:
 `npm install nylas`
 
 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
 
+To use this SDK, you must first [get a free Nylas account](https://dashboard.nylas.com/register).
+
+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/).
+
+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
+
 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.
 
-```javascript
-const Nylas = require('nylas');
+```typescript
+import Nylas from "nylas";
 
-Nylas.config({
-  clientId: CLIENT_ID,
-  clientSecret: CLIENT_SECRET,
+const nylas = new Nylas({
+  apiKey: "NYLAS_API_KEY",
 });
-
-const nylas = Nylas.with(ACCESS_TOKEN);
 ```
 
 Then, you can use Nylas to access information about a user's account:
-```javascript
-nylas.threads.list({}).then(threads => {
-  console.log(threads.length);
+```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.json

@@ -55,7 +55,7 @@
     "prettier": "^1.19.1",
     "ts-jest": "^29.1.1",
     "typedoc": "^0.24.8",
-    "typedoc-plugin-missing-exports": "^2.0.1",
+    "typedoc-plugin-rename-defaults": "^0.6.5",
     "typescript": "^4.9.5"
   },
   "repository": {

src/apiClient.ts

@@ -10,6 +10,16 @@ const PACKAGE_JSON = require('package.json').default;
 
 const SDK_VERSION = PACKAGE_JSON.version;
 
+/**
+ * Options for a request to the Nylas API
+ * @property path The path to the API endpoint
+ * @property method The HTTP method to use
+ * @property headers Additional headers to send with the request
+ * @property queryParams Query parameters to send with the request
+ * @property body The body of the request
+ * @property overrides Overrides to the default Nylas API client configuration
+ * @ignore Not for public use
+ */
 export interface RequestOptionsParams {
   path: string;
   method: string;
@@ -19,6 +29,16 @@ export interface RequestOptionsParams {
   overrides?: OverridableNylasConfig;
 }
 
+/**
+ * Options for building a request for fetch to understand
+ * @property path The path to the API endpoint
+ * @property method The HTTP method to use
+ * @property headers Additional headers to send with the request
+ * @property url The URL of the request
+ * @property body The body of the request
+ * @property overrides Overrides to the default Nylas API client configuration
+ * @ignore Not for public use
+ */
 interface RequestOptions {
   path: string;
   method: string;
@@ -28,14 +48,27 @@ interface RequestOptions {
   overrides?: Partial<NylasConfig>;
 }
 
+/**
+ * The API client for communicating with the Nylas API
+ * @ignore Not for public use
+ */
 export default class APIClient {
+  /**
+   * The API key to use for authentication
+   */
   apiKey: string;
+  /**
+   * The URL to use for communicating with the Nylas API
+   */
   serverUrl: string;
+  /**
+   * The timeout for requests to the Nylas API, in seconds
+   */
   timeout: number;
 
-  constructor({ apiKey, serverUrl, timeout }: Required<NylasConfig>) {
+  constructor({ apiKey, apiUri, timeout }: Required<NylasConfig>) {
     this.apiKey = apiKey;
-    this.serverUrl = serverUrl;
+    this.serverUrl = apiUri;
     this.timeout = timeout * 1000; // fetch timeout uses milliseconds
   }
 
@@ -44,7 +77,7 @@ export default class APIClient {
     path,
     queryParams,
   }: RequestOptionsParams): URL {
-    const url = new URL(`${overrides?.serverUrl || this.serverUrl}${path}`);
+    const url = new URL(`${overrides?.apiUri || this.serverUrl}${path}`);
 
     return this.setQueryStrings(url, queryParams);
   }

src/config.ts

@@ -1,9 +1,18 @@
+/**
+ * Configuration options for initializing the Nylas SDK.
+ * @property apiKey The Nylas API key to use for authentication
+ * @property apiUri The URL to use for communicating with the Nylas API
+ * @property timeout The timeout for requests to the Nylas API, in seconds
+ */
 export type NylasConfig = {
   apiKey: string;
-  serverUrl?: string; // TODO: rename to nylasAPIUrl
+  apiUri?: string;
   timeout?: number;
 };
 
+/**
+ * The options that can override the default Nylas API client configuration.
+ */
 export type OverridableNylasConfig = Partial<NylasConfig>;
 
 /**
@@ -14,32 +23,30 @@ export interface Overrides {
   overrides?: OverridableNylasConfig;
 }
 
-export enum ResponseType {
-  CODE = 'code',
-  TOKEN = 'token',
-}
-
-export type AuthenticateUrlConfig = {
-  redirectURI: string;
-  redirectOnError?: boolean;
-  loginHint?: string;
-  state?: string;
-  provider?: string;
-  scopes?: string[];
-  responseType?: ResponseType;
-};
-
+/**
+ * Enum representing the available Nylas API regions.
+ */
 export enum Region {
   Us = 'us',
   Eu = 'eu',
 }
 
+/**
+ * The default Nylas API region.
+ * @default Region.Us
+ */
 export const DEFAULT_REGION = Region.Us;
 
+/**
+ * The configuration options for each Nylas API region.
+ */
 type RegionConfig = {
   nylasAPIUrl: string;
 };
 
+/**
+ * The available preset configuration values for each Nylas API region.
+ */
 export const REGION_CONFIG: Record<Region, RegionConfig> = {
   [Region.Us]: {
     nylasAPIUrl: 'https://api.us.nylas.com',
@@ -49,4 +56,8 @@ export const REGION_CONFIG: Record<Region, RegionConfig> = {
   },
 };
 
+/**
+ * The default Nylas API URL.
+ * @default https://api.us.nylas.com
+ */
 export const DEFAULT_SERVER_URL = REGION_CONFIG[DEFAULT_REGION].nylasAPIUrl;

src/models/applicationDetails.ts

@@ -1,29 +1,95 @@
 import { RedirectUri } from './redirectUri';
 
+/**
+ * Interface for a Nylas application details object
+ */
 export interface ApplicationDetails {
+  /**
+   * Public Application ID
+   */
   applicationId: string;
+  /**
+   * ID of organization
+   */
   organizationId: string;
+  /**
+   * Region identifier
+   */
   region: 'us' | 'eu';
+  /**
+   * Environment identifier
+   */
   environment: 'production' | 'staging';
+  /**
+   * Branding details for the application
+   */
   branding: Branding;
+  /**
+   * Hosted authentication branding details
+   */
   hostedAuthentication?: HostedAuthentication;
+  /**
+   * List of redirect URIs
+   */
   redirectUris?: RedirectUri[];
 }
 
+/**
+ * Interface for branding details for the application
+ */
 interface Branding {
+  /**
+   * Name of the application
+   */
   name: string;
+  /**
+   * URL points to application icon
+   */
   iconUrl?: string;
+  /**
+   * Application / publisher website URL
+   */
   websiteUrl?: string;
+  /**
+   * Description of the appli∏cati∏on
+   */
   description?: string;
 }
 
+/**
+ * Interface for hosted authentication branding details
+ */
 interface HostedAuthentication {
+  /**
+   * URL of the background image
+   */
   backgroundImageUrl?: string;
+  /**
+   * Alignment of background image
+   */
   alignment?: string;
+  /**
+   * Primary color
+   */
   colorPrimary?: string;
+  /**
+   * Secondary color
+   */
   colorSecondary?: string;
+  /**
+   * Title
+   */
   title?: string;
+  /**
+   * Subtitle
+   */
   subtitle?: string;
+  /**
+   * Background color
+   */
   backgroundColor?: string;
+  /**
+   * CSS spacing attribute in px
+   */
   spacing?: number;
 }