notion-sdk-js

Notion SDK for JavaScript: Project Introduction

The Notion SDK for JavaScript is designed as a simple and user-friendly client for interacting with the Notion API. The project offers developers an efficient way to integrate and manage Notion's productivity tools within their own JavaScript applications. Below is a comprehensive breakdown of its key features and capabilities.

Installation

To begin using the Notion SDK in a JavaScript project, it's as simple as installing the package via npm:

npm install @notionhq/client

Usage

To utilize the Notion API, developers should follow Notion's Getting Started Guide to get set up with an integration or OAuth access token.

const { Client } = require("@notionhq/client");

// Initializing a client
const notion = new Client({
  auth: process.env.NOTION_TOKEN,
});

With the client initialized, users can make requests to any Notion API endpoint, which are well-documented in the API reference.

(async () => {
  const listUsersResponse = await notion.users.list({});
})();

The methods return a Promise that resolves with the response data, providing developers with the flexibility to handle and utilize this data as needed.

Handling Errors

The SDK provides robust error handling. If the API returns an error, the related Promise will reject with a APIResponseError, allowing the developer to manage exceptions efficiently by comparing error codes with APIErrorCode.

try {
  const myPage = await notion.databases.query({
    database_id: databaseId,
    filter: {
      property: "Landmark",
      rich_text: {
        contains: "Bridge",
      },
    },
  });
} catch (error) {
  if (error.code === APIErrorCode.ObjectNotFound) {
    // Handle object not found error
  } else {
    console.error(error);
  }
}

Logging

For debugging purposes, developers can enhance their log outputs by adjusting the log level:

const { Client, LogLevel } = require("@notionhq/client");

const notion = new Client({
  auth: process.env.NOTION_TOKEN,
  logLevel: LogLevel.DEBUG,
});

It is possible to set a custom logger to direct log outputs to a preferred destination other than the default console.

Client Options

The SDK allows for customization upon initialization through various options:

• auth: Authentication bearer token.
• logLevel: Define log verbosity.
• timeoutMs: Set request timeout duration.
• baseUrl: Define the API request root URL.
• logger: Customize log output.
• agent: Control TCP socket creation.

TypeScript Support

Notion SDK includes TypeScript support, providing type definitions for requests and responses to enhance type safety and development productivity.

Type guard utilities are implemented to differentiate between complete and partial API responses, ensuring developers handle types correctly.

if (isNotionClientError(error)) {
  switch (error.code) {
    case ClientErrorCode.RequestTimeout:
      // Handle request timeout
      break;
  }
}

Utility Functions

The package includes utility functions to handle paginated API endpoints:

• iteratePaginatedAPI: Converts paginated APIs to async iterators.
• collectPaginatedAPI: Collects paginated API results into an array.

System Requirements

The SDK supports a minimum of Node.js version 12 and TypeScript version 4.5.

Getting Help

For feature requests or issues with the Notion API, reach out via email at [email protected]. To report issues with the SDK itself, submitting an issue on the GitHub repository is recommended, although email communication is preferred for prompt responses.

The Notion SDK for JavaScript simplifies the process of integrating Notion's API, making it an attractive option for developers looking to harness the productivity power of Notion within their applications.