### Create Notion Page Example (Notion SDK)

Source: https://tomfrankly.github.io/notion-helper/index

Example demonstrating how to create a Notion page using the Notion SDK client. It shows the setup of the client and the construction of page content with various block types.

```javascript
import { Client } from '@notionhq/client';

const NOTION_TOKEN = 'your-notion-token';
const notion = new Client({ auth: NOTION_TOKEN });

const page = createNotion()
     .parentDb("your-database-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 request.pages.create({
  data: page.content,
  client: notion
});
```

--------------------------------

### Create Notion Page Example (Custom API Call)

Source: https://tomfrankly.github.io/notion-helper/index

Example demonstrating how to create a Notion page using a custom API call function, specifically with the 'ky' library. It includes setting up the custom API call function with necessary headers and making the request.

```javascript
import ky from 'ky';

const NOTION_TOKEN = 'your-notion-token';
const NOTION_VERSION = '2022-06-28';

const customApiCall = async (data) => {
  return await ky.post('https://api.notion.com/v1/pages', {
    json: data,
    headers: {
      'Authorization': `Bearer ${NOTION_TOKEN}`,
      'Notion-Version': NOTION_VERSION,
    },
  }).json();
};

const page = createNotion()
     .parentDb("your-database-id")
     .title("Name", "Squirtle")
     .icon("https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/7.png")
     .richText("Category", "Tiny Turtle Pokémon")
     .quote("After birth, its back swells and hardens into a shell. Powerfully sprays foam from its mouth.")
     .build();

const result = await request.pages.create({
  data: page.content,
  apiCall: customApiCall,
  getPage: (response) => response,
  getResults: (response) => response.results
});
```

--------------------------------

### Create Rich Text Objects

Source: https://tomfrankly.github.io/notion-helper/examples/browser-example

Demonstrates creating rich text objects with formatting options like bold and color using the `buildRichTextObj` function.

```javascript
import { buildRichTextObj } from 'notion-helper';

// Create rich text with formatting
const richText = buildRichTextObj("Hello, World!", { bold: true, color: "blue" });

console.log(richText);
```

--------------------------------

### Example Usage of Notion Builder

Source: https://tomfrankly.github.io/notion-helper/index

Demonstrates how to use the Notion builder to create a page with a title and paragraph, then build and log the content. Also shows how to reset the builder for creating another page.

```javascript
const notion = createNotionBuilder();
const result = notion
  .dbId('your-database-id')
  .title('Page Title', 'My New Page')
  .paragraph('This is a paragraph.')
  .build();

console.log(result.content);  // The main page content
console.log(result.additionalBlocks);  // Any blocks that couldn't fit in the initial request

// Reset the builder for a new page
notion.reset()
  .dbId('another-database-id')
  .title('Page Title', 'Another New Page')
  .build();
```

--------------------------------

### Create an Entire Notion Page

Source: https://tomfrankly.github.io/notion-helper/examples/browser-example

Illustrates creating a complete Notion page object, including properties like title, description, status, and date, along with child blocks and images, using the `createNotionBuilder`.

```javascript
import { createNotionBuilder } from 'notion-helper';

// Create page object with properties and child blocks
const pageMeta = createNotionBuilder({
  limitNesting: false,
  limitChildren: true,
  allowBlankParagraphs: true,
})
  .title("Name", "Great American Novel Idea")
  .richText("Description", "A tale about a cowboy going to space to meet Jabba the Hutt")
  .status("Status", "To Do")
  .date("Due Date", "2025-06-01")
  .heading1("Novel Pitch")
  .paragraph("The novel starts in an unlikely place: Des Moines, Iowa...")
  .image(uploadId)
  .build();

console.log(pageMeta);
```

--------------------------------

### Create Block Objects

Source: https://tomfrankly.github.io/notion-helper/examples/browser-example

Shows how to create an array of different Notion block types, including headings, paragraphs, and list items, using functions like `paragraph`, `heading1`, and `bulletedListItem`.

```javascript
import { paragraph, heading1, bulletedListItem } from 'notion-helper';

// Create an array of different block types
const blocks = [
  heading1("My Heading"),
  paragraph("This is a paragraph with some text."),
  bulletedListItem("First bullet point"),
  bulletedListItem("Second bullet point")
];

console.log(blocks);
```

--------------------------------

### Notion Builder API

Source: https://tomfrankly.github.io/notion-helper/index

Defines the fluent interface methods for constructing Notion objects, including page setup, property management, and block creation. It also details the structure management and the final build process.

```APIDOC
createNotionBuilder(options: Object?): NotionBuilder

Parameters
options `(Object?)` Configuration options for the builder 
Name | Description  
---|---
options.strict `boolean` (default `false`)  | If true, throws errors for invalid data. Otherwise gracefully handles nulls.   
options.limitNesting `boolean` (default `true`)  | If true, limits nested children to 2 levels (Notion API limit).   
options.limitChildren `boolean` (default `true`)  | If true, limits children arrays to 100 blocks, putting excess in additionalBlocks.   
options.allowBlankParagraphs `boolean` (default `false`)  | If true, allows empty paragraph blocks.   
Returns
`NotionBuilder`: A builder object with fluent interface methods for constructing Notion content.

Fluent Interface Methods:
Page Setup Methods:
  * `parentDb(database_id)` - Sets parent database
  * `parentPage(page_id)` - Sets parent page
  * `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
```

--------------------------------

### Create Notion Column Block

Source: https://tomfrankly.github.io/notion-helper/index

Provides examples for creating Notion column blocks, including empty columns, columns with a single paragraph, columns with multiple blocks, and columns with custom block types.

```javascript
// Create an empty column
const emptyColumn = block.column.createBlock();
```

```javascript
// Create a column with a single paragraph
const singleParagraphColumn = block.column.createBlock("This is a paragraph in a column");
```

```javascript
// Create a column with multiple blocks
const multiBlockColumn = block.column.createBlock([
  "First paragraph",
  block.heading_2.createBlock("Heading in column"),
  "Another paragraph"
]);
```

```javascript
// Create a column with custom blocks
const customBlocksColumn = block.column.createBlock([
  block.paragraph.createBlock("Custom paragraph"),
  block.bulleted_list_item.createBlock("Bullet point in column"),
  block.image.createBlock({ url: "https://example.com/image.jpg" })
]);
```

--------------------------------

### Create Notion Table Block

Source: https://tomfrankly.github.io/notion-helper/index

Provides examples for creating Notion table blocks using `block.table.createBlock`. It shows how to create tables with string arrays for rows, use `table_row` objects for more control over cells, and configure column/row headers. An empty table can also be created.

```javascript
// Use with array of string arrays
const simpleTable = block.table.createBlock({
  rows: [
    ["Header 1", "Header 2"],
    ["Row 1, Cell 1", "Row 1, Cell 2"],
    ["Row 2, Cell 1", "Row 2, Cell 2"]
  ],
  has_column_header: true
});

// Use with array of table_row objects
const complexTable = block.table.createBlock({
  rows: [
    block.table_row.createBlock(["Header 1", "Header 2"]),
    block.table_row.createBlock(["Row 1, Cell 1", "Row 1, Cell 2"]),
    block.table_row.createBlock(["Row 2, Cell 1", "Row 2, Cell 2"])
  ],
  has_column_header: true,
  has_row_header: false
});

// Create an empty table
const emptyTable = block.table.createBlock();
```

--------------------------------

### Append Child Blocks with Notion SDK

Source: https://tomfrankly.github.io/notion-helper/index

Demonstrates how to append child blocks to a Notion page using the official Notion SDK client. It shows the setup of the client and the call to append blocks.

```javascript
import { Client } from '@notionhq/client';

// Using with Notion SDK client
const notion = new Client({ auth: NOTION_TOKEN });
const childBlocks = createNotion().paragraph("A paragraph").build()

const { apiResponses, apiCallCount } = await request.blocks.children.append({
  block_id: 'your-block-id',
  children: childBlocks.content,
  client: notion
});
```

--------------------------------

### Create Notion Table Row Block

Source: https://tomfrankly.github.io/notion-helper/index

Illustrates the usage of `block.table_row.createBlock` for creating individual rows within a Notion table. Examples cover creating rows with simple strings for cells and with rich text objects for more advanced formatting, including annotations like bold text.

```javascript
// Use with an array of strings
const simpleRow = block.table_row.createBlock(["Cell 1", "Cell 2", "Cell 3"]);

// Use with an array of rich text objects
const complexRow = block.table_row.createBlock([
  [{ type: "text", text: { rich_text: "Cell 1" } }],
  [{ type: "text", text: { rich_text: "Cell 2", annotations: { bold: true } } }],
  [{ type: "text", text: { rich_text: "Cell 3" } }]
]);
```

--------------------------------

### Get Payload Size (JavaScript)

Source: https://tomfrankly.github.io/notion-helper/index

Estimates the size in bytes of a block array when serialized as JSON. This is essential for complying with Notion API payload size restrictions.

```APIDOC
getPayloadSize(arr: Array<Object>): number
  Gets the size in bytes of a block array when converted to JSON. Used to ensure API requests don't exceed Notion's payload size limits.
  Parameters:
    arr (Array<Object>): The array of block objects to measure.
  Returns:
    number: Size in bytes.
```

--------------------------------

### Notion Page Property: Date

Source: https://tomfrankly.github.io/notion-helper/index

Methods for setting a Notion page's date property. The `setProp` method accepts a start date and an optional end date.

```APIDOC
date.setProp(start: string, end: string = `null`): Object
  Parameters:
    start `(string)`: The start date.
    end `(string             = `null`)`: The optional end date.
  Returns:
    `Object`: A date property object.
```

--------------------------------

### Get Longest Array Length (JavaScript)

Source: https://tomfrankly.github.io/notion-helper/index

Finds the length of the longest array within a potentially nested structure of block arrays. This helps in managing complex block data.

```APIDOC
getLongestArray(arr: Array<Object>, count: number = 0): number
  Gets the length of the longest array within a nested block array.
  Parameters:
    arr (Array<Object>): The array to check.
    count (number = 0): The length of the array one level up from the array being checked, or 0 if this is the initial call of the function.
  Returns:
    number: The length of the longest nested array.
```

--------------------------------

### Basic Page Creation with Notion Builder

Source: https://tomfrankly.github.io/notion-helper/index

Demonstrates how to use the createNotionBuilder to construct a basic Notion page with a parent database, title, select property, date property, and paragraph and to-do blocks.

```javascript
const page = createNotionBuilder()
  .parentDb('database-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();

const result = page.content;
const extraBlocks = page.additionalBlocks;
```

--------------------------------

### Notion Page Creation API Documentation

Source: https://tomfrankly.github.io/notion-helper/index

Details the `create` method for Notion pages, including parameters for page data, parent, properties, icons, covers, child blocks, and options for providing a Notion client or custom API call function.

```APIDOC
pages.create(options: Object): Promise<Object>
  Creates a new page in Notion and optionally appends child blocks to it. Includes as many child blocks as possible in the initial request. Uses request.blocks.children.append() for all remaining child blocks, so it can handle nested blocks to any level.

  Parameters:
    options `(Object)` The options for creating a page.
      options.data `Object` | The data for creating the page.
        options.data.parent `Object` | The parent of the page (must include either database_id or page_id).
        options.data.properties `Object?` | The properties of the page.
        options.data.icon `Object?` | The icon of the page.
        options.data.cover `Object?` | The cover of the page.
        options.data.children `Array<Object>?` | An array of child blocks to add to the page.
      options.client `Object?` | The Notion client object. Either this or apiCall must be provided.
      options.apiCall `Function?` | A custom function for making API calls. Either this or client must be provided.
      options.getPage `Function` (default `(response)=>response`)  | A function to extract the page data from the API response. If you're passing a custom apiCall function, you should pass a getPage function as well.
      options.getResults `Function` (default `(response)=>response.results`)  | A function to extract results from the API response when appending blocks. Enables the append() method to append all child blocks in the request. If you're passing a custom apiCall function, you should pass a getResults function as well.

  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.
```

--------------------------------

### Create Bookmark Block

Source: https://tomfrankly.github.io/notion-helper/index

Creates a bookmark block in Notion. Accepts a URL string or an options object. Returns the bookmark block object.

```javascript
bookmark(options: (string | Object)): Object
Parameters
options `((string | Object))` A string representing the URL, or an options object. 
Returns
`Object`: a bookmark block. 
Related
block.bookmark for full documentation
```

--------------------------------

### Create Notion Column List

Source: https://tomfrankly.github.io/notion-helper/index

Demonstrates how to create a Notion column list with mixed content types within columns, and how to create an empty column list.

```javascript
// Create a column list with mixed content
const mixedColumnList = block.column_list.createBlock([
  "Text in first column",
  ["Paragraph 1 in second column", "Paragraph 2 in second column"],
  {
    type: "column",
    column: {},
    children: [block.heading_2.createBlock("Custom heading in third column")]
  }
]);
```

```javascript
// Create an empty column list
const emptyColumnList = block.column_list.createBlock();
```

--------------------------------

### Get Block Depth (JavaScript)

Source: https://tomfrankly.github.io/notion-helper/index

Calculates the maximum nesting depth of child blocks within a given array. This is useful for determining if recursive calls are needed when processing nested block structures.

```APIDOC
getDepth(arr: Array<Object>, level: number = 1): number
  Checks a provided array of child blocks to see how many nested levels of child blocks are present. Used by requests.blocks.children.append to determine if recursive calls need to be used.
  Parameters:
    arr (Array<Object>): The array of child blocks to be depth-checked.
    level (number = 1): The current level.
  Returns:
    number: The maximum depth of nested child blocks.
```

--------------------------------

### Create To-Do List Block

Source: https://tomfrankly.github.io/notion-helper/index

Creates a to-do list block in Notion. Accepts a string, array of strings, or an options object for the content. Returns the to-do list block.

```javascript
toDo(options: (string | Array<string> | Object)): Object
Parameters
options `((string | Array<string> | Object))` A string, an array of strings, or an options object representing the to-do content. 
Returns
`Object`: A to-do list block. 
Related
block.to_do for full documentation
```

--------------------------------

### Create Notion Embed Block

Source: https://tomfrankly.github.io/notion-helper/index

Demonstrates creating Notion embed blocks using either a direct URL string or an options object containing the URL.

```javascript
// Use with a string
const simpleEmbed = block.embed.createBlock("https://www.youtube.com/watch?v=ec5m6t77eYM");
```

```javascript
// Use with options object
const complexEmbed = block.embed.createBlock({
  url: "https://www.youtube.com/watch?v=ec5m6t77eYM"
});
```

--------------------------------

### Get Total Block Count (JavaScript)

Source: https://tomfrankly.github.io/notion-helper/index

Calculates the total number of blocks in an array, including all nested child blocks. This function is crucial for adhering to the Notion API's limit of 1,000 blocks per request.

```APIDOC
getTotalCount(arr: Array<Object>): number
  Gets the total number of blocks within an array of child blocks, including child blocks of those blocks (and so on). Used to ensure that requests do not exceed the 1,000 total block limit of the Notion API.
  Parameters:
    arr (Array<Object>): The array of block objects to be counted.
  Returns:
    number: The total count of blocks.
```

--------------------------------

### Create Notion File Block

Source: https://tomfrankly.github.io/notion-helper/index

Illustrates creating Notion file blocks from external URLs, file upload IDs, or using an options object with additional properties like name and caption.

```javascript
// Use with a file URL
const externalFile = block.file.createBlock("https://collegeinfogeek.com/wp-content/uploads/2015/01/10steps-reddit.pdf");
```

```javascript
// Use with a file upload ID
const fileUploadFile = block.file.createBlock("123e4567-e89b-12d3-a456-426614174000");
```

```javascript
// Use with options object for external file
const externalFile = block.file.createBlock({
  url: "https://collegeinfogeek.com/wp-content/uploads/2015/01/10steps-reddit.pdf",
  name: "10 Steps to Earning Awesome Grades (preview)",
  caption: "The Reddit preview of the 10 Steps to Earning Awesome Grades book."
});
```

```javascript
// Use with options object for file upload
const fileUploadFile = block.file.createBlock({

```

--------------------------------

### Notion Block Hierarchy Management

Source: https://tomfrankly.github.io/notion-helper/index

Methods for managing the structure of blocks within a Notion page, including starting and ending parent blocks, adding new blocks, and adding existing blocks. These operations are crucial for creating nested content.

```APIDOC
startParent(blockType: string, options: Object): this
  Starts a new parent block that can contain child blocks.
  Parameters:
    blockType `(string)` The type of block to create as a parent.
    options `(Object             = `{}`)` Options for creating the block, specific to the block type.
  Returns:
    `this`: The builder instance for method chaining.
  Throws:
    * Error: If the nesting level exceeds 2 or if the block type doesn't support children.
  Example:
    ```
    notion.startParent('toggle', 'Click to expand')
          .paragraph('This is inside the toggle')
          .endParent();
    ```

endParent(): this
  Ends the current parent block and moves up one level in the block hierarchy.
  Returns:
    `this`: The builder instance for method chaining.
  Example:
    ```
    notion.startParent('toggle', 'Click to expand')
          .paragraph('This is inside the toggle')
          .endParent();
    ```

addBlock(blockType: string, options: Object): this
  Adds a new block to the current level in the block hierarchy.
  Parameters:
    blockType `(string)` The type of block to add.
    options `(Object             = `{}`)` Options for creating the block, specific to the block type.
  Returns:
    `this`: The builder instance for method chaining.
  Example:
    ```
    notion.addBlock('paragraph', 'This is a paragraph.');

    // Or using the shorthand method:
    notion.paragraph('This is a paragraph.');
    ```

addExistingBlock(existingBlock: Object): this
  Adds an existing Notion block to the current level in the block hierarchy. This method is useful when you have a pre-constructed Notion block that you want to add directly.
  Parameters:
    existingBlock `(Object)` A valid Notion block object to add.
  Returns:
    `this`: The builder instance for method chaining.
  Example:
    ```
    // Add a pre-constructed paragraph block
    const myBlock = {
      type: "paragraph",
      paragraph: {
        rich_text: [{ type: "text", text: { content: "Hello" } }]
      }
    };
    notion.addExistingBlock(myBlock);
    ```
```

--------------------------------

### Notion API Request Functions Overview

Source: https://tomfrankly.github.io/notion-helper/index

Provides an overview of the different request types supported by the Notion API, including authentication, block manipulation, page creation, database operations, user management, comments, and search functionality.

```APIDOC
Auth:
  * Create a token (post)

blocks X Append block children (patch)
  * Retrieve a block (get)
  * Retrieve block children (get)
  * Update a block (patch)
  * Delete a block (delete)

page X Create a page (post)
  * Retrieve a page (get)
  * Retrieve a page property (get)
  * Update page properties (patch)

database
  * Create a database (post)
  * Query a database (post) -- Build a filter -- Build a sort
  * Retrieve a database (get)
  * Update a database (patch) -- Update database properties

users
  * List all users (get)
  * Retrieve a user (get)
  * Retrieve your token's bot user (get)

comments
  * Create comment (post)
  * Retrieve comments (get)

search
  * Search by title (post)
```

--------------------------------

### Create Table Block

Source: https://tomfrankly.github.io/notion-helper/index

Creates a table block in Notion. Accepts an options object for table configuration. Returns the table block.

```javascript
table(options: Object): Object
Parameters
options `(Object)` Options for creating the table. 
Returns
`Object`: A table block. 
Related
block.table for full documentation
```

--------------------------------

### Create Notion Page and Append Blocks (JavaScript)

Source: https://tomfrankly.github.io/notion-helper/index

Demonstrates how to create a new page in Notion and then append additional blocks as children to the newly created page. It handles cases where there are multiple chunks of blocks to append.

```javascript
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
    });
  }
}
```

--------------------------------

### Create Notion Image Block

Source: https://tomfrankly.github.io/notion-helper/index

Provides a method to create Notion image blocks. This method accepts either a string URL or an options object for more detailed configuration.

```javascript
/**
 * Creates an image block.
 * @param {string | Object} options - Either a string URL for the image or an options object.
 * @returns {Object | null} An image block object compatible with Notion's API, or null if creation fails.
 */
block.image.createBlock(options);
```

--------------------------------

### Create Audio Block

Source: https://tomfrankly.github.io/notion-helper/index

Creates an audio block in Notion. Accepts a URL string or an options object. Returns the audio block object or null if the URL is invalid.

```javascript
audio(options: (string | Object)): (Object | null)
Parameters
options `((string | Object))` A string representing the audio URL, a file upload ID, or an options object. 
Returns
`(Object | null)`: An audio block or null if the URL is invalid. 
Related
block.audio for full documentation
```

--------------------------------

### Notion Builder API Documentation

Source: https://tomfrankly.github.io/notion-helper/index

This section details the methods available in the NotionBuilder class for constructing and configuring Notion pages. Each method allows for setting specific properties or relationships, returning the builder instance for chaining.

```APIDOC
NotionBuilder:
  parentDb(database_id: string): this
    Sets the parent database for the page.
    Parameters:
      database_id `(string)`: The ID of the parent database.
    Returns:
      `this`: The builder instance for method chaining.

  parentPage(page_id: string): this
    Sets the parent page for the page.
    Parameters:
      page_id `(string)`: The ID of the parent page.
    Returns:
      `this`: The builder instance for method chaining.

  pageId(page_id: string): this
    Adds a page_id property. Used for updating page properties or doing read operations.
    Parameters:
      page_id `(string)`: The ID of the page.
    Returns:
      `this`: The builder instance for method chaining.

  propertyId(property_id: string): this
    Adds a property_id property. Used for fetching a page property item.
    Parameters:
      property_id `(string)`: The ID of the property to be fetched.
    Returns:
      `this`: The builder instance for method chaining.

  blockId(block_id: string): this
    Adds a block_id property. Used for all Block endpoints.
    Parameters:
      block_id `(string)`: The ID of the block.
    Returns:
      `this`: The builder instance for method chaining.

  cover(url: string): this
    Sets the cover image for the page.
    Parameters:
      url `(string)`: The URL of the cover image.
    Returns:
      `this`: The builder instance for method chaining.

  icon(url: string): this
    Sets the icon for the page.
    Parameters:
      url `(string)`: The URL of the icon image or an emoji.
    Returns:
      `this`: The builder instance for method chaining.

  property(name: string, type: string, value: any): this
    Adds a custom property to the page.
    Parameters:
      name `(string)`: The name of the property.
      type `(string)`: The type of the property.
      value `(any)`: The value of the property.
    Returns:
      `this`: The builder instance for method chaining.
    Throws:
      Error: If the property type is invalid.

  title(name: string, value: (string | Array)): this
    Sets a title property value for the page.
    Parameters:
      name `(string)`: The name of the property.
      value `((string | Array))`: The title value.
    Returns:
      `this`: The builder instance for method chaining.

  richText(name: string, value: (string | Array)): this
    Sets a rich text property value for the page.
    Parameters:
      name `(string)`: The name of the property.
      value `((string | Array))`: The rich text value.
    Returns:
      `this`: The builder instance for method chaining.

  checkbox(name: string, value: boolean): this
    Sets a checkbox property value for the page.
    Parameters:
      name `(string)`: The name of the property.
      value `(boolean)`: The checkbox value.
    Returns:
      `this`: The builder instance for method chaining.

  date(name: string, start: string, end: string = null): this
    Sets a date property value for the page.
    Parameters:
      name `(string)`: The name of the property.
      start `(string)`: The start date.
      end `(string)`: The end date (optional).
    Returns:
      `this`: The builder instance for method chaining.

  email(name: string, value: string): this
    Sets a email property value for the page.
    Parameters:
      name `(string)`: The name of the property.
      value `(string)`: The email value.
    Returns:
      `this`: The builder instance for method chaining.

  files(name: string, files: (string | Array)): this
    Sets a files property value for the page.
    NOTE: The separate file() method creates a file block.
    Parameters:
      name `(string)`: The name of the property.
      files `((string | Array))`: An array of file objects, or a url string.
    Returns:
      `this`: The builder instance for method chaining.

  multiSelect(name: string, values: (string | Array)): this
    Sets a multi-select property value for the page.
    Parameters:
      name `(string)`: The name of the property.
      values `((string | Array))`: A string or array of values.
    Returns:
      `this`: The builder instance for method chaining.

  number(name: string, value: number): this
    Sets a number property value for the page.
    Parameters:
      name `(string)`: The name of the property.
      value `(number)`: The number value.
    Returns:
      `this`: The builder instance for method chaining.

  people(name: string, people: (string | Array)): this
    Sets a people property value for the page.
    Parameters:
      name `(string)`: The name of the property.
      people `((string | Array))`: A person ID string or array of person IDs.
    Returns:
      `this`: The builder instance for method chaining.

  phoneNumber(name: string, value: string): this
    Sets a phone number property value for the page.
    Parameters:
      name `(string)`: The name of the property.
      value `(string)`: The phone number value.
    Returns:
      `this`: The builder instance for method chaining.
```

--------------------------------

### Add Media and Structural Blocks

Source: https://tomfrankly.github.io/notion-helper/index

Methods for adding various media (image, video, audio, file, pdf) and structural blocks (code, divider, table of contents, table, bookmark, embed) to a Notion page. All methods return the builder instance for chaining.

```APIDOC
code(options: any): this
  Adds a code block to the current stack.
  Parameters:
    options `(any)`
  Returns:
    `this`: The builder instance for method chaining.
  Related:
    block.code.createBlock for full documentation

divider(): this
  Adds a divider block to the current stack.
  Returns:
    `this`: The builder instance for method chaining.
  Related:
    block.divider.createBlock for full documentation

image(options: any): this
  Adds an image block to the current stack.
  Parameters:
    options `(any)`
  Returns:
    `this`: The builder instance for method chaining.
  Related:
    block.image.createBlock for full documentation

video(options: any): this
  Adds a video block to the current stack.
  Parameters:
    options `(any)`
  Returns:
    `this`: The builder instance for method chaining.
  Related:
    block.video.createBlock for full documentation

audio(options: any): this
  Adds an audio block to the current stack.
  Parameters:
    options `(any)`
  Returns:
    `this`: The builder instance for method chaining.
  Related:
    block.audio.createBlock for full documentation

file(options: any): this
  Adds a file block to the current stack.
  Parameters:
    options `(any)`
  Returns:
    `this`: The builder instance for method chaining.
  Related:
    block.file.createBlock for full documentation

pdf(options: any): this
  Adds a pdf block to the current stack.
  Parameters:
    options `(any)`
  Returns:
    `this`: The builder instance for method chaining.
  Related:
    block.pdf.createBlock for full documentation

bookmark(options: any): this
  Adds a bookmark block to the current stack.
  Parameters:
    options `(any)`
  Returns:
    `this`: The builder instance for method chaining.
  Related:
    block.bookmark.createBlock for full documentation

embed(options: any): this
  Adds an embed block to the current stack.
  Parameters:
    options `(any)`
  Returns:
    `this`: The builder instance for method chaining.
  Related:
    block.embed.createBlock for full documentation

tableOfContents(options: any): this
  Adds a table_of_contents block to the current stack.
  Parameters:
    options `(any)`
  Returns:
    `this`: The builder instance for method chaining.
  Related:
    block.table_of_contents.createBlock for full documentation

table(options: any): this
  Adds a table block to the current stack.
  Parameters:
    options `(any)`
  Returns:
    `this`: The builder instance for method chaining.
  Related:
    block.table.createBlock for full documentation
```

--------------------------------

### Create Code Block

Source: https://tomfrankly.github.io/notion-helper/index

Creates a code block in Notion. Accepts a string representing the code content or an options object. Returns the code block object.

```javascript
code(options: (string | Object)): Object
Parameters
options `((string | Object))` A string representing the code content, or an options object. 
Returns
`Object`: A code block. 
Related
block.code for full documentation
```

--------------------------------

### quickPages Function for Notion Page Creation

Source: https://tomfrankly.github.io/notion-helper/index

The quickPages function simplifies the creation of Notion page objects from an array of simple objects. It handles mapping data to Notion properties using a provided schema and can process nested children using a custom function. The output is an array of page objects suitable for Notion API requests.

```javascript
quickPages($0: Object, options: Object, parent: string, parent_type: string, pages: (Array<Object> | Object), schema: Object, childrenFn: function): Array<Object>
Parameters
$0 `(Object)`
Name | Description  
---|---
$0.parent `any` |   
$0.parent_type `any` |   
$0.pages `any` |   
$0.schema `any` |   
$0.childrenFn `any` |   
options `(Object)`
parent `(string)` The ID of the parent page or database. 
parent_type `(string)` "page_id" or "database_id". 
pages `((Array<Object> | Object))` 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. 
schema `(Object)` 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"]). 
childrenFn `(function)` 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. 
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). 
Example
```
const database = "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: database,
     parent_type: "database_id",
     pages: tasks,
     schema: schema,
     childrenFn: (value) => NotionHelper.makeParagraphs(value)
})
```
```

--------------------------------

### Create Notion Bookmark Block

Source: https://tomfrankly.github.io/notion-helper/index

Creates a bookmark block for the Notion API using a URL or an options object. The options can include a URL and an optional caption, which can be a string or an array of strings/rich text objects.

```javascript
block.bookmark.createBlock(options: (string | Object)): Object
```

--------------------------------

### Create Notion Quote Block

Source: https://tomfrankly.github.io/notion-helper/index

Demonstrates how to create a Notion quote block using the `block.quote.createBlock` method. Supports simple string input, an array of strings for multi-line quotes, and an options object for more complex configurations including rich text, colors, and child blocks.

```javascript
const simpleQuote = block.quote.createBlock("Simple quote");

const multiLineQuote = block.quote.createBlock(["Line 1 of quote", "Line 2 of quote"]);

const complexQuote = block.quote.createBlock({
  rich_text: "Complex quote",
  color: "gray",
  children: [
    // Child blocks would go here
  ]
});
```

--------------------------------

### Create Notion Divider Block

Source: https://tomfrankly.github.io/notion-helper/index

Shows how to create a simple divider block in Notion.

```javascript
const divider = block.divider.createBlock();
```

--------------------------------

### Create Notion Page

Source: https://tomfrankly.github.io/notion-helper/index

Creates a new page in Notion and optionally appends child blocks. Handles nested blocks efficiently by appending as many as possible in the initial request and using recursion for the rest. Requires either a Notion client or a custom API call function.

```APIDOC
request.pages.create(options: Object): Promise<Object>

Parameters:
  options `(Object)`: The options for creating a page.
    options.data `Object`: The data for creating the page.
      options.data.parent `Object`: The parent of the page (must include either database_id or page_id).
      options.data.properties `Object?`: The properties of the page.
      options.data.icon `Object?`: The icon of the page.
      options.data.cover `Object?`: The cover of the page.
      options.data.children `Array<Object>?`: An array of child blocks to add to the page.
    options.client `Object?`: The Notion client object. Either this or apiCall must be provided.
    options.apiCall `Function?`: A custom function for making API calls. Either this or client must be provided.
    options.getPage `Function` (default `(response)=>response`): A function to extract the page data from the API response.
    options.getResults `Function` (default `(response)=>response.results`): A function to extract results from the API response when appending blocks.

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.
```