ID & URL Management

/**
 * Robustly extracts the notion page ID from a notion URL or pathname suffix
 * @param id - URL, pathname, or raw ID to parse
 * @param options - Parsing options
 * @returns Parsed page ID or undefined if invalid
 */
function parsePageId(id?: string | null, options?: { uuid?: boolean }): string | undefined;

import { parsePageId } from "notion-utils";

// Parse from full URLs
const id1 = parsePageId("https://notion.so/My-Page-abc123def456");
// Returns: "abc123def456" (32-char format)

const id2 = parsePageId("https://notion.so/My-Page-abc123def456", { uuid: true });
// Returns: "abc123de-f456-..." (UUID format)

// Parse from pathnames
const id3 = parsePageId("/My-Page-abc123def456");
// Returns: "abc123def456"

// Parse raw IDs
const id4 = parsePageId("abc123def456");
// Returns: "abc123def456"

/**
 * Converts a 32-character Notion ID to UUID format with dashes
 * @param id - 32-character Notion ID
 * @returns UUID format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
 */
function idToUuid(id?: string): string;

/**
 * Converts a UUID with dashes to a 32-character Notion ID
 * @param uuid - UUID format with dashes
 * @returns 32-character Notion ID
 */
function uuidToId(uuid: string): string;

import { idToUuid, uuidToId } from "notion-utils";

// Convert ID to UUID
const uuid = idToUuid("abc123def456789012345678901234");
// Returns: "abc123de-f456-7890-1234-567890123456"

// Convert UUID back to ID
const id = uuidToId("abc123de-f456-7890-1234-567890123456");
// Returns: "abc123def456789012345678901234"

/**
 * Gets the canonical, display-friendly version of a page's ID for use in URLs
 * @param pageId - The page ID to get canonical version for
 * @param recordMap - Extended record map containing page data
 * @param options - Options for canonical ID generation
 * @returns Canonical page ID for URLs or null if not found
 */
function getCanonicalPageId(
  pageId: string,
  recordMap: ExtendedRecordMap,
  options?: { uuid?: boolean }
): string | null;

import { getCanonicalPageId } from "notion-utils";

// Get canonical ID (tries slug first, falls back to title, then UUID)
const canonicalId = getCanonicalPageId(pageId, recordMap);
// Returns: "my-page-title-abc123def456" or "my-page-title" or "abc123def456"

const canonicalIdNoUuid = getCanonicalPageId(pageId, recordMap, { uuid: false });
// Returns: "my-page-title" (no UUID suffix)

/**
 * Returns a function that maps page IDs to URL paths
 * @param rootPageId - Optional root page ID that maps to '/'
 * @returns Function that converts page IDs to URL paths
 */
function defaultMapPageUrl(rootPageId?: string): (pageId: string) => string;

/**
 * Default function for mapping/transforming image URLs for Notion
 * @param url - Image URL to transform
 * @param block - Block containing the image
 * @returns Transformed image URL or undefined
 */
function defaultMapImageUrl(url: string | undefined, block: Block): string | undefined;

import { defaultMapPageUrl, defaultMapImageUrl } from "notion-utils";

// Create URL mapper function
const mapPageUrl = defaultMapPageUrl("root-page-id");

// Map pages to URLs
const rootUrl = mapPageUrl("root-page-id"); // Returns: "/"
const pageUrl = mapPageUrl("other-page-id"); // Returns: "/otherpageid"

// Transform image URLs
const imageUrl = defaultMapImageUrl("https://example.com/image.jpg", imageBlock);
// Returns: Notion-proxied image URL or original if already optimized

/**
 * Validates if a string is a valid URL
 * @param input - String to validate
 * @returns True if valid URL, false otherwise
 */
function isUrl(input: string): boolean;

/**
 * Normalizes URLs for consistency (memoized)
 * @param url - URL to normalize
 * @returns Normalized URL string
 */
function normalizeUrl(url?: string): string;

import { isUrl, normalizeUrl } from "notion-utils";

// Validate URLs
const valid = isUrl("https://example.com"); // Returns: true
const invalid = isUrl("not-a-url"); // Returns: false

// Normalize URLs
const normalized = normalizeUrl("https://www.example.com/path?param=value#hash");
// Returns: "example.com/path" (strips protocol, www, query, hash)

// 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;
}