tessl/npm-notion-types

TypeScript types for core Notion data structures.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Block Types

Name: tessl/npm-notion-types
Author: tessl

Complete type definitions for all Notion block types representing pages, text content, media, interactive elements, and structural components.

Capabilities

Base Block Interface

All blocks inherit from the BaseBlock interface which provides common properties.

/**
 * Base properties shared by all blocks
 */
interface BaseBlock {
  /** Unique block identifier */
  id: ID;
  /** Type of block */
  type: BlockType;
  /** Block-specific properties */
  properties?: any;
  /** Block formatting options */
  format?: any;
  /** Array of child block IDs */
  content?: ID[];
  /** Space ID (optional) */
  space_id?: ID;
  /** Parent block ID */
  parent_id: ID;
  /** Parent table type */
  parent_table: string | 'space' | 'block' | 'table';
  /** Block version number */
  version: number;
  /** Creation timestamp */
  created_time: number;
  /** Last edit timestamp */
  last_edited_time: number;
  /** Whether block is active */
  alive: boolean;
  /** Creator table reference */
  created_by_table: string;
  /** Creator user ID */
  created_by_id: ID;
  /** Last editor table reference */
  last_edited_by_table: string;
  /** Last editor user ID */
  last_edited_by_id: ID;
}

Block Type Union

/**
 * Union type of all supported block types
 */
type BlockType =
  | 'page'
  | 'text'
  | 'bookmark'
  | 'bulleted_list'
  | 'numbered_list'
  | 'header'
  | 'sub_header'
  | 'sub_sub_header'
  | 'quote'
  | 'equation'
  | 'to_do'
  | 'table_of_contents'
  | 'divider'
  | 'column_list'
  | 'column'
  | 'callout'
  | 'toggle'
  | 'image'
  | 'embed'
  | 'gist'
  | 'video'
  | 'figma'
  | 'typeform'
  | 'replit'
  | 'codepen'
  | 'excalidraw'
  | 'tweet'
  | 'maps'
  | 'pdf'
  | 'audio'
  | 'drive'
  | 'file'
  | 'code'
  | 'collection_view'
  | 'collection_view_page'
  | 'transclusion_container'
  | 'transclusion_reference'
  | 'alias'
  | 'table'
  | 'table_row'
  | 'external_object_instance'
  | 'breadcrumb'
  | 'miro'
  | string; // fallback for unknown blocks

/**
 * Union type of all specific block interfaces
 */
type Block =
  | TextBlock
  | PageBlock
  | BulletedListBlock
  | NumberedListBlock
  | HeaderBlock
  | SubHeaderBlock
  | SubSubHeaderBlock
  | TodoBlock
  | TableOfContentsBlock
  | DividerBlock
  | ColumnListBlock
  | ColumnBlock
  | QuoteBlock
  | EquationBlock
  | CodeBlock
  | ImageBlock
  | VideoBlock
  | FigmaBlock
  | TypeformBlock
  | ReplitBlock
  | CodepenBlock
  | ExcalidrawBlock
  | TweetBlock
  | MapsBlock
  | AudioBlock
  | PdfBlock
  | MiroBlock
  | GoogleDriveBlock
  | FileBlock
  | EmbedBlock
  | GistBlock
  | CalloutBlock
  | BookmarkBlock
  | ToggleBlock
  | CollectionViewBlock
  | CollectionViewPageBlock
  | SyncBlock
  | SyncPointerBlock
  | PageLink
  | TableBlock
  | TableRowBlock
  | ExternalObjectInstance
  | BreadcrumbInstance;

Base Text Block

Base interface for blocks containing text content.

/**
 * Base interface for text-containing blocks
 */
interface BaseTextBlock extends BaseBlock {
  /** Optional child blocks */
  content?: string[];
  /** Text properties */
  properties?: {
    title: Decoration[];
  };
  /** Text formatting */
  format?: {
    block_color: Color;
  };
}

Page Blocks

/**
 * Base interface for page-like blocks
 */
interface BasePageBlock extends BaseBlock {
  properties?: {
    title: Decoration[];
  };
  format: {
    page_full_width?: boolean;
    page_small_text?: boolean;
    page_cover_position?: number;
    card_cover_position?: number;
    block_locked?: boolean;
    block_locked_by?: string;
    page_cover?: string;
    page_icon?: string;
    block_color?: Color;
  };
  permissions: { role: Role; type: string }[];
  file_ids?: string[];
}

/**
 * Page block representing a Notion page
 */
interface PageBlock extends BasePageBlock {
  type: 'page';
}

Text Content Blocks

/**
 * Plain text block
 */
interface TextBlock extends BaseTextBlock {
  type: 'text';
}

/**
 * Bulleted list item
 */
interface BulletedListBlock extends BaseTextBlock {
  type: 'bulleted_list';
}

/**
 * Numbered list item
 */
interface NumberedListBlock extends BaseTextBlock {
  type: 'numbered_list';
}

/**
 * Level 1 header
 */
interface HeaderBlock extends BaseTextBlock {
  type: 'header';
  format?: {
    block_color: Color;
    toggleable?: boolean;
  };
}

/**
 * Level 2 header
 */
interface SubHeaderBlock extends BaseTextBlock {
  type: 'sub_header';
  format?: {
    block_color: Color;
    toggleable?: boolean;
  };
}

/**
 * Level 3 header
 */
interface SubSubHeaderBlock extends BaseTextBlock {
  type: 'sub_sub_header';
  format?: {
    block_color: Color;
    toggleable?: boolean;
  };
}

/**
 * Quote block
 */
interface QuoteBlock extends BaseTextBlock {
  type: 'quote';
}

/**
 * Mathematical equation block
 */
interface EquationBlock extends BaseTextBlock {
  type: 'equation';
}

/**
 * Todo/checkbox block
 */
interface TodoBlock extends BaseTextBlock {
  type: 'to_do';
  properties: {
    title: Decoration[];
    checked: (['Yes'] | ['No'])[];
  };
}

Media and Content Blocks

/**
 * Base interface for media/content blocks
 */
interface BaseContentBlock extends BaseBlock {
  properties: {
    source: string[][];
    caption?: Decoration[];
  };
  format?: {
    block_alignment: 'center' | 'left' | 'right';
    block_width: number;
    block_height: number;
    display_source: string;
    block_full_width: boolean;
    block_page_width: boolean;
    block_aspect_ratio: number;
    block_preserve_scale: boolean;
  };
  file_ids?: string[];
}

/**
 * Image block
 */
interface ImageBlock extends BaseContentBlock {
  type: 'image';
}

/**
 * Video block
 */
interface VideoBlock extends BaseContentBlock {
  type: 'video';
}

/**
 * Audio block
 */
interface AudioBlock extends BaseContentBlock {
  type: 'audio';
}

/**
 * PDF document block
 */
interface PdfBlock extends BaseContentBlock {
  type: 'pdf';
}

/**
 * Generic embed block
 */
interface EmbedBlock extends BaseContentBlock {
  type: 'embed';
}

/**
 * GitHub Gist block
 */
interface GistBlock extends BaseContentBlock {
  type: 'gist';
}

Interactive Blocks

/**
 * Code snippet block
 */
interface CodeBlock extends BaseBlock {
  type: 'code';
  properties: {
    title: Decoration[];
    language: Decoration[];
    caption: Decoration[];
  };
}

/**
 * Callout/info block
 */
interface CalloutBlock extends BaseBlock {
  type: 'callout';
  format: {
    page_icon: string;
    block_color: Color;
  };
  properties: {
    title: Decoration[];
  };
}

/**
 * Collapsible toggle block
 */
interface ToggleBlock extends BaseBlock {
  type: 'toggle';
  properties: {
    title: Decoration[];
  };
}

/**
 * Web bookmark block
 */
interface BookmarkBlock extends BaseBlock {
  type: 'bookmark';
  properties: {
    link: Decoration[];
    title: Decoration[];
    description: Decoration[];
  };
  format: {
    block_color?: string;
    bookmark_icon: string;
    bookmark_cover: string;
  };
}

File and Attachment Blocks

/**
 * File attachment block
 */
interface FileBlock extends BaseBlock {
  type: 'file';
  properties: {
    title: Decoration[];
    size: Decoration[];
    source: string[][];
  };
  file_ids?: string[];
}

/**
 * Google Drive file block
 */
interface GoogleDriveBlock extends BaseContentBlock {
  type: 'drive';
  format: {
    drive_status: {
      authed: boolean;
      last_fetched: number;
    };
    drive_properties: {
      url: string;
      icon: string;
      title: string;
      file_id: string;
      trashed: boolean;
      version: string;
      thumbnail: string;
      user_name: string;
      modified_time: number;
    };
    block_alignment: 'center' | 'left' | 'right';
    block_width: number;
    block_height: number;
    display_source: string;
    block_full_width: boolean;
    block_page_width: boolean;
    block_aspect_ratio: number;
    block_preserve_scale: boolean;
  };
  file_ids?: string[];
}

Structural Blocks

/**
 * Table of contents block
 */
interface TableOfContentsBlock extends BaseBlock {
  type: 'table_of_contents';
  format?: {
    block_color: Color;
  };
}

/**
 * Horizontal divider block
 */
interface DividerBlock extends BaseBlock {
  type: 'divider';
}

/**
 * Column container block
 */
interface ColumnListBlock extends BaseBlock {
  type: 'column_list';
}

/**
 * Individual column block
 */
interface ColumnBlock extends BaseBlock {
  type: 'column';
  format: {
    column_ratio: number;
  };
}

Database Blocks

/**
 * Database view block
 */
interface CollectionViewBlock extends BaseContentBlock {
  type: 'collection_view';
  collection_id?: string;
  view_ids: ID[];
  format?: BaseContentBlock['format'] & {
    collection_pointer?: {
      id: string;
      spaceId: string;
      table: string;
    };
  };
}

/**
 * Full-page database view
 */
interface CollectionViewPageBlock extends BasePageBlock {
  type: 'collection_view_page';
  collection_id?: string;
  view_ids: ID[];
  format: BasePageBlock['format'] & {
    collection_pointer?: {
      id: string;
      spaceId: string;
      table: string;
    };
  };
}

/**
 * Table block
 */
interface TableBlock extends BaseBlock {
  type: 'table';
  collection_id: string;
  format: {
    collection_pointer: {
      id: string;
      table: string;
      spaceId: string;
    };
    table_block_column_format?: {
      [column: string]: { width?: number; color?: Color };
    };
    table_block_column_header: boolean;
    table_block_row_header: boolean;
    table_block_column_order: string[];
  };
  view_ids: ID[];
}

/**
 * Table row block
 */
interface TableRowBlock extends BaseBlock {
  type: 'table_row';
  properties: {
    [column: string]: Decoration[];
  };
}

Sync and Reference Blocks

/**
 * Sync block container
 */
interface SyncBlock extends BaseBlock {
  type: 'transclusion_container';
}

/**
 * Sync block reference
 */
interface SyncPointerBlock extends BaseBlock {
  type: 'transclusion_reference';
  format: {
    copied_from_pointer: {
      id: string;
      spaceid: string;
    };
    transclusion_reference_pointer: {
      id: string;
      spaceId: string;
    };
  };
}

/**
 * Page alias/link block
 */
interface PageLink extends BaseBlock {
  type: 'alias';
  format: {
    alias_pointer: {
      id: string;
    };
  };
}

Third-Party Integration Blocks

/**
 * Figma embed block
 */
interface FigmaBlock extends BaseContentBlock {
  type: 'figma';
}

/**
 * Typeform embed block
 */
interface TypeformBlock extends BaseContentBlock {
  type: 'typeform';
}

/**
 * Repl.it embed block
 */
interface ReplitBlock extends BaseContentBlock {
  type: 'replit';
}

/**
 * CodePen embed block
 */
interface CodepenBlock extends BaseContentBlock {
  type: 'codepen';
}

/**
 * Excalidraw diagram block
 */
interface ExcalidrawBlock extends BaseContentBlock {
  type: 'excalidraw';
}

/**
 * Twitter embed block
 */
interface TweetBlock extends BaseContentBlock {
  type: 'tweet';
}

/**
 * Map embed block
 */
interface MapsBlock extends BaseContentBlock {
  type: 'maps';
}

/**
 * Miro board block
 */
interface MiroBlock extends BaseContentBlock {
  type: 'miro';
}

/**
 * External object block
 */
interface ExternalObjectInstance extends BaseBlock {
  type: 'external_object_instance';
  format: {
    domain: string;
    original_url: string;
  };
}

/**
 * Breadcrumb navigation block
 */
interface BreadcrumbInstance extends BaseBlock {
  type: 'breadcrumb';
}

Usage Examples:

import { Block, PageBlock, TextBlock, ImageBlock } from "notion-types";

// Type guard function
function isPageBlock(block: Block): block is PageBlock {
  return block.type === 'page';
}

// Process different block types
function processBlock(block: Block) {
  switch (block.type) {
    case 'page':
      const pageBlock = block as PageBlock;
      console.log('Page:', pageBlock.properties?.title);
      break;
    case 'text':
      const textBlock = block as TextBlock;
      console.log('Text:', textBlock.properties?.title);
      break;
    case 'image':
      const imageBlock = block as ImageBlock;
      console.log('Image source:', imageBlock.properties.source);
      break;
  }
}

// Create a text block
const textBlock: TextBlock = {
  id: 'block-123',
  type: 'text',
  properties: {
    title: [['Hello, world!']]
  },
  parent_id: 'parent-456',
  parent_table: 'block',
  version: 1,
  created_time: Date.now(),
  last_edited_time: Date.now(),
  alive: true,
  created_by_table: 'notion_user',
  created_by_id: 'user-789',
  last_edited_by_table: 'notion_user',
  last_edited_by_id: 'user-789'
};

Install with Tessl CLI