notion-helper/dist/requests.d.mts

A library of functions for working more easily with the Notion API

/**
 * 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. 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.
 * @returns {Promise<Object>} An object containing the API response for page creation and, if applicable, the result of appending children.
 * @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 customApiCall = async (data) => {
 *   // Your custom API call implementation
 * };
 *
 * const result = await createPage({
 *   data: page.content,
 *   apiCall: customApiCall,
 *   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;
}): 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. 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 customApiCall = async (block_id, children) => {
 *   const response = await ky.patch(
 *     `https://api.notion.com/v1/blocks/${block_id}/children`,
 *     {
 *       json: { children },
 *       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: customApiCall
 * });
 */
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, }: {
            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;
        }): 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