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

Block Operations

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

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

Capabilities

Retrieve Block

Get a block by its ID, including its content and metadata.

/**
 * Retrieve a block by ID
 * @param args - Block retrieval parameters
 * @returns Promise resolving to block object
 */
blocks.retrieve(args: GetBlockParameters): Promise<GetBlockResponse>;

interface GetBlockParameters {
  /** ID of the block to retrieve */
  block_id: string;
}

type GetBlockResponse = BlockObjectResponse;

Usage Examples:

// Get a block
const block = await notion.blocks.retrieve({
  block_id: "block-id-here",
});

console.log(block.type); // Block type (paragraph, heading_1, etc.)
console.log(block[block.type]); // Block-specific content

Update Block

Update the content of an existing block.

/**
 * Update a block's content
 * @param args - Block update parameters
 * @returns Promise resolving to updated block
 */
blocks.update(args: UpdateBlockParameters): Promise<UpdateBlockResponse>;

interface UpdateBlockParameters {
  /** ID of the block to update */
  block_id: string;
  /** Block content specific to block type */
  [blockType: string]: any;
  /** Archive the block */
  archived?: boolean;
}

type UpdateBlockResponse = BlockObjectResponse;

Usage Examples:

// Update paragraph block
const updatedBlock = await notion.blocks.update({
  block_id: "block-id",
  paragraph: {
    rich_text: [
      {
        text: { content: "Updated paragraph content" },
      },
    ],
  },
});

// Update heading block
const updatedHeading = await notion.blocks.update({
  block_id: "heading-block-id",
  heading_1: {
    rich_text: [
      {
        text: { content: "Updated Heading" },
        annotations: { bold: true },
      },
    ],
  },
});

// Archive a block
const archivedBlock = await notion.blocks.update({
  block_id: "block-id",
  archived: true,
});

Delete Block

Delete a block permanently.

/**
 * Delete a block
 * @param args - Block deletion parameters
 * @returns Promise resolving to deleted block
 */
blocks.delete(args: DeleteBlockParameters): Promise<DeleteBlockResponse>;

interface DeleteBlockParameters {
  /** ID of the block to delete */
  block_id: string;
}

type DeleteBlockResponse = BlockObjectResponse;

Usage Examples:

// Delete a block
const deletedBlock = await notion.blocks.delete({
  block_id: "block-id-to-delete",
});

Append Block Children

Add child blocks to an existing block or page.

/**
 * Append child blocks to a parent block
 * @param args - Block children append parameters
 * @returns Promise resolving to operation result
 */
blocks.children.append(args: AppendBlockChildrenParameters): Promise<AppendBlockChildrenResponse>;

interface AppendBlockChildrenParameters {
  /** ID of the parent block or page */
  block_id: string;
  /** Array of block objects to append */
  children: BlockObjectRequest[];
  /** Add children after specific block ID */
  after?: string;
}

type AppendBlockChildrenResponse = {
  object: "list";
  results: BlockObjectResponse[];
  next_cursor: string | null;
  has_more: boolean;
  type: "block";
  block: Record<string, unknown>;
  request_id: string;
};

Usage Examples:

// Append text blocks
const result = await notion.blocks.children.append({
  block_id: "parent-block-id",
  children: [
    {
      type: "paragraph",
      paragraph: {
        rich_text: [{ text: { content: "First paragraph" } }],
      },
    },
    {
      type: "heading_2",
      heading_2: {
        rich_text: [{ text: { content: "Section Heading" } }],
      },
    },
    {
      type: "bulleted_list_item",
      bulleted_list_item: {
        rich_text: [{ text: { content: "First bullet point" } }],
      },
    },
  ],
});

// Append complex blocks
const complexBlocks = await notion.blocks.children.append({
  block_id: "page-id",
  children: [
    {
      type: "callout",
      callout: {
        rich_text: [{ text: { content: "Important note" } }],
        icon: { type: "emoji", emoji: "⚠️" },
        color: "yellow_background",
      },
    },
    {
      type: "code",
      code: {
        caption: [],
        rich_text: [{ text: { content: "console.log('Hello World');" } }],
        language: "javascript",
      },
    },
  ],
});

List Block Children

Retrieve all child blocks of a parent block or page.

/**
 * List child blocks of a parent block
 * @param args - Block children list parameters
 * @returns Promise resolving to list of child blocks
 */
blocks.children.list(args: ListBlockChildrenParameters): Promise<ListBlockChildrenResponse>;

interface ListBlockChildrenParameters {
  /** ID of the parent block or page */
  block_id: string;
  /** Pagination cursor */
  start_cursor?: string;
  /** Page size (max 100) */
  page_size?: number;
}

type ListBlockChildrenResponse = {
  object: "list";
  results: BlockObjectResponse[];
  next_cursor: string | null;
  has_more: boolean;
  type: "block";
  block: Record<string, unknown>;
};

Usage Examples:

// Get all child blocks
const children = await notion.blocks.children.list({
  block_id: "parent-block-id",
});

// Paginated retrieval
const childrenPage = await notion.blocks.children.list({
  block_id: "parent-block-id",
  start_cursor: "cursor-token",
  page_size: 50,
});

// Process all children with pagination
let cursor: string | undefined;
let allChildren: BlockObjectResponse[] = [];

do {
  const response = await notion.blocks.children.list({
    block_id: "parent-block-id",
    start_cursor: cursor,
  });
  
  allChildren.push(...response.results);
  cursor = response.next_cursor || undefined;
} while (cursor);

Types

type BlockObjectResponse = 
  | ParagraphBlockObjectResponse
  | Heading1BlockObjectResponse
  | Heading2BlockObjectResponse
  | Heading3BlockObjectResponse
  | BulletedListItemBlockObjectResponse
  | NumberedListItemBlockObjectResponse
  | QuoteBlockObjectResponse
  | ToDoBlockObjectResponse
  | ToggleBlockObjectResponse
  | TemplateBlockObjectResponse
  | SyncedBlockBlockObjectResponse
  | ChildPageBlockObjectResponse
  | ChildDatabaseBlockObjectResponse
  | EquationBlockObjectResponse
  | CodeBlockObjectResponse
  | CalloutBlockObjectResponse
  | DividerBlockObjectResponse
  | BreadcrumbBlockObjectResponse
  | TableOfContentsBlockObjectResponse
  | ColumnListBlockObjectResponse
  | ColumnBlockObjectResponse
  | LinkToPageBlockObjectResponse
  | TableBlockObjectResponse  
  | TableRowBlockObjectResponse
  | EmbedBlockObjectResponse
  | BookmarkBlockObjectResponse
  | ImageBlockObjectResponse
  | VideoBlockObjectResponse
  | PdfBlockObjectResponse
  | FileBlockObjectResponse
  | AudioBlockObjectResponse
  | LinkPreviewBlockObjectResponse
  | UnsupportedBlockObjectResponse;

interface PartialBlockObjectResponse {
  object: "block";
  id: string;
}

interface BlockObjectRequest {
  type: string;
  [blockType: string]: any;
}

interface ParagraphBlockObjectResponse {
  type: "paragraph";
  paragraph: {
    rich_text: RichTextItemResponse[];
    color: string;
    children?: BlockObjectResponse[];
  };
  object: "block";
  id: string;
  parent: ParentObject;
  created_time: string;
  created_by: PartialUserObjectResponse;
  last_edited_time: string;
  last_edited_by: PartialUserObjectResponse;
  archived: boolean;
  has_children: boolean;
}

interface Heading1BlockObjectResponse {
  type: "heading_1";
  heading_1: {
    rich_text: RichTextItemResponse[];
    color: string;
    is_toggleable: boolean;
    children?: BlockObjectResponse[];
  };
  object: "block";
  id: string;
  parent: ParentObject;
  created_time: string;
  created_by: PartialUserObjectResponse;
  last_edited_time: string;
  last_edited_by: PartialUserObjectResponse;
  archived: boolean;
  has_children: boolean;
}

interface CalloutBlockObjectResponse {
  type: "callout";
  callout: {
    rich_text: RichTextItemResponse[];
    icon?: {
      type: "emoji";
      emoji: string;
    } | {
      type: "external";
      external: { url: string };
    } | {
      type: "file";
      file: { url: string; expiry_time: string };
    };
    color: string;
    children?: BlockObjectResponse[];
  };
  object: "block";
  id: string;
  parent: ParentObject;
  created_time: string;
  created_by: PartialUserObjectResponse;
  last_edited_time: string;
  last_edited_by: PartialUserObjectResponse;
  archived: boolean;
  has_children: boolean;
}

interface CodeBlockObjectResponse {
  type: "code";
  code: {
    caption: RichTextItemResponse[];
    rich_text: RichTextItemResponse[];
    language: string;
  };
  object: "block";
  id: string;
  parent: ParentObject;
  created_time: string;
  created_by: PartialUserObjectResponse;
  last_edited_time: string;
  last_edited_by: PartialUserObjectResponse;
  archived: boolean;
  has_children: boolean;
}

type ParentObject = 
  | { type: "database_id"; database_id: string }
  | { type: "page_id"; page_id: string }
  | { type: "block_id"; block_id: string }
  | { type: "workspace"; workspace: true };

Install with Tessl CLI