Block & Property Utilities

/**
 * Gets the title of a block (works for pages, collection views, and regular blocks)
 * @param block - The block to get title from
 * @param recordMap - Extended record map containing related data
 * @returns Block title or empty string if no title found
 */
function getBlockTitle(block: Block, recordMap: ExtendedRecordMap): string;

import { getBlockTitle } from "notion-utils";

// Get title for any block type
const pageTitle = getBlockTitle(pageBlock, recordMap);
const collectionTitle = getBlockTitle(collectionViewBlock, recordMap);
const headerTitle = getBlockTitle(headerBlock, recordMap);

console.log(`Page: ${pageTitle}`);
console.log(`Collection: ${collectionTitle}`);
console.log(`Header: ${headerTitle}`);

/**
 * Gets the icon for a block (page icon or collection icon)
 * @param block - The block to get icon from
 * @param recordMap - Extended record map containing related data
 * @returns Icon string (emoji or URL) or null if no icon
 */
function getBlockIcon(block: Block, recordMap: ExtendedRecordMap): string | null;

import { getBlockIcon } from "notion-utils";

const icon = getBlockIcon(pageBlock, recordMap);
if (icon) {
  // Could be emoji like "📝" or URL like "https://..."
  console.log(`Page icon: ${icon}`);
} else {
  console.log("No icon found");
}

/**
 * Returns the parent page block containing a given block
 * @param block - Starting block to find parent for
 * @param recordMap - Extended record map containing all blocks
 * @param options - Navigation options
 * @returns Parent page block or null if none found
 */
function getBlockParentPage(
  block: Block,
  recordMap: ExtendedRecordMap,
  options?: { inclusive?: boolean }
): PageBlock | null;

import { getBlockParentPage } from "notion-utils";

// Find parent page of a block
const parentPage = getBlockParentPage(childBlock, recordMap);
if (parentPage) {
  const parentTitle = getBlockTitle(parentPage, recordMap);
  console.log(`Parent page: ${parentTitle}`);
}

// Include the block itself if it's a page
const parentOrSelf = getBlockParentPage(maybePageBlock, recordMap, { inclusive: true });

/**
 * Extracts the collection ID from a block
 * @param block - Block that may be associated with a collection
 * @param recordMap - Extended record map containing collection data
 * @returns Collection ID or null if not found
 */
function getBlockCollectionId(block: Block, recordMap: ExtendedRecordMap): string | null;

import { getBlockCollectionId } from "notion-utils";

const collectionId = getBlockCollectionId(collectionViewBlock, recordMap);
if (collectionId) {
  const collection = recordMap.collection?.[collectionId]?.value;
  console.log(`Collection: ${collection?.name}`);
}

/**
 * Gets the value of a collection property for a given page (collection item)
 * @param propertyName - Name of the property to retrieve (case-insensitive)
 * @param block - The page/item block containing the property
 * @param recordMap - Extended record map containing collection schema
 * @returns Property value in appropriate JavaScript type
 */
function getPageProperty<T>(
  propertyName: string,
  block: Block,
  recordMap: ExtendedRecordMap
): T;

function getPageProperty(
  propertyName: string,
  block: Block,
  recordMap: ExtendedRecordMap
): string | number | boolean | string[] | number[] | null;

import { getPageProperty } from "notion-utils";

// Get different types of properties
const title = getPageProperty("Title", itemBlock, recordMap);
// Returns: string

const status = getPageProperty("Status", itemBlock, recordMap);
// Returns: string (select value)

const tags = getPageProperty("Tags", itemBlock, recordMap);
// Returns: string[] (multi-select values)

const completed = getPageProperty("Completed", itemBlock, recordMap);
// Returns: boolean (checkbox value)

const dueDate = getPageProperty("Due Date", itemBlock, recordMap);
// Returns: number (timestamp) or number[] (date range)

const priority = getPageProperty("Priority", itemBlock, recordMap);
// Returns: number (if property is numeric)

// Generic typed version
const typedStatus = getPageProperty<string>("Status", itemBlock, recordMap);

// Re-exported from notion-types
interface ExtendedRecordMap {
  block: Record<string, Block>;
  collection?: Record<string, Collection>;
  collection_view?: Record<string, CollectionView>;
  notion_user?: Record<string, NotionUser>;
  collection_query?: Record<string, any>;
  signed_urls?: Record<string, string>;
  preview_images?: Record<string, string>;
}

interface Block {
  id: string;
  type: BlockType;
  properties?: Record<string, any>;
  format?: Record<string, any>;
  content?: string[];
  parent_id: string;
  parent_table: string;
  alive: boolean;
  created_time: number;
  last_edited_time: number;
}

interface PageBlock extends Block {
  type: "page";
  properties?: {
    title?: Decoration[];
  };
  format?: {
    page_icon?: string;
    page_cover?: string;
    page_cover_position?: number;
    page_full_width?: boolean;
    page_small_text?: boolean;
  };
}

interface Collection {
  id: string;
  name: string[][];
  description?: string[][];
  icon?: string;
  cover?: string;
  schema: Record<string, CollectionPropertySchema>;
  format?: Record<string, any>;
}

interface CollectionPropertySchema {
  name: string;
  type: CollectionPropertyType;
  options?: any[];
}

type CollectionPropertyType = 
  | 'title' | 'text' | 'number' | 'select' | 'multi_select'
  | 'date' | 'person' | 'file' | 'checkbox' | 'url' | 'email'
  | 'phone_number' | 'formula' | 'relation' | 'rollup'
  | 'created_time' | 'created_by' | 'last_edited_time' | 'last_edited_by';