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

Page Operations

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

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

Capabilities

Create Page

Create a new page in a Notion workspace, either as a standalone page or as a database entry.

/**
 * Create a new page
 * @param args - Page creation parameters
 * @returns Promise resolving to created page
 */
pages.create(args: CreatePageParameters): Promise<CreatePageResponse>;

interface CreatePageParameters {
  /** Parent page or database for the new page */
  parent: {
    type: "page_id";
    page_id: string;
  } | {
    type: "database_id";
    database_id: string;
  };
  /** Page properties (required for database pages) */
  properties?: Record<string, PropertyValue>;
  /** Page content as an array of blocks */
  children?: BlockObjectRequest[];
  /** Page icon */
  icon?: {
    type: "emoji";
    emoji: string;
  } | {
    type: "external";
    external: { url: string };
  } | {
    type: "file";
    file: { url: string; expiry_time: string };
  };
  /** Page cover image */
  cover?: {
    type: "external";
    external: { url: string };
  } | {
    type: "file";
    file: { url: string; expiry_time: string };
  };
}

type CreatePageResponse = PageObjectResponse;

Usage Examples:

// Create a standalone page
const page = await notion.pages.create({
  parent: { type: "page_id", page_id: "parent-page-id" },
  properties: {
    title: {
      title: [{ text: { content: "My New Page" } }],
    },
  },
});

// Create a database page with properties
const databasePage = await notion.pages.create({
  parent: { type: "database_id", database_id: "database-id" },
  properties: {
    Name: {
      title: [{ text: { content: "Task Name" } }],
    },
    Status: {
      select: { name: "In Progress" },
    },
    Priority: {
      number: 3,
    },
  },
});

// Create page with content blocks
const pageWithContent = await notion.pages.create({
  parent: { type: "page_id", page_id: "parent-id" },
  properties: {
    title: { title: [{ text: { content: "Page with Content" } }] },
  },
  children: [
    {
      type: "paragraph",
      paragraph: {
        rich_text: [{ text: { content: "This is a paragraph." } }],
      },
    },
    {
      type: "heading_1",
      heading_1: {
        rich_text: [{ text: { content: "Heading 1" } }],
      },
    },
  ],
});

Retrieve Page

Get a page by its ID, including its properties and metadata.

/**
 * Retrieve a page by ID
 * @param args - Page retrieval parameters
 * @returns Promise resolving to page object
 */
pages.retrieve(args: GetPageParameters): Promise<GetPageResponse>;

interface GetPageParameters {
  /** ID of the page to retrieve */
  page_id: string;
  /** Specific properties to include in response */
  filter_properties?: string[];
}

type GetPageResponse = PageObjectResponse;

Usage Examples:

// Get a page
const page = await notion.pages.retrieve({ 
  page_id: "page-id-here" 
});

// Get page with specific properties only
const page = await notion.pages.retrieve({
  page_id: "page-id-here",
  filter_properties: ["Name", "Status"],
});

Update Page

Update page properties, icon, cover, or archive status.

/**
 * Update a page's properties
 * @param args - Page update parameters
 * @returns Promise resolving to updated page
 */
pages.update(args: UpdatePageParameters): Promise<UpdatePageResponse>;

interface UpdatePageParameters {
  /** ID of the page to update */
  page_id: string;
  /** Properties to update */
  properties?: Record<string, PropertyValue | null>;
  /** Archive the page */
  archived?: boolean;
  /** Update page icon */
  icon?: {
    type: "emoji";
    emoji: string;
  } | {
    type: "external";
    external: { url: string };
  } | {
    type: "file";
    file: { url: string; expiry_time: string };
  } | null;
  /** Update page cover */
  cover?: {
    type: "external";
    external: { url: string };
  } | {
    type: "file";
    file: { url: string; expiry_time: string };
  } | null;
}

type UpdatePageResponse = PageObjectResponse;

Usage Examples:

// Update page properties
const updatedPage = await notion.pages.update({
  page_id: "page-id",
  properties: {
    Status: {
      select: { name: "Complete" },
    },
    Priority: {
      number: 5,
    },
  },
});

// Archive a page
const archivedPage = await notion.pages.update({
  page_id: "page-id",
  archived: true,
});

// Update page icon and cover
const updatedPage = await notion.pages.update({
  page_id: "page-id", 
  icon: {
    type: "emoji",
    emoji: "📝",
  },
  cover: {
    type: "external",
    external: { url: "https://example.com/cover.jpg" },
  },
});

Retrieve Page Property

Get the value of a specific page property, particularly useful for properties with large values.

/**
 * Retrieve a specific page property
 * @param args - Page property retrieval parameters
 * @returns Promise resolving to property value
 */
pages.properties.retrieve(args: GetPagePropertyParameters): Promise<GetPagePropertyResponse>;

interface GetPagePropertyParameters {
  /** ID of the page */
  page_id: string;
  /** ID of the property to retrieve */
  property_id: string;
  /** Pagination cursor for large property values */
  start_cursor?: string;
  /** Page size for paginated results */
  page_size?: number;
}

type GetPagePropertyResponse = PropertyItemObjectResponse | PropertyItemListResponse;

Usage Examples:

// Get a specific property
const property = await notion.pages.properties.retrieve({
  page_id: "page-id",
  property_id: "property-id",
});

// Get paginated property results
const propertyPage = await notion.pages.properties.retrieve({
  page_id: "page-id",
  property_id: "property-id",
  start_cursor: "cursor-token",
  page_size: 100,
});

Types

interface PageObjectResponse {
  object: "page";
  id: string;
  created_time: string;
  created_by: PartialUserObjectResponse;
  last_edited_time: string;
  last_edited_by: PartialUserObjectResponse;
  archived: boolean;
  icon?: {
    type: "emoji";
    emoji: string;
  } | {
    type: "external";
    external: { url: string };
  } | {
    type: "file";
    file: { url: string; expiry_time: string };
  };
  cover?: {
    type: "external";
    external: { url: string };
  } | {
    type: "file";
    file: { url: string; expiry_time: string };
  };
  properties: Record<string, PropertyItemObjectResponse>;
  parent: {
    type: "database_id";
    database_id: string;
  } | {
    type: "page_id";
    page_id: string;
  } | {
    type: "workspace";
    workspace: true;
  };
  url: string;
  public_url?: string;
}

interface PartialPageObjectResponse {
  object: "page";
  id: string;
}

type PropertyValue = 
  | { title: RichTextItemResponse[] }
  | { rich_text: RichTextItemResponse[] }
  | { number: number | null }
  | { select: { name: string } | null }
  | { multi_select: { name: string }[] }
  | { date: { start: string; end?: string; time_zone?: string } | null }
  | { checkbox: boolean }
  | { url: string | null }
  | { email: string | null }
  | { phone_number: string | null }
  | { relation: { id: string }[] }
  | { people: PartialUserObjectResponse[] }
  | { files: FileObjectResponse[] };

interface PropertyItemListResponse {
  object: "list";
  results: PropertyItemObjectResponse[];
  next_cursor: string | null;
  has_more: boolean;
  type: string;
  property_item: Record<string, unknown>;
}

Install with Tessl CLI