import { type RequestContext } from '../../utils/internal/requestContext.js';
/**
 * Options for HTML article extraction.
 */
export interface ExtractArticleOptions {
    /**
     * CSS selector to use as the main content element, bypassing auto-detection.
     * If the selector does not match any element, Defuddle falls back to
     * auto-detection.
     */
    contentSelector?: string;
    /**
     * Enable Defuddle's debug logging and bypass div flattening. Useful when
     * diagnosing why a specific page extracts poorly. Defaults to `false`.
     */
    debug?: boolean;
    /**
     * Output format for `content`. `'markdown'` converts to Markdown (the common
     * case for LLM-bound text), `'html'` returns cleaned HTML. Defaults to
     * `'markdown'`.
     */
    format?: 'html' | 'markdown';
    /**
     * Preferred language for extraction and transcript selection (BCP 47, e.g.
     * `'en'`, `'fr'`, `'ja'`).
     */
    language?: string;
    /**
     * Strip all images from the extracted content. Defaults to `false`.
     */
    removeImages?: boolean;
    /**
     * URL of the page being parsed. Passed to Defuddle for site-specific
     * extractors and resolved link rewriting.
     */
    url?: string;
    /**
     * Allow Defuddle's async extractors to fetch from third-party APIs
     * (e.g. FxTwitter) when no local content is available in the HTML.
     * Defaults to `false` to keep extraction fully local and deterministic.
     */
    useAsync?: boolean;
}
/**
 * Result of HTML article extraction.
 *
 * All fields except `content` are best-effort — they may be undefined if the
 * source page does not provide the corresponding metadata.
 */
export interface ExtractArticleResult {
    /** Article author, if detected. */
    author?: string;
    /** Cleaned main content, either as Markdown or HTML depending on `format`. */
    content: string;
    /** Description or summary of the article, if present in page metadata. */
    description?: string;
    /** Domain of the source page (e.g. `'example.com'`), if derivable. */
    domain?: string;
    /** URL of the source site's favicon, if detected. */
    favicon?: string;
    /** URL of the article's primary image, if detected. */
    image?: string;
    /** Page language in BCP 47 format (e.g. `'en'`, `'en-US'`), if detected. */
    language?: string;
    /** Meta tags extracted from the page head, keyed by name. */
    metaTags?: Record<string, string>;
    /** Time `defuddle` spent parsing, in milliseconds. */
    parseTime?: number;
    /** Publication date string, if detected. Format is source-dependent. */
    published?: string;
    /** Raw schema.org data extracted from the page, if present. */
    schemaOrgData?: unknown;
    /** Site name, if detected (e.g. from Open Graph `og:site_name`). */
    site?: string;
    /** Article title, if detected. */
    title?: string;
    /** Word count of the extracted content, as reported by `defuddle`. */
    wordCount?: number;
}
/**
 * Utility class for extracting main article content from raw HTML.
 *
 * Lazily loads `defuddle` and `linkedom` on first use — both are optional peer
 * dependencies (`bun add defuddle linkedom`). Returns cleaned main content
 * plus best-effort metadata: title, author, description, Open Graph fields,
 * schema.org data, word count.
 *
 * Does not guarantee structure beyond "main content of the page." For quirky
 * pages, malformed HTML, or SPA shells with minimal server-rendered content,
 * the result may be sparse — callers should degrade gracefully.
 */
export declare class HtmlExtractor {
    /**
     * Extracts the main article content from an HTML string.
     *
     * Async due to lazy loading of `defuddle` and `linkedom`, and because
     * Defuddle's node entry is itself async (supports async fallback extractors
     * gated by `useAsync`).
     *
     * @param html - Raw HTML string to extract from.
     * @param options - Optional extraction options (format, URL, content selector, etc.).
     * @param context - Optional `RequestContext` for correlated logging and error metadata.
     * @returns Extracted content and metadata. Only `content` is guaranteed to
     *   be present; all other fields are best-effort.
     * @throws {McpError} With `ConfigurationError` if `defuddle` or `linkedom` is not installed.
     * @throws {McpError} With `ValidationError` if the HTML string is empty after trimming,
     *   or if `defuddle` fails to parse the page.
     *
     * @example
     * ```typescript
     * import { htmlExtractor } from '../../utils/parsing/htmlExtractor.js';
     *
     * const html = await fetch('https://example.com/article').then((r) => r.text());
     * const result = await htmlExtractor.extract(html, {
     *   url: 'https://example.com/article',
     *   format: 'markdown',
     * });
     *
     * console.log(result.title);
     * console.log(result.content);
     * ```
     */
    extract(html: string, options?: ExtractArticleOptions, context?: RequestContext): Promise<ExtractArticleResult>;
}
/**
 * Singleton instance of {@link HtmlExtractor}.
 *
 * Prefer this over constructing a new `HtmlExtractor` directly. Lazily loads
 * `defuddle` and `linkedom` on first call, so there is no startup cost if
 * HTML extraction is never used.
 *
 * @example
 * ```typescript
 * import { htmlExtractor } from '../../utils/parsing/htmlExtractor.js';
 *
 * const article = await htmlExtractor.extract(rawHtml, {
 *   url: 'https://example.com/post',
 *   format: 'markdown',
 * });
 *
 * // Hand the content + metadata to the LLM
 * llm.prompt({ title: article.title, body: article.content });
 * ```
 */
export declare const htmlExtractor: HtmlExtractor;
//# sourceMappingURL=htmlExtractor.d.ts.map