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

Data Source Operations

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

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

Capabilities

Query Data Source

Query a database for pages matching specific criteria with filtering, sorting, and pagination.

/**
 * Query a data source (database) for pages
 * @param args - Query parameters including filters and sorting
 * @returns Promise resolving to query results
 */
dataSources.query(args: QueryDataSourceParameters): Promise<QueryDataSourceResponse>;

interface QueryDataSourceParameters {
  /** ID of the database to query */
  data_source_id: string;
  /** Filter criteria for pages */
  filter?: FilterObject;
  /** Sort criteria for results */
  sorts?: SortObject[];
  /** Pagination cursor */
  start_cursor?: string;
  /** Page size (max 100) */
  page_size?: number;
  /** Properties to include in response */
  filter_properties?: string[];
}

type QueryDataSourceResponse = {
  object: "list";
  results: PageObjectResponse[];
  next_cursor: string | null;
  has_more: boolean;
  type: "page_or_database";
  page_or_database: Record<string, unknown>;
};

Usage Examples:

// Basic query
const pages = await notion.dataSources.query({
  data_source_id: "database-id",
});

// Query with filter
const filteredPages = await notion.dataSources.query({
  data_source_id: "database-id",
  filter: {
    property: "Status",
    select: {
      equals: "In Progress",
    },
  },
});

// Query with multiple filters and sorting
const results = await notion.dataSources.query({
  data_source_id: "database-id",
  filter: {
    and: [
      {
        property: "Status",
        select: {
          equals: "Complete",
        },
      },
      {
        property: "Priority",
        number: {
          greater_than: 3,
        },
      },
    ],
  },
  sorts: [
    {
      property: "Created",
      direction: "descending",
    },
  ],
  page_size: 50,
});

// Paginated query
const nextPage = await notion.dataSources.query({
  data_source_id: "database-id",
  start_cursor: "cursor-token",
  page_size: 25,
});

Retrieve Data Source

Get data source metadata and schema information.

/**
 * Retrieve a data source by ID
 * @param args - Data source retrieval parameters
 * @returns Promise resolving to data source object
 */
dataSources.retrieve(args: GetDataSourceParameters): Promise<GetDataSourceResponse>;

interface GetDataSourceParameters {
  /** ID of the data source to retrieve */
  data_source_id: string;
}

type GetDataSourceResponse = DataSourceObjectResponse;

Usage Examples:

// Get data source information
const dataSource = await notion.dataSources.retrieve({
  data_source_id: "data-source-id",
});

Create Data Source

Create a new data source from an existing database.

/**
 * Create a new data source
 * @param args - Data source creation parameters
 * @returns Promise resolving to created data source
 */
dataSources.create(args: CreateDataSourceParameters): Promise<CreateDataSourceResponse>;

interface CreateDataSourceParameters {
  /** Parent page for the data source */
  parent: {
    type: "page_id";
    page_id: string;
  };
  /** Database to use as source */
  database_id: string;
  /** Data source view configuration */
  view?: {
    type: "table" | "board" | "timeline" | "calendar" | "gallery" | "list";
  };
}

type CreateDataSourceResponse = DataSourceObjectResponse;

Usage Examples:

// Create data source from database
const dataSource = await notion.dataSources.create({
  parent: { type: "page_id", page_id: "parent-page-id" },
  database_id: "source-database-id",
  view: { type: "table" },
});

Update Data Source

Update data source configuration and settings.

/**
 * Update a data source
 * @param args - Data source update parameters
 * @returns Promise resolving to updated data source
 */
dataSources.update(args: UpdateDataSourceParameters): Promise<UpdateDataSourceResponse>;

interface UpdateDataSourceParameters {
  /** ID of the data source to update */
  data_source_id: string;
  /** Updated view configuration */
  view?: {
    type: "table" | "board" | "timeline" | "calendar" | "gallery" | "list";
  };
  /** Archive the data source */
  archived?: boolean;
}

type UpdateDataSourceResponse = DataSourceObjectResponse;

Usage Examples:

// Update data source view type
const updatedDataSource = await notion.dataSources.update({
  data_source_id: "data-source-id",
  view: { type: "board" },
});

// Archive data source
const archivedDataSource = await notion.dataSources.update({
  data_source_id: "data-source-id",
  archived: true,
});

Types

interface DataSourceObjectResponse {
  object: "data_source";
  id: string;
  created_time: string;
  created_by: PartialUserObjectResponse;
  last_edited_time: string;
  last_edited_by: PartialUserObjectResponse;
  archived: boolean;
  parent: {
    type: "page_id";
    page_id: string;
  };
  database_id: string;
  view: {
    type: "table" | "board" | "timeline" | "calendar" | "gallery" | "list";
  };
}

interface PartialDataSourceObjectResponse {
  object: "data_source";
  id: string;
}

type FilterObject = 
  | PropertyFilter
  | CompoundFilter;

interface PropertyFilter {
  property: string;
  title?: TextFilter;
  rich_text?: TextFilter;
  number?: NumberFilter;
  checkbox?: CheckboxFilter;
  select?: SelectFilter;
  multi_select?: MultiSelectFilter;
  date?: DateFilter;
  people?: PeopleFilter;
  files?: FilesFilter;
  url?: TextFilter;
  email?: TextFilter;
  phone_number?: TextFilter;
  relation?: RelationFilter;
  created_by?: PeopleFilter;
  created_time?: DateFilter;
  last_edited_by?: PeopleFilter;
  last_edited_time?: DateFilter;
  formula?: FormulaFilter;
  rollup?: RollupFilter;
  status?: StatusFilter;
  unique_id?: UniqueIdFilter;
  verification?: VerificationFilter;
}

interface CompoundFilter {
  and?: FilterObject[];
  or?: FilterObject[];
}

interface TextFilter {
  equals?: string;
  does_not_equal?: string;
  contains?: string;
  does_not_contain?: string;
  starts_with?: string;
  ends_with?: string;
  is_empty?: true;
  is_not_empty?: true;
}

interface NumberFilter {
  equals?: number;
  does_not_equal?: number;
  greater_than?: number;
  less_than?: number;
  greater_than_or_equal_to?: number;
  less_than_or_equal_to?: number;
  is_empty?: true;
  is_not_empty?: true;
}

interface CheckboxFilter {
  equals?: boolean;
  does_not_equal?: boolean;
}

interface SelectFilter {
  equals?: string;
  does_not_equal?: string;
  is_empty?: true;
  is_not_empty?: true;
}

interface MultiSelectFilter {
  contains?: string;
  does_not_contain?: string;
  is_empty?: true;
  is_not_empty?: true;
}

interface DateFilter {
  equals?: string;
  before?: string;
  after?: string;
  on_or_before?: string;
  on_or_after?: string;
  past_week?: Record<string, never>;
  past_month?: Record<string, never>;
  past_year?: Record<string, never>;
  next_week?: Record<string, never>;
  next_month?: Record<string, never>;
  next_year?: Record<string, never>;
  is_empty?: true;
  is_not_empty?: true;
}

interface PeopleFilter {
  contains?: string;
  does_not_contain?: string;
  is_empty?: true;
  is_not_empty?: true;
}

interface FilesFilter {
  is_empty?: true;
  is_not_empty?: true;
}

interface RelationFilter {
  contains?: string;
  does_not_contain?: string;
  is_empty?: true;
  is_not_empty?: true;
}

interface FormulaFilter {
  string?: TextFilter;
  checkbox?: CheckboxFilter;
  number?: NumberFilter;
  date?: DateFilter;
}

interface RollupFilter {
  any?: PropertyFilter;
  every?: PropertyFilter;
  none?: PropertyFilter;
  number?: NumberFilter;
  date?: DateFilter;
}

interface StatusFilter {
  equals?: string;
  does_not_equal?: string;
  is_empty?: true;
  is_not_empty?: true;
}

interface UniqueIdFilter {
  equals?: number;
  does_not_equal?: number;
  greater_than?: number;
  less_than?: number;
  greater_than_or_equal_to?: number;
  less_than_or_equal_to?: number;
}

interface VerificationFilter {
  equals?: "verified" | "unverified";
  does_not_equal?: "verified" | "unverified";
}

interface SortObject {
  property?: string;
  timestamp?: "created_time" | "last_edited_time";
  direction: "ascending" | "descending";
}

Install with Tessl CLI