tessl/npm-notionhq--client

A simple and easy to use client for the Notion API

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Notion SDK for JavaScript

Name: tessl/npm-notionhq--client
Author: tessl

The Notion SDK for JavaScript is a simple and easy to use client for the Notion API. It provides a comprehensive TypeScript/JavaScript SDK that enables developers to integrate with Notion workspaces programmatically, offering a complete client library with strongly-typed interfaces for all Notion API endpoints.

Package Information

Package Name: @notionhq/client
Package Type: npm
Language: TypeScript
Installation: npm install @notionhq/client

Core Imports

import { Client } from "@notionhq/client";

For CommonJS:

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

Additional imports for types and utilities:

import { 
  Client, 
  APIErrorCode, 
  LogLevel, 
  isNotionClientError,
  collectPaginatedAPI,
  iteratePaginatedAPI,
  isFullPage,
  isFullBlock,
  isFullUser,
  isFullComment,
  isFullDatabase,
  isFullDataSource,
  isFullPageOrDataSource,
  isTextRichTextItemResponse,
  isEquationRichTextItemResponse,
  isMentionRichTextItemResponse
} from "@notionhq/client";

Basic Usage

import { Client } from "@notionhq/client";

// Initialize client with authentication
const notion = new Client({
  auth: process.env.NOTION_TOKEN,
});

// List users in workspace
const users = await notion.users.list({});

// Create a new page
const page = await notion.pages.create({
  parent: { database_id: "your-database-id" },
  properties: {
    title: {
      title: [{ text: { content: "New Page" } }],
    },
  },
});

// Query a database
const database = await notion.databases.retrieve({
  database_id: "your-database-id",
});

Architecture

The Notion SDK is built around several key components:

Client Class: Main entry point providing organized endpoint namespaces (blocks, pages, databases, users, etc.)
Type System: Comprehensive TypeScript definitions for all API objects and operations (150+ types)
Error Handling: Specialized error classes with specific error codes for API and client errors
Pagination Helpers: Utilities for handling paginated API responses
Logging System: Configurable logging with multiple severity levels
OAuth Support: Complete OAuth flow implementation for app integrations

Capabilities

Client Configuration

Client initialization and configuration options for authentication, timeouts, logging, and API versioning.

class Client {
  constructor(options?: ClientOptions);
}

interface ClientOptions {
  auth?: string;
  timeoutMs?: number;
  baseUrl?: string;
  logLevel?: LogLevel;
  logger?: Logger;
  notionVersion?: string;
  fetch?: SupportedFetch;
  agent?: Agent;
}

Client Configuration

Page Operations

Create, retrieve, and update pages within Notion workspaces. Pages can be standalone or part of databases.

pages: {
  create(args: CreatePageParameters): Promise<CreatePageResponse>;
  retrieve(args: GetPageParameters): Promise<GetPageResponse>;
  update(args: UpdatePageParameters): Promise<UpdatePageResponse>;
  properties: {
    retrieve(args: GetPagePropertyParameters): Promise<GetPagePropertyResponse>;
  };
}

Page Operations

Database Operations

Manage Notion databases including creation, updates, and retrieval of database schemas and metadata.

databases: {
  retrieve(args: GetDatabaseParameters): Promise<GetDatabaseResponse>;
  create(args: CreateDatabaseParameters): Promise<CreateDatabaseResponse>;
  update(args: UpdateDatabaseParameters): Promise<UpdateDatabaseResponse>;
}

Database Operations

Data Source Operations

Query and manage data sources (database content) with filtering, sorting, and pagination capabilities.

dataSources: {
  retrieve(args: GetDataSourceParameters): Promise<GetDataSourceResponse>;
  create(args: CreateDataSourceParameters): Promise<CreateDataSourceResponse>;
  update(args: UpdateDataSourceParameters): Promise<UpdateDataSourceResponse>;
  query(args: QueryDataSourceParameters): Promise<QueryDataSourceResponse>;
}

Data Source Operations

Block Operations

Manipulate page content through blocks - the building blocks of Notion pages including text, images, lists, and more.

blocks: {
  retrieve(args: GetBlockParameters): Promise<GetBlockResponse>;
  update(args: UpdateBlockParameters): Promise<UpdateBlockResponse>;
  delete(args: DeleteBlockParameters): Promise<DeleteBlockResponse>;
  children: {
    append(args: AppendBlockChildrenParameters): Promise<AppendBlockChildrenResponse>;
    list(args: ListBlockChildrenParameters): Promise<ListBlockChildrenResponse>;
  };
}

Block Operations

User Management

Retrieve information about users in the Notion workspace including the current authenticated user.

users: {
  retrieve(args: GetUserParameters): Promise<GetUserResponse>;
  list(args: ListUsersParameters): Promise<ListUsersResponse>;
  me(args: GetSelfParameters): Promise<GetSelfResponse>;
}

User Management

Comments

Create and manage comments on pages and blocks for collaboration features.

comments: {
  create(args: CreateCommentParameters): Promise<CreateCommentResponse>;
  list(args: ListCommentsParameters): Promise<ListCommentsResponse>;
  retrieve(args: GetCommentParameters): Promise<GetCommentResponse>;
}

Comments

File Uploads

Handle file uploads to Notion including creation, sending, and completion of upload processes.

fileUploads: {
  create(args: CreateFileUploadParameters): Promise<CreateFileUploadResponse>;
  retrieve(args: GetFileUploadParameters): Promise<GetFileUploadResponse>;
  send(args: SendFileUploadParameters): Promise<SendFileUploadResponse>;
  complete(args: CompleteFileUploadParameters): Promise<CompleteFileUploadResponse>;
  list(args: ListFileUploadsParameters): Promise<ListFileUploadsResponse>;
}

File Uploads

Search

Search across the entire Notion workspace for pages, databases, and other content.

search(args: SearchParameters): Promise<SearchResponse>;

OAuth Authentication

Complete OAuth flow implementation for Notion app integrations including token exchange and management.

oauth: {
  token(args: OauthTokenParameters): Promise<OauthTokenResponse>;
  revoke(args: OauthRevokeParameters): Promise<OauthRevokeResponse>;
  introspect(args: OauthIntrospectParameters): Promise<OauthIntrospectResponse>;
}

OAuth Authentication

Error Handling

Comprehensive error handling with specific error types and codes for different failure scenarios.

enum APIErrorCode {
  Unauthorized = "unauthorized";
  RestrictedResource = "restricted_resource";
  ObjectNotFound = "object_not_found";
  RateLimited = "rate_limited";
  InvalidJSON = "invalid_json";
  InvalidRequestURL = "invalid_request_url";
  InvalidRequest = "invalid_request";
  ValidationError = "validation_error";
  ConflictError = "conflict_error";
  InternalServerError = "internal_server_error";
  ServiceUnavailable = "service_unavailable";
}

function isNotionClientError(error: unknown): error is NotionClientError;

Error Handling

Pagination Helpers

Utility functions for handling paginated API responses with automatic cursor management.

function iteratePaginatedAPI<T>(
  listFn: Function,
  args: any
): AsyncIterableIterator<T>;

function collectPaginatedAPI<T>(
  listFn: Function,
  args: any
): Promise<T[]>;

Pagination Helpers

Types

Core shared types used across multiple capabilities:

enum LogLevel {
  DEBUG = "debug";
  INFO = "info"; 
  WARN = "warn";
  ERROR = "error";
}

interface Logger {
  (level: LogLevel, message: string, extraInfo: Record<string, unknown>): void;
}

type UserObjectResponse = PersonUserObjectResponse | BotUserObjectResponse;
type RichTextItemResponse = TextRichTextItemResponse | MentionRichTextItemResponse | EquationRichTextItemResponse;
type BlockObjectResponse = ParagraphBlockObjectResponse | Heading1BlockObjectResponse | /* ... all block types ... */;

Install with Tessl CLI