notion-helper/dist/utils.d.mts

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

/**
 * Checks if a string contains only a single emoji.
 *
 * @param {string} string
 * @returns {boolean}
 */
export function isSingleEmoji(string: string): boolean;
/**
 * Checks if a string is a valid URL.
 *
 * @param {string} string
 * @returns {boolean}
 */
export function isValidURL(string: string): boolean;
/**
 * Checks if a string is a valid UUID.
 *
 * @param {string} string
 * @returns {boolean}
 */
export function isValidUUID(string: string): boolean;
/**
 * Checks if an image URL is both a valid URL and has a supported image file type.
 *
 * @param {url} url - the URL to be checked
 * @returns {boolean}
 */
export function validateImageURL(url: any): boolean;
/**
 * Checks if a video URL is both a valid URL and will be accepted by the API, based on a list of supported file extensions and embed websites.
 *
 * @param {url} url - the URL to be checked
 * @returns {boolean}
 */
export function validateVideoURL(url: any): boolean;
/**
 * Checks if a audio URL is both a valid URL and will be accepted by the API, based on a list of supported file extensions.
 *
 * @param {url} url - the URL to be checked
 * @returns {boolean}
 */
export function validateAudioURL(url: any): boolean;
/**
 * Checks if a PDF URL is both a valid URL and ends with the .pdf extension.
 *
 * @param {url} url - the URL to be checked
 * @returns {boolean}
 */
export function validatePDFURL(url: any): boolean;
/**
 * Checks string length against the max length and throws a warning if it is over the limit.
 * @param {Object} options - the options for the function
 * @param {string} options.string - the string to be checked
 * @param {string} options.type - the type of string to be checked (text, equation, url, email, phone_number)
 * @param {number} options.limit - the max length of the string
 * @returns {void}
 */
export function validateStringLength({ string, type, limit }: {
    string: string;
    type: string;
    limit: number;
}): void;
/**
 * Checks array length against the max length and throws a warning if it is over the limit.
 * @param {Object} options - the options for the function
 * @param {Array} options.array - the array to be checked
 * @param {string} options.type - the type of array to be checked (relation, multi_select, people)
 * @param {number} options.limit - the max length of the array
 * @returns {void}
 */
export function validateArrayLength({ array, type, limit }: {
    array: any[];
    type: string;
    limit: number;
}): void;
/**
 * Enforces a length limit on a string. Returns the original string in a single-element array if it is under the limit. If not, returns an array with string chunks under the limit.
 *
 * @param {string} string - the string to be tested
 * @param {number} limit - optional string-length limit
 * @returns {Array<string>} - array with the original string, or chunks of the string if it was over the limit.
 */
export function enforceStringLength(string: string, limit: number): Array<string>;
/**
 * Validates a Date object or string input that represents a date, and converts it to an ISO-8601 date string if possible.
 *
 * If the input is a string without time information, returns just the date (YYYY-MM-DD).
 * If the input is a Date object or a string with time info, returns full ISO string.
 * Returns null if the input is invalid.
 *
 * @param {(string|Date)} dateInput - A Date object or string representing a date
 * @returns {string|null} ISO-8601 date string, or null if input is invalid
 *
 * @example
 * // Returns "2023-12-01"
 * validateDate("2023-12-01")
 *
 * // Returns "2023-12-01T15:30:00.000Z"
 * validateDate("2023-12-01T15:30:00Z")
 *
 * // Returns "2023-12-01T00:00:00.000Z"
 * validateDate(new Date("2023-12-01"))
 *
 * // Handles non-ISO date strings, Returns "2023-09-10T00:00:00.000Z" (browser timezone may affect result)
 * validateDate("September 10, 2023")
 *
 * // Handles other common formats, Returns "2023-07-04T00:00:00.000Z"
 * validateDate("07/04/2023")
 *
 * // Returns null (invalid input)
 * validateDate("not a date")
 */
export function validateDate(dateInput: (string | Date)): string | null;
/**
 * 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.
 *
 * @param {Array<Object>} arr - The array of child blocks to be depth-checked.
 * @param {number} [level = 1] - The current level.
 *
 * @returns {number}
 */
export function getDepth(arr: Array<Object>, level?: number): 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.
 *
 * @param {Array<Object>} arr - The array of block objects to be counted.
 * @returns {number}
 */
export function getTotalCount(arr: Array<Object>): number;
/**
 * Gets the length of the longest array within a nested block array.
 *
 * @param {Array<Object>} arr - The array to check
 * @param {number} count - 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}
 */
export function getLongestArray(arr: Array<Object>, count?: number): 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.
 *
 * @param {Array<Object>} arr - The array of block objects to measure
 * @returns {number} Size in bytes
 */
export function getPayloadSize(arr: Array<Object>): number;
/**
 * Validates a well-formed Notion block and splits it into multiple blocks if needed.
 *
 * This function performs validation and splitting for different types of rich text content:
 * 1. Main rich_text arrays (paragraph, heading, etc.) - splits individual objects and handles MAX_BLOCKS limit
 * 2. Caption arrays (image, video, audio, file, pdf, code blocks) - splits individual objects but doesn't duplicate blocks
 *
 * For blocks with main rich_text arrays, if the resulting array exceeds MAX_BLOCKS (100),
 * the function splits into multiple blocks of the same type. Children are preserved only
 * for the first split block to avoid duplication. For blocks with captions, only the caption
 * rich text objects are processed without duplicating the block. If a caption array exceeds
 * MAX_BLOCKS after processing, it is truncated to the first 100 objects with a console warning.
 *
 * @param {Object} block - A well-formed Notion block object
 * @param {number} [limit] - Optional custom limit for text length. If not provided, uses CONSTANTS.MAX_TEXT_LENGTH
 * @returns {Array<Object>} - Array containing the original block if valid, or multiple blocks if split was necessary
 *
 * @example
 * // Block with short text - returns original block
 * const shortBlock = {
 *   type: "paragraph",
 *   paragraph: {
 *     rich_text: [{ type: "text", text: { content: "Short text" } }]
 *   }
 * };
 * const result1 = validateAndSplitBlock(shortBlock);
 * // Returns: [shortBlock]
 *
 * // Block with long text in single rich text object - splits the rich text object
 * const longBlock = {
 *   type: "paragraph",
 *   paragraph: {
 *     rich_text: [{ type: "text", text: { content: "Very long text that exceeds the limit..." } }],
 *     color: "blue"
 *   }
 * };
 * const result2 = validateAndSplitBlock(longBlock);
 * // Returns: [block] with multiple rich text objects in the rich_text array
 *
 * // Image block with long caption - processes caption without duplicating block
 * const imageBlock = {
 *   type: "image",
 *   image: {
 *     type: "external",
 *     external: { url: "https://example.com/image.jpg" },
 *     caption: [{ type: "text", text: { content: "Very long caption..." } }]
 *   }
 * };
 * const result3 = validateAndSplitBlock(imageBlock);
 * // Returns: [imageBlock] with processed caption rich text
 *
 * // Heading block with children - children preserved only in first split block
 * const headingWithChildren = {
 *   type: "heading_1",
 *   heading_1: {
 *     rich_text: Array(150).fill().map((_, i) => ({
 *       type: "text",
 *       text: { content: `Heading text ${i}` }
 *     })),
 *     children: [{ type: "paragraph", paragraph: { rich_text: [] } }] // 100 child blocks
 *   }
 * };
 * const result4 = validateAndSplitBlock(headingWithChildren);
 * // Returns: [heading1, heading2] where only heading1 has children
 *
 * // Image block with too many caption objects - truncates and warns
 * const imageWithManyCaptions = {
 *   type: "image",
 *   image: {
 *     type: "external",
 *     external: { url: "https://example.com/image.jpg" },
 *     caption: Array(150).fill().map((_, i) => ({
 *       type: "text",
 *       text: { content: `Caption ${i}` }
 *     }))
 *   }
 * };
 * const result4 = validateAndSplitBlock(imageWithManyCaptions);
 * // Returns: [imageBlock] with caption truncated to first 100 objects + console warning
 */
export function validateAndSplitBlock(block: Object, limit?: number): Array<Object>;
/**
 * Extracts the Notion page ID (UUID, with or without dashes) from a URL.
 * Handles both dashed and non-dashed formats found in URLs.
 *
 * @param {string} url - The URL to extract the page ID from.
 * @returns {string|null} The 32-character page ID without dashes, or null if not found.
 */
export function extractNotionPageId(url: string): string | null;
//# sourceMappingURL=utils.d.mts.map