@octocrawl/sdk 0.3.0

package/dist/types/cjs/contracts/execution.d.ts

@@ -0,0 +1,197 @@
+import type { RobotsOverride } from './compliance.js';
+import type { FetchWarning, TraceEvent } from './result.js';
+import type { AttributeSelector, ListFormatRequest, ScreenshotOptions } from './structured.js';
+import type { PageAction } from './actions.js';
+/** In-process cancellation and an absolute UTC deadline. Never serialize signal. */
+export interface ExecutionContext {
+    signal?: AbortSignal;
+    deadlineAt?: number;
+    /** Persist publisher cooldown immediately, before an interruptible inline wait. */
+    onRetryAfter?: (url: string, retryAt: number) => void;
+    /**
+     * Hear of a recorded robots override the moment a lane applies it, before
+     * its request goes out: the ladder keeps the override on the run's answer
+     * when that lane never returns (a deadline) or another rung's result answers.
+     */
+    onRobotsOverride?: (applied: RobotsOverrideApplied) => void;
+}
+/** What a lane reports when it sets a robots.txt rule aside under a recorded override. */
+export interface RobotsOverrideApplied {
+    /** The lane's `robots_checked`, `robots_disallowed` and `robots_overridden` trace events, in that order. */
+    trace: readonly TraceEvent[];
+    /** The `robots_overridden` warning the lane's own result carries. */
+    warning: FetchWarning;
+}
+/**
+ * What the caller asked a lane to capture from one page. It changes the
+ * content a lane emits, never the Evidence (hashes, status rules).
+ */
+export interface FetchOptions {
+    /** false: Markdown of the whole page body, header, navigation and footer kept. Default true. */
+    onlyMainContent?: boolean;
+    /** Milliseconds a browser rung waits after load and stability before capture. Default 0. */
+    waitFor?: number;
+    /**
+     * The caller's own `timeout`, when it set one. The deadline itself is the
+     * ExecutionContext's; this says the caller chose it, so a lane waits for a
+     * slow server (HTTP headers and body, browser navigation) until that
+     * deadline instead of stopping at its default caps.
+     */
+    timeout?: number;
+    /**
+     * Bytes a file (PDF, CSV, XLSX, ZIP, JSON, text) may have, below the
+     * operator's cap (`NetworkPolicy.maxFileBytes`); a larger file is failed
+     * with `body_too_large` and not saved. Web pages keep `maxBodyBytes`.
+     */
+    maxFileBytes?: number;
+    /**
+     * How a PDF response is read (Firecrawl's `parsers`): absent reads every
+     * PDF's text layer with W2L's defaults; `[]` reads none (the file is saved
+     * as received, without text); one `pdf` entry sets the options. Other
+     * files are unaffected.
+     */
+    parsers?: readonly PdfParser[];
+    /**
+     * A recorded decision to fetch this one URL although its host's robots.txt
+     * disallows it. robots.txt is still read and its verdict recorded; the
+     * override goes into the trace, the warnings and, in the browser lane, the
+     * compliance record. An unreachable robots.txt is not set aside. The HTTP
+     * and local browser lanes apply it; the provider lane takes none.
+     * Set per URL by the caller (a scrape's `robotsOverride`, a batch's
+     * `robotsOverrides` entry), never by a batch or crawl for every page.
+     */
+    robotsOverride?: RobotsOverride;
+    /**
+     * CSS selectors naming the only elements to keep. The content is those
+     * elements, in document order, copied from the page before anything is
+     * cleaned away, so a named navigation stays; `onlyMainContent` no longer
+     * chooses the content. Nothing matching is an empty answer. The page's
+     * type, title and metadata are still read from the whole page. The API
+     * refuses a selector the extractor does not match (@w2l/extract-tf
+     * `invalidSelector`) and a list of more parts than it matches for one
+     * list (`MAX_SELECTOR_PARTS`); a lane given either reads it as naming
+     * nothing.
+     */
+    includeTags?: readonly string[];
+    /**
+     * CSS selectors removed, with everything inside them, before the content
+     * is taken: from the main content, from the whole page
+     * (`onlyMainContent: false`) and from an `includeTags` selection alike.
+     * The same selectors as `includeTags`.
+     */
+    excludeTags?: readonly string[];
+    /**
+     * Extra request headers, lower-cased names, validated by the API
+     * (`readHeaders`): never the User-Agent, a client hint, a credential or a
+     * transport header. The HTTP and local browser lanes send them with the
+     * requested URL and its same-origin hops and subresources, after the
+     * declared identity, and record them (`request_headers_added`). Both lanes
+     * fetch a redirect hop to another origin with the identity alone and say so
+     * (`custom_headers_withheld`); on the browser lane the headers are added per
+     * request through Chromium's request interception, which judges every hop
+     * and every file the page loads by its own origin, so a navigation the page
+     * makes to another origin gets none either. robots.txt is fetched with the
+     * identity alone. Everything here is on the record.
+     */
+    headers?: Readonly<Record<string, string>>;
+    /**
+     * Fetch as the declared mobile Chrome identity (Android User-Agent, mobile
+     * client hints, 412x915 viewport, touch) instead of the desktop one. A
+     * second declared identity, not a disguise: it passes the same coherence
+     * and honesty checks, and robots.txt is evaluated against its User-Agent.
+     * Default false. Refused with research mode, which declares a bot.
+     */
+    mobile?: boolean;
+    /**
+     * Local only: load a site whose certificate does not verify (self-signed,
+     * expired, wrong name). The lanes relax verification for this one fetch
+     * and its robots.txt lookup, say so in the trace
+     * (`tls_verification_skipped`) and in a `tls_unverified` warning. Default
+     * false: a certificate failure is `failed` / `tls_error`. A hosted engine
+     * refuses the option.
+     */
+    skipTlsVerification?: boolean;
+    /**
+     * Abort requests to a bundled list of ad-serving hosts on the local
+     * browser lane (`ads_blocked`), and remove ad and cookie-banner elements
+     * before extraction on every lane. Default true; false keeps them in the
+     * Markdown and `html`. The hosted browser's host allowlist stays in force
+     * whatever this says.
+     */
+    blockAds?: boolean;
+    /**
+     * Carry `html` on a contentful result: the cleaned HTML its Markdown was
+     * written from. Set from the requested formats (`html`), not by a caller.
+     */
+    includeHtml?: boolean;
+    /**
+     * Carry `rawHtml` on a contentful result: the page as the lane received
+     * it. Set from the requested formats (`rawHtml`), not by a caller.
+     */
+    includeRawHtml?: boolean;
+    /**
+     * Carry `images` on a contentful result: every image URL of the whole
+     * document as received (the rendered DOM on a browser lane). Set from the
+     * requested formats (`images`), not by a caller.
+     */
+    includeImages?: boolean;
+    /**
+     * Carry `tables` on a contentful result: every data table of the content
+     * the Markdown was written from, as data and CSV. Set from the requested
+     * formats (`tables`), not by a caller.
+     */
+    includeTables?: boolean;
+    /**
+     * Carry `attributes` on a contentful result: for each selector, the named
+     * attribute's values on the elements it matches in the document as
+     * received. Set from the requested formats (an `attributes` entry), not
+     * by a caller; the API has checked the selectors (`invalidSelector`).
+     */
+    attributes?: readonly AttributeSelector[];
+    /** The `list` format's request, set from the requested formats, not by a caller; the API has checked its selectors. */
+    list?: ListFormatRequest;
+    /**
+     * Whether an `<img>` whose `src` is a `data:` URI is left out of the
+     * Markdown, its alt text kept (Firecrawl's `removeBase64Images`). Default
+     * true, which every lane always did; false keeps the image as
+     * `![alt](data:…)`, which the token count then counts. `html` and
+     * `rawHtml` are never rewritten. A rendering choice, not a fetch fact: no
+     * trace event or warning.
+     */
+    removeBase64Images?: boolean;
+    /**
+     * Capture the rendered page as an image (the `screenshot` format): a PNG,
+     * or a JPEG at `quality`, of the viewport (the request's `viewport` within
+     * the declared screen, else the declared one) or of the document's whole
+     * height (`fullPage`, without scrolling first), taken after load,
+     * stability and `waitFor` and before the DOM is read, CSS-pixel sized. The
+     * local browser lane alone honours it, and the API selects that lane alone
+     * for such a request; the http and provider lanes ignore it. Set from the
+     * requested formats (a `screenshot` entry), not by a caller.
+     */
+    screenshot?: ScreenshotOptions;
+    /**
+     * Steps the local browser runs on the page after load, stability and
+     * `waitFor`, and before the screenshot format and the DOM are read
+     * (`actions`). The local browser lanes alone run them; the API selects
+     * those lanes alone for such a request.
+     */
+    actions?: readonly PageAction[];
+}
+/** The largest `maxPages` a pdf parser entry may ask for. */
+export declare const MAX_PDF_PAGES = 10000;
+/**
+ * The `pdf` entry of `parsers`. W2L reads a PDF's text layer and runs no
+ * OCR, so `mode` is `fast` or `auto`, both that reader (`ocr` is refused).
+ */
+export interface PdfParser {
+    type: 'pdf';
+    mode?: 'fast' | 'auto';
+    /** Read at most this many pages, from the first (1 to MAX_PDF_PAGES); default 1000. A document cut by it is `success` with a `page_cap` warning: the cut was asked for. */
+    maxPages?: number;
+    /** Also return each page's Markdown as `pages: [{ pageNumber, markdown }]`. Default false. */
+    pages?: boolean;
+    /** A `<!-- page N -->` line before each page's text. Default true natively, false on `/fc` as on Firecrawl. */
+    pageMarkers?: boolean;
+}
+//# sourceMappingURL=execution.d.ts.map

package/dist/types/cjs/contracts/extractor.d.ts

@@ -0,0 +1,379 @@
+/**
+ * Extractor contract: the seam every main-content extractor implements
+ * (extract-tf, the v0 readability wrapper, and any future tier).
+ */
+/** Page shape the extractor routed to. */
+export type PageType = 'article' | 'listing' | 'collection' | 'product' | 'forum';
+/** Extraction strategy that produced mainHtml, independent of pageType. */
+export type ExtractStrategy = 'article' | 'list' | 'table' | 'product';
+/**
+ * Where a product fact came from. The ordering is a strength ordering:
+ * `jsonld` and `microdata` are the publisher's own machine-readable claim,
+ * `meta` is a tag written for machines, `text` is our reading of rendered
+ * prose, `inferred` is our derivation from context (e.g., currency from domain).
+ * A price we matched out of visible text is a weaker claim than one
+ * the publisher declared, and a consumer is entitled to know which it got.
+ */
+export type ProductFactSource = 'jsonld' | 'microdata' | 'meta' | 'dom' | 'text' | 'inferred' | 'model';
+/** Evidence classes allowed on the normalized cross-site entity surface. */
+export type EntityFieldSource = 'jsonld' | 'microdata' | 'meta' | 'hydration' | 'dom' | 'inferred';
+export type EntityFieldStatus = 'confirmed' | 'unconfirmed';
+export type EntityType = 'product' | 'post' | 'thread' | 'comment' | 'profile' | 'community' | 'video' | 'article';
+export type AdapterStatus = 'generic' | 'beta adapter' | 'verified adapter' | 'unsupported';
+export type EntityValue = string | number | boolean | null | readonly EntityValue[] | {
+    readonly [key: string]: EntityValue;
+};
+export interface EntityField<T extends EntityValue = EntityValue> {
+    /** Value exactly as observed on the page. */
+    raw: T;
+    /** Stable value used across adapters. */
+    normalized: T;
+    source: EntityFieldSource;
+    /** CSS selector, JSON Pointer, URL component, or another public-page location. */
+    path: string;
+    status: EntityFieldStatus;
+}
+export interface ExtractedEntity {
+    type: EntityType;
+    id: string | null;
+    fields: Readonly<Record<string, EntityField>>;
+    /** IDs of other entities in this response, e.g. parent/author/community. */
+    relationships: Readonly<Record<string, string | readonly string[] | null>>;
+}
+export interface AdapterDescriptor {
+    id: string;
+    version: string;
+    status: AdapterStatus;
+}
+/** Identity and provenance checks performed by a site adapter. */
+export interface AdapterValidation {
+    valid: boolean;
+    issues: readonly string[];
+}
+/** One product fact plus the evidence class it was drawn from. */
+export interface ProductFact {
+    /** The value exactly as the page carried it. Never normalized — a
+     *  normalized price is a claim we would be making, not one we read. */
+    value: string;
+    source: ProductFactSource;
+    /** JSON Pointer or CSS selector locating the evidence when available. */
+    path?: string;
+}
+export interface ProductPrice {
+    amount: ProductFact;
+    currency: ProductFact | null;
+    priceType: 'current' | 'list' | 'unit' | 'subscription' | 'other';
+    seller: ProductFact | null;
+}
+export interface ProductVariant {
+    name: string;
+    value: string;
+    selected: boolean;
+    source: ProductFactSource;
+    path?: string;
+}
+/**
+ * Product identity verification result with multi-evidence approach.
+ * R1-B: Ensures we never output data for the wrong product.
+ */
+export interface ProductIdentity {
+    /** ASIN or SKU requested by the user (from URL). */
+    requestedId: string;
+    /** ASIN or SKU observed as selected on the page (from DOM multi-evidence). */
+    observedSelectedId: string;
+    /** Parent ASIN if this is a variant product. */
+    parentId: string | null;
+    /** Selected variant attributes if applicable. */
+    selectedVariants: readonly ProductVariant[];
+    /** Why the selected subject could or could not be verified. */
+    status: 'matched' | 'mismatched' | 'unverified' | 'conflicting';
+    /** True only when the observed selected product is the requested product. */
+    identityMatch: boolean;
+    /** CSS selectors or paths that contributed to identity determination. */
+    identityEvidence: readonly string[];
+}
+/**
+ * Quote/price state classification.
+ * R1-C: Distinguishes "definitely absent" from "not found yet" from "present".
+ */
+export declare enum QuoteState {
+    /** Quote found and extracted successfully. */
+    Present = "present",
+    /** Evidence that quote does not exist (e.g., "Currently unavailable"). */
+    AbsentObserved = "absent_observed",
+    /** Not found in current extraction, may exist elsewhere. */
+    Unobserved = "unobserved",
+    /** Multiple conflicting quotes found. */
+    Conflicting = "conflicting"
+}
+/**
+ * Facts a product-detail page asserted about the product it is about.
+ * Every field is independently nullable: a page may declare a price and no
+ * SKU, and inventing the missing one is worse than reporting null.
+ */
+export interface ProductFacts {
+    name: ProductFact | null;
+    price: ProductFact | null;
+    priceCurrency: ProductFact | null;
+    sku: ProductFact | null;
+    brand: ProductFact | null;
+    availability: ProductFact | null;
+    /** Rich product facts are additive so older extractors remain valid. */
+    kind?: 'physical' | 'subscription' | 'unknown';
+    subjectId?: ProductFact | null;
+    prices?: readonly ProductPrice[];
+    seller?: ProductFact | null;
+    deliveryLocation?: ProductFact | null;
+    rating?: ProductFact | null;
+    reviewCount?: ProductFact | null;
+    images?: readonly ProductFact[];
+    variants?: readonly ProductVariant[];
+    specifications?: Readonly<Record<string, ProductFact>>;
+    /** R1-B: Multi-evidence identity verification. */
+    identity?: ProductIdentity;
+    /** R1-C: Quote state classification. */
+    quoteState?: QuoteState;
+}
+/**
+ * A value the page states under its own label: a two-cell table row (a `<th>`
+ * label and a `<td>` value) or a definition-list pair (one `<dt>`, one
+ * `<dd>`) in the main content. Both texts are as the page shows them, with
+ * whitespace collapsed; nothing is normalized.
+ */
+export interface LabelledValue {
+    label: string;
+    value: string;
+    /**
+     * `table[i] tr[j]` or `dl[i] dt[j]`: zero-based, in document order, the
+     * table or list among those in the main content and the row or term in it.
+     */
+    path: string;
+}
+/**
+ * What the page's own markup declares about the page, read from the whole
+ * document before cleaning. Each value is that declaration or null when the
+ * page makes none: nothing is inferred from the URL, the content or another
+ * tag (no `og:description` for a missing description, no `/favicon.ico` for a
+ * missing icon).
+ */
+export interface PageMetadata {
+    /**
+     * The document's `<title>`, whitespace collapsed as `document.title` does
+     * (an SVG `<title>` does not count). Unlike `document.title`, the content
+     * title, it never comes from a heading.
+     */
+    title: string | null;
+    /** `<meta name="description">`. */
+    description: string | null;
+    /** `<html lang>`; when `<html>` has no lang attribute, `<meta http-equiv="content-language">`. */
+    language: string | null;
+    /** `<meta name="keywords">` as declared, not split. */
+    keywords: string | null;
+    /** `<meta name="robots">`. */
+    robots: string | null;
+    /** The first `<link rel~="icon">` that resolves, against the document base URL, to an http(s) URL. */
+    favicon: string | null;
+    /** The first `<link rel~="canonical">` that resolves to an http(s) URL. */
+    canonicalUrl: string | null;
+    /** `<meta property="og:title">` (or `name=`). */
+    ogTitle?: string;
+    /** `og:description`; an empty `content` is no declaration. */
+    ogDescription?: string;
+    /** `og:url`, resolved against the document base URL when it parses, else as written. */
+    ogUrl?: string;
+    /** `og:image`, else `og:image:secure_url`, else `og:image:url`; resolved like `ogUrl`. */
+    ogImage?: string;
+    /** `og:audio`, resolved like `ogUrl`. */
+    ogAudio?: string;
+    /** `og:video`, else `og:video:secure_url`, else `og:video:url`; resolved like `ogUrl`. */
+    ogVideo?: string;
+    /** `og:determiner`. */
+    ogDeterminer?: string;
+    /** `og:locale`. */
+    ogLocale?: string;
+    /** Every `og:locale:alternate`, in document order. */
+    ogLocaleAlternate?: readonly string[];
+    /** `og:site_name`. */
+    ogSiteName?: string;
+    /** `<meta name="dcterms.created">`. */
+    dcTermsCreated?: string;
+    /** `<meta name="dc.date.created">`. */
+    dcDateCreated?: string;
+    /** `<meta name="dc.date">`. */
+    dcDate?: string;
+    /** `<meta name="dcterms.type">`. */
+    dcTermsType?: string;
+    /** `<meta name="dc.type">`. */
+    dcType?: string;
+    /** `<meta name="dcterms.audience">`. */
+    dcTermsAudience?: string;
+    /** `<meta name="dcterms.subject">`. */
+    dcTermsSubject?: string;
+    /** `<meta name="dc.subject">`. */
+    dcSubject?: string;
+    /** `<meta name="dc.description">`. */
+    dcDescription?: string;
+    /** `<meta name="dcterms.keywords">`. */
+    dcTermsKeywords?: string;
+    /** `article:published_time`, as the page writes it: no date normalisation. */
+    publishedTime?: string;
+    /** `article:modified_time`, as written. */
+    modifiedTime?: string;
+    /** Every `article:tag`, in document order. */
+    articleTag?: readonly string[];
+    /** `article:section`. */
+    articleSection?: string;
+}
+export interface DocumentExtraction {
+    title: string | null;
+    pageType: PageType;
+    strategy: ExtractStrategy;
+    confidence: number;
+    product: ProductFacts | null;
+    adapter: AdapterDescriptor;
+    entities: readonly ExtractedEntity[];
+    adapterValidation?: AdapterValidation;
+    /** Label/value pairs of the main content; JSON extraction matches them to schema keys. */
+    labelledValues?: readonly LabelledValue[];
+}
+/** The rule that decided a page's data is most likely rendered client-side (see RenderSignals). */
+export type RenderReason = 'empty_table_with_scripts' | 'empty_app_root' | 'script_shell' | 'js_fallback' | 'hydration_shell' | 'aria_busy';
+/** A client-side rendering marker found in the page as received (see RenderSignals). */
+export type RenderMarker = 'hydration_state' | 'app_root_empty' | 'noscript_notice' | 'js_fallback_marker' | 'aria_busy';
+/**
+ * Evidence that a page fills its data in with JavaScript after load, read
+ * from the server HTML. A shell with an empty app root, a table with no
+ * cells beside kilobytes of script, or an explicit "enable JavaScript"
+ * fallback all mean the HTTP capture is not the page a browser shows.
+ */
+export interface RenderSignals {
+    /** Visible text characters after boilerplate cleaning. */
+    textChars: number;
+    /** Characters of inline script in the raw document. */
+    scriptChars: number;
+    /** `<table>` elements with no data cells. */
+    emptyTables: number;
+    /** Markers found in the page as received. */
+    markers: readonly RenderMarker[];
+    /** True when the signals say the data is most likely rendered client-side. */
+    clientRendered: boolean;
+    /**
+     * The rule that decided `clientRendered`, null when false. Every rule pairs
+     * a structural gap with script presence; a `noscript` notice alone counts
+     * only on a thin page or beside hydration state.
+     */
+    reason: RenderReason | null;
+}
+export interface ExtractorOutput {
+    /** Page title, or null when none could be found. */
+    title: string | null;
+    /** Extracted main content as HTML. Markdown conversion happens later in the pipeline. */
+    mainHtml: string;
+    /**
+     * Base URL for the page's relative URLs: the first `<base href>` resolved
+     * against `options.url`, else `options.url`. mainHtml is a fragment without
+     * the page's `<base>` element, so Markdown conversion takes this instead.
+     * Null when no absolute URL is known.
+     */
+    baseUrl: string | null;
+    /** The page's own declarations (title, description, language, ...), from the whole document. */
+    metadata: PageMetadata;
+    /** 0..1 self-assessed extraction confidence. */
+    confidence: number;
+    /**
+     * True when this page should be routed to a higher tier (LLM/neural).
+     * The escalation target is intentionally unimplemented in v0.
+     */
+    escalate: boolean;
+    /**
+     * True when mainHtml came only from the last resort, a list the page repeats
+     * (`selectDetectedList`), after every strategy found nothing. A lane still
+     * checks such a page for a wall (a login form, a challenge) as it does one
+     * with nothing found, since a list sits beside many walls.
+     */
+    lastResort?: boolean;
+    /** Page type the router detected. */
+    pageType: PageType;
+    /**
+     * The strategy that produced mainHtml. Independent of pageType: a product
+     * page may use the table strategy, a forum thread the article cascade.
+     */
+    strategy: ExtractStrategy;
+    /**
+     * Product facts, present only when pageType is 'product'. Null on every
+     * other page type — an article has no price, and an empty ProductFacts
+     * object would read as "we looked and found none".
+     */
+    product?: ProductFacts | null;
+    /** Adapter identity and normalized entities are produced directly from HTML. */
+    adapter: AdapterDescriptor;
+    entities: readonly ExtractedEntity[];
+    adapterValidation?: AdapterValidation;
+    /**
+     * Tables in the fetched HTML with no rows at all: an empty `<thead>` and
+     * `<tbody>` waiting for a script to fill them. The data is not in this HTML.
+     */
+    emptyTableShells?: number;
+    /**
+     * Data the page declares its scripts will fetch once they run
+     * (`<link rel="preload" as="fetch">`). Whatever the scripts build from it,
+     * a table or a chart, is not in this HTML.
+     */
+    fetchPreloads?: number;
+    /**
+     * Client-side rendering signals read from the page as received: whether
+     * its data is most likely filled in by scripts after load, and why. A lane
+     * that cannot run scripts reads `clientRendered` as a caveat on its
+     * capture; one that rendered the page has no use for it.
+     */
+    render?: RenderSignals;
+    /** Label/value pairs of the main content (see LabelledValue). */
+    labelledValues?: readonly LabelledValue[];
+    /** Monotonic extractor stage timings. */
+    timings: {
+        parseMs: number;
+        extractMs: number;
+    };
+}
+export interface ExtractorOptions {
+    /** Final URL after redirects. Site adapters use it only as an identity signal. */
+    url?: string;
+    /**
+     * Prefer less text but correct extraction (tighten thresholds, require a
+     * semantic container). Mirrors trafilatura's favor_precision.
+     */
+    favorPrecision?: boolean;
+    /** When unsure, prefer more text (loosen thresholds). Mirrors favor_recall. */
+    favorRecall?: boolean;
+    /**
+     * Extra CSS selectors to prune from the tree before extraction. Like
+     * `includeSelectors`, limited to the selectors that are matched in time
+     * proportional to the page (@w2l/extract-tf `invalidSelector`); any other
+     * names nothing.
+     */
+    pruneSelectors?: readonly string[];
+    /**
+     * CSS selectors naming the only elements to keep. mainHtml is then a
+     * `<body>` holding those elements in document order, copied from the page
+     * before cleaning and without `pruneSelectors`, and its confidence is 1
+     * when they hold any text or image: what the caller named is the content.
+     * Nothing matching gives an empty mainHtml. The page type, title, metadata
+     * and product facts are still read from the whole page, and `escalate`
+     * stays the page's own signal (the cascade found no main content): a lane
+     * reads it for its block check and its offer to the browser, and does not
+     * fail a selection for it.
+     */
+    includeSelectors?: readonly string[];
+    /**
+     * Remove ad containers (id or class tokens such as `ad`, `advertisement`,
+     * `sponsored`, `promo`) and cookie-consent banners before the cascade
+     * runs. Default true, which is what every extraction did before the
+     * switch existed; false keeps them. The structural cleaning (scripts,
+     * styles, navigation, forms) is not affected.
+     */
+    blockAds?: boolean;
+}
+export interface Extractor {
+    extract(html: string, options?: ExtractorOptions): ExtractorOutput;
+}
+//# sourceMappingURL=extractor.d.ts.map