/**
 * Opt-in HTML helpers for the chrischall MCP fleet.
 *
 * Isolated behind the `@chrischall/mcp-utils/html` subpath because it pulls the
 * heavy `node-html-parser` dependency — lean API-only MCPs shouldn't pay for it.
 *
 * Consolidates the HTML-scraping primitives that were independently
 * re-implemented across the realty cohort (homes / redfin / compass /
 * zillow / onehome) and a couple of content MCPs (opentable, infinitecampus):
 *
 *   - `parsePropertyTable` / `findLinksUnderHeading` — heading-anchored DOM
 *     scraping for the SSR property-detail tables and link lists.
 *   - `extractJsonFromHtml` — the balanced-brace `__INITIAL_STATE__` walker
 *     (opentable / compass / realty); regex can't handle nested objects and
 *     escaped strings.
 *   - `extractPlainTextFromHtml` — dependency-free script/style strip + entity
 *     decode used to render Infinite Campus message bodies as plain text.
 *   - `urlToPath` / `locationToSlug` / `buildIdExtractor` — the small URL atoms
 *     that were byte-identical across the cohort.
 */
import { type HTMLElement } from 'node-html-parser';
export type { HTMLElement };
/** A scraped HTML table: column headers plus row-major cell text. */
export interface PropertyTable {
    /** Trimmed text of each header cell, in document order. */
    headers: string[];
    /** Each body row as an array of trimmed cell strings, in document order. */
    rows: string[][];
}
/**
 * Locate the `<table>` under the heading matching `heading` and return its
 * column headers and body rows.
 *
 * Header cells are scoped to `<thead>` when present (falling back to all `<th>`
 * in the table). Body rows collect **both** `<th>` and `<td>` because the realty
 * portals use `<th scope="row">` for the leading cell of every data row (the
 * year / date column) — dropping those would silently shift every column left
 * and corrupt the parsed record.
 *
 * Cell text has internal whitespace collapsed to single spaces and is trimmed.
 *
 * @param html    Raw page HTML (or an HTML fragment).
 * @param heading Case-insensitive substring of the heading above the table.
 * @returns The parsed table, or `null` when no matching heading+table is found.
 *
 * @example parsePropertyTable(detailHtml, 'Tax History')
 *   // { headers: ['Year', 'Property Tax'], rows: [['2023', '$1,200'], ...] }
 */
export declare function parsePropertyTable(html: string | HTMLElement, heading: string): PropertyTable | null;
/**
 * Find every `<a>` (or `selector`-matching element) that follows the first
 * heading matching `heading`, up to — but not including — the next sibling
 * heading. Useful for the "Homes for Sale Near" link lists at the bottom of a
 * detail page.
 *
 * Collects both direct-sibling anchors and anchors nested inside the
 * intervening sibling elements (lists, cards), in document order.
 *
 * @param root     Raw HTML string or an already-parsed root element.
 * @param heading  Case-insensitive substring of the heading to anchor on.
 * @param selector CSS selector for the elements to collect (default `'a'`).
 * @returns The matching elements, or an empty array when the heading is absent.
 */
export declare function findLinksUnderHeading(root: string | HTMLElement, heading: string, selector?: string): HTMLElement[];
/**
 * Extract an embedded JSON state object from a server-rendered HTML page by
 * walking the balanced brace/string structure after a marker.
 *
 * Handles both rendering forms seen across the fleet:
 *   1. `window.__INITIAL_STATE__ = {...};` — a JS assignment in a `<script>`.
 *   2. `"__INITIAL_STATE__":{...}` — a JSON key inside a larger embedded blob.
 *
 * A regex can't be used: the state contains nested objects and escaped strings.
 * This walks the structure tracking string/escape context so braces inside
 * string literals don't terminate the object early.
 *
 * Unlike the per-MCP `extractInitialState`, this returns `null` (rather than
 * throwing) on any failure — no marker, unbalanced braces, or invalid JSON —
 * so callers can branch on a missing blob without a try/catch.
 *
 * @param html   The page HTML.
 * @param marker The state key to search for (default `'__INITIAL_STATE__'`).
 *               Both the `window.<marker>` and `"<marker>"` forms are tried.
 * @returns The parsed object, or `null` if not found / not parseable.
 */
export declare function extractJsonFromHtml(html: string, marker?: string): Record<string, unknown> | null;
/**
 * Strip an HTML document down to its readable plain text: remove `<script>` and
 * `<style>` blocks (and their contents), drop all remaining tags, decode common
 * HTML entities, then collapse whitespace.
 *
 * Dependency-free (no DOM parser) — this mirrors the Infinite Campus message
 * extractor, which renders `messageView.xsl` bodies into a flat string. Removing
 * `<script>`/`<style>` *content* first is load-bearing for safety: it ensures
 * inline JS/CSS text never leaks into the surfaced message body.
 *
 * @param html The HTML (full document or fragment).
 * @returns The decoded, whitespace-collapsed plain text (`''` for empty input).
 */
export declare function extractPlainTextFromHtml(html: string): string;
/**
 * Reduce a portal URL (or path) to its `pathname + search` portion.
 *
 * Accepts an absolute URL (any host — only the path is kept), a path already
 * starting with `/` (returned unchanged), or a bare segment which is coerced to
 * a leading-slash path. Malformed input that `new URL()` can't parse falls
 * through to the same coercion branch, so the function never throws.
 *
 * @example urlToPath('https://www.zillow.com/homedetails/foo/7_zpid/')
 *   // '/homedetails/foo/7_zpid/'
 * @example urlToPath('homedetails/7_zpid/')  // '/homedetails/7_zpid/'
 * @example urlToPath('/already/a/path/')     // '/already/a/path/'
 */
export declare function urlToPath(input: string): string;
/**
 * Slugify a free-text location into a portal search-URL segment.
 *
 * NFKD-normalises, strips diacritics, lowercases, collapses runs of
 * non-alphanumerics to a single `-`, then trims leading/trailing `-`. A bare ZIP
 * passes through unchanged.
 *
 * @example locationToSlug('Brooklyn, NY')  // 'brooklyn-ny'
 * @example locationToSlug('Cañon City, CO') // 'canon-city-co'
 * @example locationToSlug('94110')         // '94110'
 */
export declare function locationToSlug(input: string): string;
/**
 * Build a stateless id-extractor from a regular expression.
 *
 * Returns a function that runs `regex` against a URL/path and yields the first
 * capture group (or the whole match when the pattern has no groups), or
 * `undefined` on no match / nullish input.
 *
 * The extractor is **stateless**: a fresh `RegExp` is constructed per call so a
 * `g`/`y`-flagged source can't carry `lastIndex` between invocations and
 * silently skip matches.
 *
 * @example buildIdExtractor(/\/home\/(\d+)(?:[/?#]|$)/)('/x/home/42/') // '42'
 * @example buildIdExtractor(/\/([A-Za-z0-9]+)_pid\/?$/)('/s/abc_pid/') // 'abc'
 */
export declare function buildIdExtractor(regex: RegExp): (input: string | undefined | null) => string | undefined;
//# sourceMappingURL=index.d.ts.map