@mxfb/tools 1.0.0 → 1.0.3

package/agnostic/scrapers/@tumblr/utils.js

@@ -0,0 +1,407 @@
+const TUMBLR_HOSTNAME_SUFFIX = '.tumblr.com';
+const TUMBLR_CANONICAL_HOSTNAMES = ['www.tumblr.com', 'tumblr.com'];
+const PERMALINK_PATHNAME_PATTERN = /^\/post\/(\d+)(?:\/|$)/v;
+const INDEX_PAGE_PATHNAME_PATTERN = /^\/page\/(\d+)(?:\/|$)/v;
+const ARCHIVE_PATHNAME_PATTERN = /^\/archive(?:\/|$)/v;
+const TAGGED_PATHNAME_PATTERN = /^\/tagged\//v;
+// A post block never reaches across one of these, so they stop the walk up the tree on a
+// permalink page, where no sibling post is there to stop it.
+const PAGE_LANDMARK_SELECTOR = 'nav, header, footer, aside';
+export function toIntegerOrNull(raw) {
+    if (raw === null)
+        return null;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isNaN(parsed) ? null : parsed;
+}
+export function readSitemapChildUrls(document) {
+    const urls = [];
+    for (const entry of Array.from(document.getElementsByTagName('sitemap'))) {
+        const url = readFirstChildText(entry, 'loc');
+        if (url !== null)
+            urls.push(url);
+    }
+    return urls;
+}
+export function readSitemapLocations(document) {
+    const locations = [];
+    for (const entry of Array.from(document.getElementsByTagName('url'))) {
+        const url = readFirstChildText(entry, 'loc');
+        if (url === null)
+            continue;
+        locations.push({
+            url,
+            lastModifiedOn: toDateOrNull(readFirstChildText(entry, 'lastmod'))
+        });
+    }
+    return locations;
+}
+export function toOrigin(url) {
+    if (url === null)
+        return null;
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return null;
+    }
+}
+export function readMetaProperty(document, property) {
+    return readAttribute(document, `meta[property="${property}"]`, 'content');
+}
+export function extractCanonicalUrl(document) {
+    return readLinkHref(document, 'canonical')
+        ?? readMetaProperty(document, 'og:url');
+}
+export function extractPageKind(pageUrl) {
+    const pathname = toPathname(pageUrl);
+    if (pathname === null)
+        return 'unknown';
+    if (PERMALINK_PATHNAME_PATTERN.test(pathname))
+        return 'permalink';
+    if (ARCHIVE_PATHNAME_PATTERN.test(pathname))
+        return 'archive';
+    // Kept as a pattern to stay symmetric with the three above.
+    /* eslint-disable-next-line @typescript-eslint/prefer-string-starts-ends-with */
+    if (TAGGED_PATHNAME_PATTERN.test(pathname))
+        return 'tagged';
+    if (INDEX_PAGE_PATHNAME_PATTERN.test(pathname))
+        return 'index';
+    if (pathname === '/')
+        return 'index';
+    return 'custom';
+}
+export function extractBlog(document, pageUrl, canonicalUrl, pageKind) {
+    const baseUrl = toOrigin(pageUrl);
+    const iconHref = readLinkHref(document, 'apple-touch-icon')
+        ?? readLinkHref(document, 'icon');
+    return {
+        name: extractBlogName(pageUrl, canonicalUrl),
+        title: readMetaProperty(document, 'og:site_name')
+            ?? toTextOrNull(document.querySelector('title')?.textContent ?? null),
+        description: extractBlogDescription(document, pageKind),
+        baseUrl,
+        avatarUrl: toAbsoluteUrl(iconHref, baseUrl),
+        navLinks: extractNavLinks(document, baseUrl)
+    };
+}
+export function extractPostFromPermalinkPage(document, pageUrl) {
+    const id = extractPostIdFromUrl(pageUrl);
+    const postIdByAnchor = indexPostAnchors(document, toOrigin(pageUrl));
+    return {
+        ...createIdentifiedPost(id, pageUrl),
+        type: extractPostType(readMetaProperty(document, 'og:type')),
+        publishedOn: toDateOrNull(readMetaProperty(document, 'article:published_time')),
+        title: readMetaProperty(document, 'og:title'),
+        tags: readEveryMetaProperty(document, 'article:tag'),
+        media: extractMedia(document),
+        ...readRawHtml(findPostElement(document, id, postIdByAnchor), 'permalink')
+    };
+}
+export function extractPostsFromListingPage(document, baseUrl) {
+    const postIdByAnchor = indexPostAnchors(document, baseUrl);
+    const postsById = new Map();
+    for (const [anchor, id] of postIdByAnchor) {
+        if (postsById.has(id))
+            continue;
+        const url = toAbsoluteUrl(anchor.getAttribute('href'), baseUrl);
+        postsById.set(id, {
+            ...createIdentifiedPost(id, url),
+            ...readRawHtml(findPostElement(document, id, postIdByAnchor), 'listing')
+        });
+    }
+    return Array.from(postsById.values());
+}
+export function extractPagination(document, pageUrl, baseUrl) {
+    const currentPageNumber = extractCurrentPageNumber(pageUrl);
+    const pageUrlsByNumber = collectPageUrlsByNumber(document, baseUrl);
+    const siblingPageUrl = (offset) => {
+        if (currentPageNumber === null)
+            return null;
+        return pageUrlsByNumber.get(currentPageNumber + offset) ?? null;
+    };
+    return {
+        currentPageNumber,
+        nextPageUrl: toAbsoluteUrl(readLinkHref(document, 'next'), baseUrl) ?? siblingPageUrl(1),
+        previousPageUrl: toAbsoluteUrl(readLinkHref(document, 'prev'), baseUrl) ?? siblingPageUrl(-1)
+    };
+}
+function readFirstChildText(element, tagName) {
+    return toTextOrNull(element.getElementsByTagName(tagName)[0]?.textContent ?? null);
+}
+function normalizeWhitespace(raw) {
+    return raw.replace(/\s+/gv, ' ').trim();
+}
+function toTextOrNull(raw) {
+    if (raw === null)
+        return null;
+    const normalized = normalizeWhitespace(raw);
+    return normalized === '' ? null : normalized;
+}
+function toDateOrNull(raw) {
+    if (raw === null)
+        return null;
+    const parsed = new Date(raw);
+    return Number.isNaN(parsed.getTime()) ? null : parsed;
+}
+function toAbsoluteUrl(href, baseUrl) {
+    if (href === null)
+        return null;
+    try {
+        return new URL(href, baseUrl ?? undefined).href;
+    }
+    catch {
+        return null;
+    }
+}
+function toPathname(url) {
+    if (url === null)
+        return null;
+    try {
+        return new URL(url).pathname;
+    }
+    catch {
+        return null;
+    }
+}
+function sharesOrigin(url, baseUrl) {
+    if (baseUrl === null)
+        return true;
+    return toOrigin(url) === toOrigin(baseUrl);
+}
+function readAttribute(document, selector, attributeName) {
+    return toTextOrNull(document.querySelector(selector)?.getAttribute(attributeName) ?? null);
+}
+function readMetaName(document, name) {
+    return readAttribute(document, `meta[name="${name}"]`, 'content');
+}
+function readLinkHref(document, relation) {
+    return readAttribute(document, `link[rel="${relation}"]`, 'href');
+}
+function readEveryMetaProperty(document, property) {
+    return Array
+        .from(document.querySelectorAll(`meta[property="${property}"]`))
+        .map(element => toTextOrNull(element.getAttribute('content')))
+        .filter((content) => content !== null);
+}
+function extractBlogName(pageUrl, canonicalUrl) {
+    return readBlogNameFromCanonicalUrl(canonicalUrl)
+        ?? readBlogNameFromHostname(pageUrl);
+}
+function readBlogNameFromCanonicalUrl(canonicalUrl) {
+    if (canonicalUrl === null)
+        return null;
+    let url;
+    try {
+        url = new URL(canonicalUrl);
+    }
+    catch {
+        return null;
+    }
+    if (!TUMBLR_CANONICAL_HOSTNAMES.includes(url.hostname))
+        return null;
+    const segments = url.pathname.split('/').filter(segment => segment !== '');
+    return segments[0] ?? null;
+}
+function readBlogNameFromHostname(pageUrl) {
+    let hostname;
+    try {
+        hostname = new URL(pageUrl).hostname;
+    }
+    catch {
+        return null;
+    }
+    if (!hostname.endsWith(TUMBLR_HOSTNAME_SUFFIX))
+        return null;
+    const name = hostname.slice(0, -TUMBLR_HOSTNAME_SUFFIX.length);
+    if (name === '' || name === 'www' || name.includes('.'))
+        return null;
+    return name;
+}
+function extractBlogDescription(document, pageKind) {
+    if (pageKind === 'permalink')
+        return null;
+    return readMetaName(document, 'description')
+        ?? readMetaProperty(document, 'og:description');
+}
+function extractNavLinks(document, baseUrl) {
+    const navLinks = [];
+    const seenUrls = new Set();
+    for (const anchor of document.querySelectorAll('nav a[href], header a[href]')) {
+        const url = toAbsoluteUrl(anchor.getAttribute('href'), baseUrl);
+        const label = toTextOrNull(anchor.textContent);
+        if (url === null || label === null)
+            continue;
+        if (!sharesOrigin(url, baseUrl) || seenUrls.has(url))
+            continue;
+        seenUrls.add(url);
+        navLinks.push({ label, url });
+    }
+    return navLinks;
+}
+function extractPostIdFromUrl(url) {
+    const pathname = toPathname(url);
+    if (pathname === null)
+        return null;
+    return PERMALINK_PATHNAME_PATTERN.exec(pathname)?.[1] ?? null;
+}
+function extractPageNumberFromUrl(url) {
+    const pathname = toPathname(url);
+    if (pathname === null)
+        return null;
+    return toIntegerOrNull(INDEX_PAGE_PATHNAME_PATTERN.exec(pathname)?.[1] ?? null);
+}
+function extractPostType(openGraphType) {
+    if (openGraphType === null)
+        return 'unknown';
+    if (openGraphType.startsWith('video'))
+        return 'video';
+    if (openGraphType.startsWith('music'))
+        return 'audio';
+    return 'unknown';
+}
+function extractMedia(document) {
+    const media = [];
+    const imageUrl = readMetaProperty(document, 'og:image');
+    if (imageUrl !== null) {
+        media.push({
+            kind: 'image',
+            url: imageUrl,
+            widthPx: toIntegerOrNull(readMetaProperty(document, 'og:image:width')),
+            heightPx: toIntegerOrNull(readMetaProperty(document, 'og:image:height')),
+            alternativeText: readMetaProperty(document, 'og:image:alt')
+        });
+    }
+    const videoUrl = readMetaProperty(document, 'og:video');
+    if (videoUrl !== null) {
+        media.push({
+            kind: 'video',
+            url: videoUrl,
+            widthPx: toIntegerOrNull(readMetaProperty(document, 'og:video:width')),
+            heightPx: toIntegerOrNull(readMetaProperty(document, 'og:video:height')),
+            alternativeText: null
+        });
+    }
+    const audioUrl = readMetaProperty(document, 'og:audio');
+    if (audioUrl !== null) {
+        media.push({
+            kind: 'audio',
+            url: audioUrl,
+            widthPx: null,
+            heightPx: null,
+            alternativeText: null
+        });
+    }
+    return media;
+}
+function indexPostAnchors(document, baseUrl) {
+    const postIdByAnchor = new Map();
+    for (const anchor of document.querySelectorAll('a[href]')) {
+        const url = toAbsoluteUrl(anchor.getAttribute('href'), baseUrl);
+        if (url === null || !sharesOrigin(url, baseUrl))
+            continue;
+        const id = extractPostIdFromUrl(url);
+        if (id === null)
+            continue;
+        postIdByAnchor.set(anchor, id);
+    }
+    return postIdByAnchor;
+}
+function findPostElement(document, postId, postIdByAnchor) {
+    if (postId === null)
+        return null;
+    const blocks = [];
+    for (const [anchor, id] of postIdByAnchor) {
+        if (id !== postId)
+            continue;
+        const block = climbToPostBlock(anchor, postId, postIdByAnchor);
+        if (block !== null && !blocks.includes(block))
+            blocks.push(block);
+    }
+    if (blocks.length === 0)
+        return document.querySelector('article');
+    const namedBlocks = blocks.filter(block => namesPost(block, postId));
+    return widestElement(namedBlocks.length > 0 ? namedBlocks : blocks);
+}
+function climbToPostBlock(anchor, postId, postIdByAnchor) {
+    let candidate = anchor;
+    let widestBlock = null;
+    let nearestNamedBlock = null;
+    while (holdsOnlyThisPost(candidate, postId, postIdByAnchor)) {
+        widestBlock = candidate;
+        if (nearestNamedBlock === null && namesPost(candidate, postId))
+            nearestNamedBlock = candidate;
+        const parent = candidate.parentElement;
+        if (parent === null || parent.tagName === 'BODY' || parent.tagName === 'HTML')
+            break;
+        candidate = parent;
+    }
+    return nearestNamedBlock ?? widestBlock;
+}
+function widestElement(elements) {
+    let widest = null;
+    for (const element of elements) {
+        if (widest === null || element.outerHTML.length > widest.outerHTML.length)
+            widest = element;
+    }
+    return widest;
+}
+function holdsOnlyThisPost(element, postId, postIdByAnchor) {
+    if (element.matches(PAGE_LANDMARK_SELECTOR))
+        return false;
+    if (element.querySelector(PAGE_LANDMARK_SELECTOR) !== null)
+        return false;
+    for (const anchor of element.querySelectorAll('a[href]')) {
+        const id = postIdByAnchor.get(anchor);
+        if (id !== undefined && id !== postId)
+            return false;
+    }
+    return true;
+}
+function namesPost(element, postId) {
+    return element.tagName === 'ARTICLE' || element.id.includes(postId);
+}
+function readRawHtml(postElement, source) {
+    if (postElement === null)
+        return { rawHtml: null, rawHtmlSource: null };
+    return { rawHtml: postElement.outerHTML, rawHtmlSource: source };
+}
+function createIdentifiedPost(id, url) {
+    return {
+        id,
+        url,
+        type: 'unknown',
+        publishedOn: null,
+        title: null,
+        contentHtml: null,
+        rawHtml: null,
+        rawHtmlSource: null,
+        detail: null,
+        tags: [],
+        media: [],
+        notesCount: null,
+        reblogOfUrl: null,
+        lastModifiedOn: null
+    };
+}
+function collectPageUrlsByNumber(document, baseUrl) {
+    const pageUrlsByNumber = new Map();
+    for (const anchor of document.querySelectorAll('a[href]')) {
+        const url = toAbsoluteUrl(anchor.getAttribute('href'), baseUrl);
+        if (url === null || !sharesOrigin(url, baseUrl))
+            continue;
+        const pageNumber = extractPageNumberFromUrl(url);
+        if (pageNumber === null || pageUrlsByNumber.has(pageNumber))
+            continue;
+        pageUrlsByNumber.set(pageNumber, url);
+    }
+    return pageUrlsByNumber;
+}
+function extractCurrentPageNumber(pageUrl) {
+    const pathname = toPathname(pageUrl);
+    if (pathname === null)
+        return null;
+    const declaredPageNumber = extractPageNumberFromUrl(pageUrl);
+    if (declaredPageNumber !== null)
+        return declaredPageNumber;
+    return pathname === '/' ? 1 : null;
+}

package/agnostic/scrapers/index.d.ts

@@ -0,0 +1,2 @@
+export * as meteociel from './@meteociel/index.js'
+export * as tumblr from './@tumblr/index.js'

package/agnostic/scrapers/index.js

@@ -0,0 +1,2 @@
+export * as meteociel from './@meteociel/index.js'
+export * as tumblr from './@tumblr/index.js'

package/agnostic/weather/index.d.ts

@@ -0,0 +1 @@
+export {}

package/agnostic/weather/index.js

@@ -0,0 +1 @@
+export {}

package/agnostic/weather/types.d.ts

@@ -157,7 +157,7 @@ export type WeatherObservation = WeatherDataCore & {
         /** Observation source metadata (station, provider, license...). */ source?: ObservationDataSource;
         /** Time when the data was collected or ingested by the system. */ collectedOn?: Date;
         /** Human-readable description or summary of the observation. */ description?: string;
-        /** Raw source data as received from the provider. */ rawData?: Record<string, any> | string;
+        /** Raw source data as received from the provider. */ rawData?: Record<string, unknown> | string;
         /** Quality control and processing metadata for the observation. */ observationQuality?: ObservationQualityMetadata;
     };
 };
@@ -175,7 +175,7 @@ export type WeatherForecast = WeatherDataCore & {
         /** Forecast model and source metadata. */ source?: ForecastDataSource;
         /** Time when the data was collected or ingested by the system. */ collectedOn?: Date;
         /** Human-readable description or summary of the observation. */ description?: string;
-        /** Raw source data as received from the provider. */ rawData?: Record<string, any> | string;
+        /** Raw source data as received from the provider. */ rawData?: Record<string, unknown> | string;
         /** Associated probabilistic forecast information, if available. */ probabilistic?: ProbabilisticData;
     };
 };

package/agnostic/weather/types.js

@@ -0,0 +1,8 @@
+/**
+ * Core weather data types for archiving and exchanging meteorological information.
+ *
+ * The structures are inspired by WMO (World Meteorological Organization) guidance
+ * and CF Conventions. Units are encoded explicitly in property names to avoid
+ * ambiguity and to make transformations between systems easier and safer.
+ */
+export {};

package/components/index.d.ts

@@ -0,0 +1 @@
+export * as utils from './utils/index.js'

package/components/index.js

@@ -0,0 +1 @@
+export * as utils from './utils/index.js'

package/components/public-classnames.d.ts

@@ -0,0 +1,5 @@
+export declare const button = "mxfb-button";
+export declare const input = "mxfb-input";
+export declare const jsonEditor = "mxfb-json-editor";
+export declare const select = "mxfb-select";
+export declare const textarea = "mxfb-textarea";

package/components/public-classnames.js

@@ -0,0 +1,5 @@
+export const button = 'mxfb-button';
+export const input = 'mxfb-input';
+export const jsonEditor = 'mxfb-json-editor';
+export const select = 'mxfb-select';
+export const textarea = 'mxfb-textarea';

package/components/utils/index.d.ts

@@ -0,0 +1 @@
+export declare function mergeClassNames(...names: Array<string | null | undefined | Array<string | null | undefined>>): string;

package/components/utils/index.js

@@ -0,0 +1,12 @@
+export function mergeClassNames(...names) {
+    return names.map(name => {
+        if (typeof name !== 'string' && !Array.isArray(name))
+            return false;
+        if (Array.isArray(name))
+            return mergeClassNames(...name);
+        if (name.trim() === '')
+            return false;
+        return name.trim();
+    }).filter((name) => typeof name === 'string')
+        .join(' ');
+}

package/components/utils/types.d.ts

@@ -0,0 +1,3 @@
+export type WithClassName<T extends Record<string, unknown>> = T & {
+    className?: string | Array<string | null | undefined>;
+};

package/components/utils/types.js

@@ -0,0 +1 @@
+export {};

package/index.d.ts

@@ -0,0 +1,3 @@
+export * as agnostic from './agnostic/index.js'
+export * as components from './components/index.js'
+export * as node from './node/index.js'

package/index.js

@@ -0,0 +1,3 @@
+export * as agnostic from './agnostic/index.js'
+export * as components from './components/index.js'
+export * as node from './node/index.js'

package/node/headless-browser/index.d.ts

@@ -0,0 +1,37 @@
+import type { HeadlessBrowserOptions, HeadlessReadOptions } from './types.js';
+/**
+ * A Chrome session that reads pages an HTTP client alone cannot reach.
+ *
+ * Some hosts — every `*.tumblr.com` blog among them — answer any plain request with a 403
+ * carrying a JavaScript challenge, and only serve the real page to whoever runs it. One
+ * tab is kept per origin: the first read of an origin navigates there and waits for the
+ * challenge to clear, and both read modes then reuse that cleared tab, so the cookies it
+ * was granted keep applying.
+ *
+ * The browser starts itself on first use and must be closed by the caller.
+ */
+export declare class HeadlessBrowser {
+    private readonly options;
+    private readonly pagesByOrigin;
+    private browser;
+    constructor(options?: HeadlessBrowserOptions);
+    /**
+     * Reads one URL as text, starting the browser and clearing the origin's challenge when
+     * this is the first read of that origin.
+     *
+     * @param url - Absolute URL to read.
+     * @param readOptions - Overrides this session's read defaults for this call.
+     * @returns The page's text, or `null` when the URL has no readable origin, or when a
+     * `'served'` read met a response that was not a success. A `'rendered'` read returns
+     * whatever the tab ended up holding, error pages included, since that is the document
+     * the browser was given.
+     * @throws If the browser cannot be started, if a navigation times out, or if an
+     * interstitial never clears, as `challenge-not-cleared`.
+     */
+    readText(url: string, readOptions?: HeadlessReadOptions): Promise<string | null>;
+    /** Closes every tab and the browser itself. Reading again starts a new one. */
+    close(): Promise<void>;
+    private openOrigin;
+    private start;
+    private waitForChallenge;
+}

package/node/headless-browser/index.js

@@ -0,0 +1,126 @@
+import puppeteer from 'puppeteer';
+const DEFAULT_USER_AGENT = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)'
+    + ' AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36';
+const DEFAULT_LAUNCH_ARGS = [
+    '--no-sandbox',
+    '--disable-setuid-sandbox',
+    // What a challenge actually reads: the automation flag is a one-line giveaway, and
+    // Chrome's headless default user agent names itself `HeadlessChrome`.
+    '--disable-blink-features=AutomationControlled'
+];
+const DEFAULT_CHALLENGE_MARKERS = ['Checking your browser'];
+const DEFAULT_CHALLENGE_TIMEOUT_MS = 30000;
+const DEFAULT_NAVIGATION_TIMEOUT_MS = 60000;
+const DEFAULT_WAIT_UNTIL = 'networkidle2';
+const CHALLENGE_POLL_MS = 500;
+/**
+ * A Chrome session that reads pages an HTTP client alone cannot reach.
+ *
+ * Some hosts — every `*.tumblr.com` blog among them — answer any plain request with a 403
+ * carrying a JavaScript challenge, and only serve the real page to whoever runs it. One
+ * tab is kept per origin: the first read of an origin navigates there and waits for the
+ * challenge to clear, and both read modes then reuse that cleared tab, so the cookies it
+ * was granted keep applying.
+ *
+ * The browser starts itself on first use and must be closed by the caller.
+ */
+export class HeadlessBrowser {
+    options;
+    pagesByOrigin = new Map();
+    browser = null;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    /**
+     * Reads one URL as text, starting the browser and clearing the origin's challenge when
+     * this is the first read of that origin.
+     *
+     * @param url - Absolute URL to read.
+     * @param readOptions - Overrides this session's read defaults for this call.
+     * @returns The page's text, or `null` when the URL has no readable origin, or when a
+     * `'served'` read met a response that was not a success. A `'rendered'` read returns
+     * whatever the tab ended up holding, error pages included, since that is the document
+     * the browser was given.
+     * @throws If the browser cannot be started, if a navigation times out, or if an
+     * interstitial never clears, as `challenge-not-cleared`.
+     */
+    async readText(url, readOptions = {}) {
+        let origin;
+        try {
+            origin = new URL(url).origin;
+        }
+        catch {
+            return null;
+        }
+        const resolved = { ...this.options.read, ...readOptions };
+        const page = await this.openOrigin(origin, url, resolved);
+        if (resolved.source !== 'rendered')
+            return await readServedText(page, url);
+        if (page.url() !== url) {
+            await page.goto(url, { waitUntil: resolved.waitUntil ?? DEFAULT_WAIT_UNTIL });
+            await this.waitForChallenge(page);
+        }
+        await wait(resolved.settleMs ?? 0);
+        return await page.content();
+    }
+    /** Closes every tab and the browser itself. Reading again starts a new one. */
+    async close() {
+        const browser = this.browser;
+        this.browser = null;
+        this.pagesByOrigin.clear();
+        await browser?.close();
+    }
+    async openOrigin(origin, entryUrl, readOptions) {
+        const known = this.pagesByOrigin.get(origin);
+        if (known !== undefined)
+            return known;
+        const browser = await this.start();
+        const page = await browser.newPage();
+        this.pagesByOrigin.set(origin, page);
+        page.setDefaultNavigationTimeout(this.options.navigationTimeoutMs ?? DEFAULT_NAVIGATION_TIMEOUT_MS);
+        // A challenge answers 403 until it is solved, so a failed navigation is expected here.
+        await page
+            .goto(entryUrl, { waitUntil: readOptions.waitUntil ?? DEFAULT_WAIT_UNTIL })
+            .catch(() => null);
+        await this.waitForChallenge(page);
+        return page;
+    }
+    async start() {
+        this.browser ??= await puppeteer.launch({
+            headless: true,
+            args: [
+                ...this.options.launchArgs ?? DEFAULT_LAUNCH_ARGS,
+                `--user-agent=${this.options.userAgent ?? DEFAULT_USER_AGENT}`
+            ]
+        });
+        return this.browser;
+    }
+    async waitForChallenge(page) {
+        const markers = this.options.challengeMarkers ?? DEFAULT_CHALLENGE_MARKERS;
+        if (markers.length === 0)
+            return;
+        const deadline = Date.now()
+            + (this.options.challengeTimeoutMs ?? DEFAULT_CHALLENGE_TIMEOUT_MS);
+        while (Date.now() < deadline) {
+            // Reading mid-navigation throws, which only means the challenge is still working.
+            const content = await page.content().catch(() => null);
+            if (content !== null && !markers.some(marker => content.includes(marker)))
+                return;
+            await wait(CHALLENGE_POLL_MS);
+        }
+        throw new Error('challenge-not-cleared');
+    }
+}
+async function readServedText(page, url) {
+    return await page.evaluate(async (target) => {
+        const response = await fetch(target, { credentials: 'include' });
+        if (!response.ok)
+            return null;
+        return await response.text();
+    }, url);
+}
+async function wait(durationMs) {
+    if (durationMs <= 0)
+        return;
+    await new Promise(resolve => { setTimeout(resolve, durationMs); });
+}