notion-helper/dist/pages.d.mts

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

/**
 *
 * @param {Object} options
 * @param {string} parent - The ID of the parent page or database.
 * @param {string} parent_type - "page_id", "data_source_id", or "database_id". (database_id is deprecated and will not work in databases with more than one data source.)
 * @param {(Array<Object>|Object)} pages - an array of simple objects, each of which will be turned into a valid page object. Each can have property types that match to valid Notion page properties, as well as a "cover", "icon", and "children" property. The "children" prop's value should be either a string or an array. You can also pass a single object, but the function will still return an array.
 * @param {Object} schema - an object that maps the schema of the pages objects to property names and types in the parent. Saves you from needing to specify the property name and type from the target Notion database for every entry in your pages object. For each property in your pages object that should map to a Notion database property, specify the key as the property name in the pages object and set the value as an array with the Notion property name as the first element and the property type as the second. Non-valid property types will be filtered out. Optionall, you can specify custom keys for the icon (["Icon", "icon"]), cover (["Cover", "cover"]), and children array (["Children", "children"]).
 * @param {function} childrenFn - a callback you can specify that will run on any array elements present in a "children" property of any object in the pages array. If that "children" property contains a single string, it'll run on that as well. If omitted, any "children" values will be converted to Paragraph blocks by default.
 *
 * @example
 * const dataSource = "abcdefghijklmnopqrstuvwxyz"
 *
 * const tasks = [ {
 *   icon: "😛",
 *   task: "Build Standing Desk",
 *   due: "2024-09-10",
 *   status: "Not started"
 * } ]
 *
 * const schema = {
 *   task: [ "Name", "title" ],
 *   due: [ "Due Date", "date"],
 *   status: [ "Status", "status" ]
 * }
 *
 * const pageObjects = quickPages({
 *      parent: dataSource,
 *      parent_type: "data_source_id",
 *      pages: tasks,
 *      schema: schema,
 *      childrenFn: (value) => NotionHelper.makeParagraphs(value)
 * })
 * @returns {Array<Object>} - An array of page objects, each of which can be directly passed as the children for a POST request to https://api.notion.com/v1/pages (or as the single argument to notion.pages.create() when using the SDK).
 */
export function quickPages({ parent, parent_type, pages, schema, childrenFn }: Object): Array<Object>;
/**
 * A builder object for Notion content with fluent interface methods.
 * @typedef {Object} NotionBuilder
 * @example
 * const notionBuilder = createNotionBuilder();
 *
 * // Build a new Notion page with various blocks
 * const result = notionBuilder
 *   .parentDataSource('data-source-id')
 *   .title('Page Title', 'Hello World')
 *   .paragraph('This is the first paragraph.')
 *   .heading1('Main Heading')
 *   .build();
 */
/**
 * Creates a fluent interface builder for constructing Notion objects, including pages, properties, and blocks.
 *
 * **Fluent Interface Methods:**
 *
 * The returned builder provides chainable methods organized into categories:
 *
 * **Page Setup Methods:**
 * - `parentDataSource(data_source_id)` - Sets parent data source
 * - `parentDs(data_source_id)` - Alias for parentDataSource()
 * - `parentPage(page_id)` - Sets parent page
 * - `parentDatabase(database_id)` - Sets parent database (deprecated, will not work in databases with more than one data source)
 * - `parentDb(database_id)` - Alias for parentDatabase() (deprecated, will not work in databases with more than one data source)
 * - `pageId(page_id)` - Adds page ID for updates
 * - `blockId(block_id)` - Adds block ID for block operations
 * - `propertyId(property_id)` - Adds property ID for property operations
 * - `cover(url)` - Sets page cover image
 * - `icon(url)` - Sets page icon
 *
 * **Property Methods:**
 * - `property(name, type, value)` - Adds custom property
 * - `title(name, value)` - Adds title property
 * - `richText(name, value)` - Adds rich text property
 * - `checkbox(name, value)` - Adds checkbox property
 * - `date(name, value)` - Adds date property
 * - `email(name, value)` - Adds email property
 * - `files(name, value)` - Adds files property
 * - `multiSelect(name, value)` - Adds multi-select property
 * - `number(name, value)` - Adds number property
 * - `people(name, value)` - Adds people property
 * - `phoneNumber(name, value)` - Adds phone number property
 * - `relation(name, value)` - Adds relation property
 * - `select(name, value)` - Adds select property
 * - `status(name, value)` - Adds status property
 * - `url(name, value)` - Adds URL property
 *
 * **Block Methods:**
 * - `paragraph(content, options, url)` - Adds paragraph block
 * - `heading1(content, options, url)` - Adds H1 block
 * - `heading2(content, options, url)` - Adds H2 block
 * - `heading3(content, options, url)` - Adds H3 block
 * - `bulletedListItem(content, options, url)` - Adds bulleted list item
 * - `numberedListItem(content, options, url)` - Adds numbered list item
 * - `toDo(content, checked, options, url)` - Adds to-do block
 * - `callout(content, emoji, options, url)` - Adds callout block
 * - `quote(content, options, url)` - Adds quote block
 * - `code(content, language)` - Adds code block
 * - `divider()` - Adds divider block
 * - `image(url, caption)` - Adds image block
 * - `video(url, caption)` - Adds video block
 * - `audio(url, caption)` - Adds audio block
 * - `file(url, caption)` - Adds file block
 * - `pdf(url, caption)` - Adds PDF block
 * - `bookmark(url, caption)` - Adds bookmark block
 * - `embed(url, caption)` - Adds embed block
 * - `table(tableArray)` - Adds table block
 * - `tableRow(cellContents)` - Adds table row
 * - `columnList(columnArray)` - Adds column list
 * - `column(columnContent)` - Adds column
 * - `toggle(content, children, options, url)` - Adds toggle block
 *
 * **Structure Management:**
 * - `startParent(parentBlock)` - Begins nested block structure
 * - `endParent()` - Ends current nesting level
 * - `build()` - Finalizes and returns the built object
 *
 * **Return Object:**
 *
 * Returns an object with two possible properties:
 * - `content` (always returned) - can be a full page object, an array of blocks, or a properties object
 * - `additionalBlocks` - array containing block chunks that exceed Notion's limits for subsequent requests
 *
 * @function createNotionBuilder
 * @param {Object} [options] - Configuration options for the builder
 * @param {boolean} [options.strict=false] If true, throws errors for invalid data. Otherwise gracefully handles nulls.
 * @param {boolean} [options.limitNesting=true] If true, limits nested children to 2 levels (Notion API limit).
 * @param {boolean} [options.limitChildren=true] If true, limits children arrays to 100 blocks, putting excess in additionalBlocks.
 * @param {boolean} [options.allowBlankParagraphs=false] If true, allows empty paragraph blocks.
 * @param {boolean} [options.handleTemplatePageChildren=false] If true, automatically moves all children blocks to additionalBlocks when a template is applied (type is not "none"). This is required because the Notion API doesn't allow children blocks in page creation requests that apply templates.
 * @returns {NotionBuilder} A builder object with fluent interface methods for constructing Notion content.
 *
 * @example
 * // Basic page creation
 * const page = createNotionBuilder()
 *   .parentDataSource('data-source-id')
 *   .title('Name', 'My Task')
 *   .select('Status', 'In Progress')
 *   .date('Due Date', '2024-12-01')
 *   .paragraph('This is a task description.')
 *   .toDo('Complete the first step', false)
 *   .toDo('Review with team', false)
 *   .build();
 *
 * // Complex nested structure
 * const complexPage = createNotionBuilder()
 *   .parentDataSource('data-source-id')
 *   .title('Project Name', 'Website Redesign')
 *   .heading1('Project Overview')
 *   .paragraph('This project involves redesigning our main website.')
 *   .heading2('Phase 1: Research')
 *   .startParent(toggle('Research Tasks', []))
 *     .toDo('Conduct user interviews', false)
 *     .toDo('Analyze competitor websites', false)
 *   .endParent()
 *   .heading2('Phase 2: Design')
 *   .callout('Important: Get stakeholder approval before development', '⚠️')
 *   .build();
 *
 * // Handle large content with additionalBlocks
 * const result = page.content;
 * const extraBlocks = page.additionalBlocks;
 *
 * // Create page first, then append additional blocks if needed
 * const notion = new Client({ auth: process.env.NOTION_TOKEN });
 * const newPage = await notion.pages.create(result);
 *
 * if (extraBlocks && extraBlocks.length > 0) {
 *   for (const blockChunk of extraBlocks) {
 *     await notion.blocks.children.append({
 *       block_id: newPage.id,
 *       children: blockChunk
 *     });
 *   }
 * }
 *
 * // Using template with automatic children handling
 * const templatePage = createNotionBuilder({ handleTemplatePageChildren: true })
 *   .parentDataSource('data-source-id')
 *   .template('default') // or template_id
 *   .title('Name', 'Task from Template')
 *   .paragraph('This content will be moved to additionalBlocks')
 *   .toDo('Complete task', false)
 *   .build();
 *
 * // Create page with template, then append children
 * const notion = new Client({ auth: process.env.NOTION_TOKEN });
 * const newPage = await notion.pages.create(templatePage.content);
 *
 * // Append the children that were moved to additionalBlocks
 * if (templatePage.additionalBlocks && templatePage.additionalBlocks.length > 0) {
 *   for (const blockChunk of templatePage.additionalBlocks) {
 *     await notion.blocks.children.append({
 *       block_id: newPage.id,
 *       children: blockChunk
 *     });
 *   }
 * }
 */
export function createNotionBuilder({ strict, limitNesting, limitChildren, allowBlankParagraphs, handleTemplatePageChildren, }?: {
    strict?: boolean | undefined;
    limitNesting?: boolean | undefined;
    limitChildren?: boolean | undefined;
    allowBlankParagraphs?: boolean | undefined;
    handleTemplatePageChildren?: boolean | undefined;
}): NotionBuilder;
/**
 * @deprecated Use createNotionBuilder() instead. This function is maintained for backwards compatibility.
 * @function createNotion
 * @param {Object} options - The options for creating a Notion builder.
 * @param {boolean} [options.strict=false] If true, the builder will throw errors when passed invalid or null data.
 * @param {number} [options.limitNesting=true] If true, limits the number of nested children block arrays to 2.
 * @param {boolean} [options.limitChildren=true] If true, the final content object's children array will have a maximum of 100 blocks.
 * @param {boolean} [options.allowBlankParagraphs=false] If true, calling .paragraph("") will result in an empty paragraph block.
 * @returns {NotionBuilder} A builder object with methods for constructing and managing Notion content.
 */
export function createNotion(options: {
    strict?: boolean | undefined;
    limitNesting?: number | undefined;
    limitChildren?: boolean | undefined;
    allowBlankParagraphs?: boolean | undefined;
}): NotionBuilder;
/**
 * A builder object for Notion content with fluent interface methods.
 */
export type NotionBuilder = Object;
//# sourceMappingURL=pages.d.mts.map