notion-helper
Version:
A library of functions for working more easily with the Notion API
172 lines • 8.77 kB
text/typescript
/**
* Request shorthand methods - these allow you to call the methods of the request object directly. Import them directly into a file, or call them on NotionHelper.
* @namespace RequestShorthand
*/
/**
* Creates a new page in Notion and optionally appends child blocks to it.
* @memberof RequestShorthand
* @function
* @param {Object} options - The options for creating a page.
* @param {Object} options.data - The data for creating the page.
* @param {Object} options.data.parent - The parent of the page (must include data_source_id, page_id, or database_id (database_id is deprecated and will not work in databases with more than one data source)).
* @param {Object} [options.data.properties] - The properties of the page.
* @param {Object} [options.data.icon] - The icon of the page.
* @param {Object} [options.data.cover] - The cover of the page.
* @param {Array<Object>} [options.data.children] - An array of child blocks to add to the page.
* @param {Object} [options.client] - The Notion client object. Either this or apiCall must be provided.
* @param {Function} [options.apiCall] - A custom function for making API calls. Receives `{ type: 'create_page', data }` as argument. Either this or client must be provided.
* @param {Function} [options.getPage] - A function to extract the page data from the API response. Defaults to (response) => response.
* @param {Function} [options.getResults] - A function to extract results from the API response when appending blocks. Defaults to (response) => response.results.
* @param {number} [options.templateWaitMs=3000] - Milliseconds to wait after page creation when using templates, before appending children.
* @param {Function} [options.onTemplatePageCreated] - Optional callback function called after page creation but before appending children when using templates. Receives `{ page, template, fallbackWaitMs }` as parameter, where page is the created Notion page object, template is the template object used to create the page, and fallbackWaitMs is the value of templateWaitMs. Can throw an error to stop execution and prevent children appending. Alternatively, you can pass a number to templateWaitMs, which the callback can use in case it fails to directly verify the template is ready.
* @param {boolean} [options.skipAutoAppendOnTemplate=false] - If true, returns children to caller instead of auto-appending them when using templates.
* @returns {Promise<Object>} An object containing the API response for page creation and, if applicable, the result of appending children. When `skipAutoAppendOnTemplate` is true and templates are used, returns `{ apiResponse, pendingChildren, pageId }` instead.
* @throws {Error} If no parent is provided or if there's an error during page creation or block appending.
* @example
* // Using with Notion SDK client
* const notion = new Client({ auth: NOTION_TOKEN });
* const page = createNotion()
* .parentDataSource("your-data-source-id")
* .title("Name", "Charmander")
* .icon("https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/4.png")
* .richText("Category", "Lizard Pokémon")
* .quote("Obviously prefers hot places. When it rains, steam is said to spout from the tip of its tail.")
* .build()
*
* const result = await createPage({
* data: page.content,
* client: notion
* });
*
* // Using with custom API call function
* const apiCall = async ({ type, data }) => {
* if (type === 'create_page') {
* // Your custom API call implementation for page creation
* return await someHTTPClient.post('https://api.notion.com/v1/pages', { json: data });
* } else if (type === 'append_blocks') {
* // Your custom API call implementation for block appending
* const { block_id, children, after } = data;
* return await someHTTPClient.patch(`https://api.notion.com/v1/blocks/${block_id}/children`, {
* json: { children, ...(after && { after }) }
* });
* }
* };
*
* const result = await createPage({
* data: page.content,
* apiCall,
* getPage: (response) => response,
* getResults: (response) => response.results
* });
*/
export function createPage(options: {
data: {
parent: Object;
properties?: Object | undefined;
icon?: Object | undefined;
cover?: Object | undefined;
children?: Object[] | undefined;
};
client?: Object | undefined;
apiCall?: Function | undefined;
getPage?: Function | undefined;
getResults?: Function | undefined;
templateWaitMs?: number | undefined;
onTemplatePageCreated?: Function | undefined;
skipAutoAppendOnTemplate?: boolean | undefined;
}): Promise<Object>;
/**
* Appends a children block array to a parent block (or page). Handles nested blocks to any level via recursion.
* @memberof RequestShorthand
* @function
* @param {Object} options - The options for appending blocks.
* @param {string} options.block_id - The ID of the parent block to append children to. Can be a page ID.
* @param {Array<Object>} options.children - An array of child blocks to append.
* @param {Object} [options.client] - The Notion client object. Either this or apiCall must be provided.
* @param {Function} [options.apiCall] - A custom function for making API calls. Receives `{ type: 'append_blocks', data: { block_id, children, after } }` as argument. Either this or client must be provided.
* @param {Function} [options.getResults] - A function to extract results from the API response. Defaults to response => response.results, which will work if you pass a client object created with the Notion SDK: https://github.com/makenotion/notion-sdk-js. If you're passing a custom apiCall function, you should provide a matching getResults function that can handle the response and return the results array, which contains the created blocks.
* @returns {Promise<Object>} An object containing the API responses and the total number of API calls made.
* @throws {Error} If there's an error during the API call or block appending process.
* @example
* // Using with Notion SDK client
* const notion = new Client({ auth: NOTION_TOKEN });
* const childBlocks = createNotion().paragraph("A paragraph").build()
*
* const { apiResponses, apiCallCount } = await appendBlocks({
* block_id: 'your-block-id',
* children: childBlocks.content,
* client: notion
* });
*
* // Using with custom API call function (using ky)
* import ky from 'ky';
*
* const NOTION_TOKEN = 'your-notion-token';
*
* const apiCall = async ({ type, data }) => {
* const { block_id, children, after } = data;
* const response = await ky.patch(
* `https://api.notion.com/v1/blocks/${block_id}/children`,
* {
* json: { children, ...(after && { after }) },
* headers: {
* 'Authorization': `Bearer ${NOTION_TOKEN}`,
* 'Notion-Version': '2025-09-03',
* },
* }
* ).json();
* return response;
* };
*
* const childBlocks = createNotion().paragraph("Hello, World!").build();
*
* const { apiResponses, apiCallCount } = await appendBlocks({
* block_id: 'your-block-id',
* children: childBlocks.content,
* apiCall
* });
*/
export function appendBlocks(options: {
block_id: string;
children: Array<Object>;
client?: Object | undefined;
apiCall?: Function | undefined;
getResults?: Function | undefined;
}): Promise<Object>;
export namespace request {
namespace pages {
function create({ data, client, apiCall, getPage, getResults, templateWaitMs, onTemplatePageCreated, skipAutoAppendOnTemplate, debug, }: {
data: {
parent: Object;
properties?: Object | undefined;
icon?: Object | undefined;
cover?: Object | undefined;
children?: Object[] | undefined;
};
client?: Object | undefined;
apiCall?: Function | undefined;
getPage?: Function | undefined;
getResults?: Function | undefined;
templateWaitMs?: number | undefined;
onTemplatePageCreated?: Function | undefined;
skipAutoAppendOnTemplate?: boolean | undefined;
}): Promise<Object>;
}
namespace blocks {
namespace children {
function append(options: any): Promise<{
apiResponses: any;
apiCallCount: number;
error?: undefined;
} | {
apiResponses: null;
apiCallCount: number;
error: any;
}>;
namespace append {
function resetApiCallCount(): void;
}
}
}
}
//# sourceMappingURL=requests.d.mts.map