@crawlee/utils 4.0.0-beta.13 → 4.0.0-beta.131

package/internals/sitemap.js

@@ -2,29 +2,31 @@ import { createHash } from 'node:crypto';
 import { PassThrough, pipeline, Readable, Transform } from 'node:stream';
 import { StringDecoder } from 'node:string_decoder';
 import { createGunzip } from 'node:zlib';
-import sax from 'sax';
+import { FetchHttpClient } from '@crawlee/http-client';
 import MIMEType from 'whatwg-mimetype';
-import log from '@apify/log';
+import { mergeAsyncIterables } from './iterables.js';
+import { RobotsTxtFile } from './robots.js';
+import { filterUrl } from './url.js';
 class SitemapTxtParser extends Transform {
-    decoder = new StringDecoder('utf8');
-    buffer = '';
+    #decoder = new StringDecoder('utf8');
+    #buffer = '';
     constructor() {
         super({
             readableObjectMode: true,
             transform: (chunk, _encoding, callback) => {
-                this.processBuffer(this.decoder.write(chunk), false);
+                this.processBuffer(this.#decoder.write(chunk), false);
                 callback();
             },
             flush: (callback) => {
-                this.processBuffer(this.decoder.end(), true);
+                this.processBuffer(this.#decoder.end(), true);
                 callback();
             },
         });
     }
     processBuffer(input, finalize) {
-        this.buffer += input;
-        if (finalize || this.buffer.includes('\n')) {
-            const parts = this.buffer
+        this.#buffer += input;
+        if (finalize || this.#buffer.includes('\n')) {
+            const parts = this.#buffer
                 .split('\n')
                 .map((part) => part.trim())
                 .filter((part) => part.length > 0);
@@ -32,101 +34,109 @@ class SitemapTxtParser extends Transform {
                 for (const url of parts) {
                     this.push({ type: 'url', loc: url });
                 }
-                this.buffer = '';
+                this.#buffer = '';
             }
             else if (parts.length > 0) {
                 for (const url of parts.slice(0, -1)) {
                     this.push({ type: 'url', loc: url });
                 }
-                this.buffer = parts.at(-1);
+                this.#buffer = parts.at(-1);
             }
         }
     }
 }
 class SitemapXmlParser extends Transform {
-    decoder = new StringDecoder('utf8');
-    parser = new sax.SAXParser(true);
-    rootTagName;
-    currentTag = undefined;
-    url = {};
-    constructor() {
+    #decoder = new StringDecoder('utf8');
+    #parser;
+    #rootTagName;
+    #currentTag = undefined;
+    #url = {};
+    static async create() {
+        const { SAXParser } = await import('sax');
+        return new SitemapXmlParser(new SAXParser(true));
+    }
+    constructor(parser) {
         super({
             readableObjectMode: true,
             transform: (chunk, _encoding, callback) => {
-                this.parser.write(this.decoder.write(chunk));
+                this.#parser.write(this.#decoder.write(chunk));
                 callback();
             },
             flush: (callback) => {
-                const rest = this.decoder.end();
+                const rest = this.#decoder.end();
                 if (rest.length > 0) {
-                    this.parser.write(rest);
+                    this.#parser.write(rest);
                 }
-                this.parser.end();
+                this.#parser.end();
                 callback();
             },
         });
-        this.parser.onopentag = this.onOpenTag.bind(this);
-        this.parser.onclosetag = this.onCloseTag.bind(this);
-        this.parser.ontext = this.onText.bind(this);
-        this.parser.oncdata = this.onText.bind(this);
-        this.parser.onerror = this.destroy.bind(this);
+        this.#parser = parser;
+        this.#parser.onopentag = this.onOpenTag.bind(this);
+        this.#parser.onclosetag = this.onCloseTag.bind(this);
+        this.#parser.ontext = this.onText.bind(this);
+        this.#parser.oncdata = this.onText.bind(this);
+        this.#parser.onerror = this.destroy.bind(this);
     }
     onOpenTag(node) {
-        if (this.rootTagName !== undefined) {
+        if (this.#rootTagName !== undefined) {
             if (node.name === 'loc' ||
                 node.name === 'lastmod' ||
                 node.name === 'priority' ||
                 node.name === 'changefreq') {
-                this.currentTag = node.name;
+                this.#currentTag = node.name;
             }
         }
         if (node.name === 'urlset') {
-            this.rootTagName = 'urlset';
+            this.#rootTagName = 'urlset';
         }
         if (node.name === 'sitemapindex') {
-            this.rootTagName = 'sitemapindex';
+            this.#rootTagName = 'sitemapindex';
         }
     }
     onCloseTag(name) {
         if (name === 'loc' || name === 'lastmod' || name === 'priority' || name === 'changefreq') {
-            this.currentTag = undefined;
+            this.#currentTag = undefined;
         }
-        if (name === 'url' && this.url.loc !== undefined) {
-            this.push({ type: 'url', ...this.url, loc: this.url.loc });
-            this.url = {};
+        if (name === 'url') {
+            if (this.#url.loc !== undefined) {
+                this.push({ type: 'url', ...this.#url, loc: this.#url.loc });
+            }
+            this.#url = {};
         }
     }
     onText(text) {
-        if (this.currentTag === 'loc') {
-            if (this.rootTagName === 'sitemapindex') {
+        if (this.#currentTag === 'loc') {
+            if (this.#rootTagName === 'sitemapindex') {
                 this.push({ type: 'sitemapUrl', url: text.trim() });
             }
-            if (this.rootTagName === 'urlset') {
-                this.url ??= {};
-                this.url.loc = text.trim();
+            if (this.#rootTagName === 'urlset') {
+                this.#url ??= {};
+                this.#url.loc = text.trim();
             }
         }
         text = text.trim();
-        if (this.currentTag === 'lastmod') {
-            this.url.lastmod = new Date(text);
+        if (this.#currentTag === 'lastmod') {
+            const lastmod = new Date(text);
+            if (!Number.isNaN(lastmod.getTime())) {
+                this.#url.lastmod = lastmod;
+            }
         }
-        if (this.currentTag === 'priority') {
-            this.url.priority = Number(text);
+        if (this.#currentTag === 'priority') {
+            this.#url.priority = Number(text);
         }
-        if (this.currentTag === 'changefreq') {
+        if (this.#currentTag === 'changefreq') {
             if (['always', 'hourly', 'daily', 'weekly', 'monthly', 'yearly', 'never'].includes(text)) {
-                this.url.changefreq = text;
+                this.#url.changefreq = text;
             }
         }
     }
 }
 export async function* parseSitemap(initialSources, proxyUrl, options) {
-    const { gotScraping } = await import('got-scraping');
-    const { fileTypeStream } = await import('file-type');
-    const { emitNestedSitemaps = false, maxDepth = Infinity, sitemapRetries = 3, networkTimeouts } = options ?? {};
+    const { httpClient = new FetchHttpClient(), emitNestedSitemaps = false, maxDepth = Infinity, sitemapRetries = 3, timeoutMillis: timeout = 30000, reportNetworkErrors = true, nestedSitemapFilter, enqueueStrategy = 'same-hostname', logger, } = options ?? {};
     const sources = [...initialSources];
     const visitedSitemapUrls = new Set();
-    const createParser = (contentType = '', url) => {
+    const createParser = async (contentType = '', url) => {
         let mimeType;
         try {
             mimeType = new MIMEType(contentType);
@@ -135,7 +145,7 @@ export async function* parseSitemap(initialSources, proxyUrl, options) {
             mimeType = null;
         }
         if (mimeType?.isXML() || url?.pathname.endsWith('.xml')) {
-            return new SitemapXmlParser();
+            return SitemapXmlParser.create();
         }
         if (mimeType?.essence === 'text/plain' || url?.pathname.endsWith('.txt')) {
             return new SitemapTxtParser();
@@ -145,33 +155,40 @@ export async function* parseSitemap(initialSources, proxyUrl, options) {
     while (sources.length > 0) {
         const source = sources.shift();
         if ((source?.depth ?? 0) > maxDepth) {
-            log.debug(`Skipping sitemap ${source.type === 'url' ? source.url : ''} because it reached max depth ${maxDepth}.`);
             continue;
         }
         let items = null;
+        // Parent URL, parsed once and reused as the origin for the strategy checks below.
+        let sitemapUrl;
         if (source.type === 'url') {
-            const sitemapUrl = new URL(source.url);
+            sitemapUrl = new URL(source.url);
             visitedSitemapUrls.add(sitemapUrl.toString());
             let retriesLeft = sitemapRetries + 1;
             while (retriesLeft-- > 0) {
                 try {
-                    const sitemapStream = await new Promise((resolve, reject) => {
-                        const request = gotScraping.stream({
-                            url: sitemapUrl,
-                            proxyUrl,
+                    let sitemapResponse;
+                    try {
+                        sitemapResponse = await httpClient.sendRequest(new Request(sitemapUrl, {
                             method: 'GET',
-                            timeout: networkTimeouts,
                             headers: {
-                                accept: 'text/plain, application/xhtml+xml, application/xml;q=0.9, */*;q=0.8',
+                                accept: '*/*',
                             },
+                        }), {
+                            proxyUrl,
+                            timeoutMillis: timeout,
                         });
-                        request.on('response', () => resolve(request));
-                        request.on('error', reject);
-                    });
+                    }
+                    catch (error) {
+                        sitemapResponse = null;
+                    }
                     let error = null;
-                    if (sitemapStream.response.statusCode >= 200 && sitemapStream.response.statusCode < 300) {
-                        let contentType = sitemapStream.response.headers['content-type'];
-                        const streamWithType = await fileTypeStream(sitemapStream);
+                    if (sitemapResponse && sitemapResponse.status >= 200 && sitemapResponse.status < 300) {
+                        let contentType = sitemapResponse.headers.get('content-type');
+                        if (sitemapResponse.body === null) {
+                            break;
+                        }
+                        const { fileTypeStream } = await import('file-type');
+                        const streamWithType = await fileTypeStream(Readable.fromWeb(sitemapResponse.body));
                         if (streamWithType.fileType !== undefined) {
                             contentType = streamWithType.fileType.mime;
                         }
@@ -184,43 +201,76 @@ export async function* parseSitemap(initialSources, proxyUrl, options) {
                                 sitemapUrl.pathname = sitemapUrl.pathname.substring(0, sitemapUrl.pathname.length - 3);
                             }
                         }
-                        items = pipeline(streamWithType, isGzipped ? createGunzip() : new PassThrough(), createParser(contentType, sitemapUrl), (e) => {
-                            if (e !== undefined) {
-                                error = e;
+                        items = pipeline(streamWithType, isGzipped ? createGunzip() : new PassThrough(), await createParser(contentType ?? undefined, sitemapUrl), (e) => {
+                            if (e !== undefined && e !== null) {
+                                error = { type: 'parser', error: e };
                             }
                         });
                     }
                     else {
-                        error = new Error(`Failed to fetch sitemap: ${sitemapUrl}, status code: ${sitemapStream.response.statusCode}`);
+                        error = {
+                            type: 'fetch',
+                            error: new Error(`Failed to fetch sitemap: ${sitemapUrl}, status code: ${sitemapResponse?.status}`),
+                        };
                     }
                     if (error !== null) {
-                        throw error;
+                        const shouldIgnoreError = error.type === 'fetch' && !reportNetworkErrors;
+                        if (!shouldIgnoreError) {
+                            throw error.error;
+                        }
+                    }
+                    else {
+                        break;
                     }
-                    break;
                 }
                 catch (e) {
-                    log.warning(`Malformed sitemap content: ${sitemapUrl}, ${retriesLeft === 0 ? 'no retries left.' : 'retrying...'} (${e})`);
+                    logger?.warning(`Malformed sitemap content: ${sitemapUrl}, ${retriesLeft === 0 ? 'no retries left.' : 'retrying...'} (${e})`);
                 }
             }
         }
         else if (source.type === 'raw') {
-            items = pipeline(Readable.from([source.content]), createParser('text/xml'), (error) => {
+            items = pipeline(Readable.from([source.content]), await createParser('text/xml'), (error) => {
                 if (error !== undefined) {
-                    log.warning(`Malformed sitemap content: ${error}`);
+                    logger?.warning(`Malformed sitemap content: ${error}`);
                 }
             });
         }
         if (items === null) {
             continue;
         }
+        // URL entries dropped by the enqueue strategy filter, reported in one warning per sitemap after
+        // the loop (per-entry warnings could flood the log; individual drops are logged at debug level).
+        let droppedUrlEntries = 0;
         for await (const item of items) {
             if (item.type === 'sitemapUrl' && !visitedSitemapUrls.has(item.url)) {
+                if (nestedSitemapFilter && !nestedSitemapFilter(item.url)) {
+                    logger?.debug(`Skipping sitemap ${item.url} due to nestedSitemapFilter.`);
+                    continue;
+                }
+                // Keep only nested sitemaps matching the strategy (and using http(s)) relative to the
+                // parent. Raw string sources have no parent URL, so the check is skipped.
+                if (source.type === 'url') {
+                    const { allowed, reason } = filterUrl(item.url, sitemapUrl, enqueueStrategy);
+                    if (!allowed) {
+                        logger?.warning(`Skipping nested sitemap ${item.url} (parent ${source.url}): ${reason}.`);
+                        continue;
+                    }
+                }
                 sources.push({ type: 'url', url: item.url, depth: (source.depth ?? 0) + 1 });
                 if (emitNestedSitemaps) {
                     yield { loc: item.url, originSitemapUrl: null };
                 }
             }
             if (item.type === 'url') {
+                // Keep only URL entries that match the enqueue strategy relative to the parent (see above).
+                if (source.type === 'url') {
+                    const { allowed, reason } = filterUrl(item.loc, sitemapUrl, enqueueStrategy);
+                    if (!allowed) {
+                        droppedUrlEntries++;
+                        logger?.debug(`Skipping sitemap URL ${item.loc} (parent ${source.url}): ${reason}.`);
+                        continue;
+                    }
+                }
                 yield {
                     ...item,
                     originSitemapUrl: source.type === 'url'
@@ -229,6 +279,9 @@ export async function* parseSitemap(initialSources, proxyUrl, options) {
                 };
             }
         }
+        if (droppedUrlEntries > 0 && source.type === 'url') {
+            logger?.warning(`Skipped ${droppedUrlEntries} URL(s) from sitemap ${source.url} not matching enqueue strategy '${enqueueStrategy}' (or using a non-http(s) scheme). Enable debug logs to see each skipped URL.`);
+        }
     }
 }
 /**
@@ -254,7 +307,7 @@ export class Sitemap {
      * @param url The domain URL to fetch the sitemap for.
      * @param proxyUrl A proxy to be used for fetching the sitemap file.
      */
-    static async tryCommonNames(url, proxyUrl) {
+    static async tryCommonNames(url, proxyUrl, parseSitemapOptions) {
         const sitemapUrls = [];
         const sitemapUrl = new URL(url);
         sitemapUrl.search = '';
@@ -262,7 +315,7 @@ export class Sitemap {
         sitemapUrls.push(sitemapUrl.toString());
         sitemapUrl.pathname = '/sitemap.txt';
         sitemapUrls.push(sitemapUrl.toString());
-        return Sitemap.load(sitemapUrls, proxyUrl);
+        return Sitemap.load(sitemapUrls, proxyUrl, { reportNetworkErrors: false, ...parseSitemapOptions });
     }
     /**
      * Fetch sitemap content from given URL or URLs and return URLs of referenced pages.
@@ -277,8 +330,8 @@ export class Sitemap {
      * @param content XML sitemap content
      * @param proxyUrl URL of a proxy to be used for fetching sitemap contents
      */
-    static async fromXmlString(content, proxyUrl) {
-        return await this.parse([{ type: 'raw', content }], proxyUrl);
+    static async fromXmlString(content, proxyUrl, parseSitemapOptions) {
+        return await this.parse([{ type: 'raw', content }], proxyUrl, parseSitemapOptions);
     }
     static async parse(sources, proxyUrl, parseSitemapOptions) {
         const urls = [];
@@ -287,10 +340,129 @@ export class Sitemap {
                 urls.push(item.loc);
             }
         }
-        catch {
+        catch (e) {
+            parseSitemapOptions?.logger?.warning(`Sitemap.load: Failed to load sitemap, returning empty result. (${e})`);
             return new Sitemap([]);
         }
         return new Sitemap(urls);
     }
 }
-//# sourceMappingURL=sitemap.js.map
+/**
+ * Given a list of URLs, discover related sitemap files for these domains by checking the `robots.txt` file,
+ * the default `sitemap.xml` & `sitemap.txt` files and the URLs themselves.
+ * @param `urls` The list of URLs to discover sitemaps for.
+ * @param `options` Options for sitemap discovery
+ * @returns An async iterable with the discovered sitemap URLs.
+ */
+export async function* discoverValidSitemaps(urls, options = {}) {
+    const { proxyUrl, timeoutMillis = 60_000, signal: externalSignal, requestTimeoutMillis = 20_000, httpClient = new FetchHttpClient(), logger, } = options;
+    const controller = new AbortController();
+    const timeoutHandle = setTimeout(() => controller.abort(), timeoutMillis);
+    const onExternalAbort = () => controller.abort();
+    if (externalSignal) {
+        if (externalSignal.aborted) {
+            controller.abort();
+        }
+        else {
+            externalSignal.addEventListener('abort', onExternalAbort, { once: true });
+        }
+    }
+    const signal = controller.signal;
+    const sitemapUrls = new Set();
+    const addSitemapUrl = (url) => {
+        const sizeBefore = sitemapUrls.size;
+        sitemapUrls.add(url);
+        if (sitemapUrls.size > sizeBefore) {
+            return url;
+        }
+        return undefined;
+    };
+    const urlExists = async (url) => {
+        if (!httpClient) {
+            return false;
+        }
+        try {
+            const response = await httpClient.sendRequest(new Request(url, { method: 'HEAD' }), {
+                proxyUrl,
+                timeoutMillis: requestTimeoutMillis,
+                signal,
+            });
+            return response.status >= 200 && response.status < 400;
+        }
+        catch {
+            return false;
+        }
+    };
+    const discoverSitemapsForDomainUrls = async function* (hostname, domainUrls) {
+        if (!hostname) {
+            return;
+        }
+        try {
+            const robotsFile = await RobotsTxtFile.find(domainUrls[0], {
+                proxyUrl,
+                timeoutMillis: requestTimeoutMillis,
+                signal,
+                httpClient,
+                logger,
+            });
+            // Surface all referenced sitemaps, including cross-host; scoping happens at load time.
+            for (const sitemapUrl of robotsFile.getSitemaps({ enqueueStrategy: 'all' })) {
+                if (addSitemapUrl(sitemapUrl)) {
+                    yield sitemapUrl;
+                }
+            }
+        }
+        catch (err) {
+            logger?.warning(`Failed to fetch robots.txt file for ${hostname}`, { error: err });
+        }
+        const sitemapUrl = domainUrls.find((url) => /sitemap(?:_index)?\.(?:xml|txt)(?:\.gz)?$/i.test(url));
+        if (sitemapUrl !== undefined) {
+            if (addSitemapUrl(sitemapUrl)) {
+                yield sitemapUrl;
+            }
+        }
+        else {
+            const firstUrl = new URL(domainUrls[0]);
+            const possibleSitemapPathnames = ['/sitemap.xml', '/sitemap.txt', '/sitemap_index.xml'];
+            const candidateSitemapUrls = possibleSitemapPathnames.map((pathname) => {
+                firstUrl.pathname = pathname;
+                return firstUrl.toString();
+            });
+            const candidateResults = await Promise.allSettled(candidateSitemapUrls.map(urlExists));
+            for (const [index, result] of candidateResults.entries()) {
+                const candidateSitemapUrl = candidateSitemapUrls[index];
+                if (result.status === 'fulfilled') {
+                    if (result.value && addSitemapUrl(candidateSitemapUrl)) {
+                        yield candidateSitemapUrl;
+                    }
+                }
+                else {
+                    logger?.debug(`Failed to check sitemap candidate ${candidateSitemapUrl} for ${hostname}`, {
+                        error: result.reason,
+                    });
+                }
+            }
+        }
+    };
+    const groupedUrls = urls.reduce((acc, url) => {
+        const hostname = new URL(url)?.hostname ?? '';
+        acc[hostname] ??= [];
+        acc[hostname].push(url);
+        return acc;
+    }, {});
+    const iterables = Object.entries(groupedUrls).map(([hostname, domainUrls]) => discoverSitemapsForDomainUrls(hostname, domainUrls));
+    const discoveredUrls = new Set();
+    try {
+        for await (const url of mergeAsyncIterables(...iterables)) {
+            if (discoveredUrls.has(url)) {
+                continue;
+            }
+            discoveredUrls.add(url);
+            yield url;
+        }
+    }
+    finally {
+        clearTimeout(timeoutHandle);
+        externalSignal?.removeEventListener('abort', onExternalAbort);
+    }
+}

package/internals/social.d.ts

@@ -488,5 +488,4 @@ export declare const DISCORD_REGEX_GLOBAL: RegExp;
  *   so that the caller doesn't need to parse the HTML document again, if needed.
  * @return An object with the social handles.
  */
-export declare function parseHandlesFromHtml(html: string, data?: Record<string, unknown> | null): SocialHandles;
-//# sourceMappingURL=social.d.ts.map
+export declare function parseHandlesFromHtml(html: string, data?: Record<string, unknown> | null): Promise<SocialHandles>;

package/internals/social.js

@@ -1,7 +1,9 @@
-import * as cheerio from 'cheerio';
 import { htmlToText } from './cheerio.js';
 // Regex inspired by https://zapier.com/blog/extract-links-email-phone-regex/
-const EMAIL_REGEX_STRING = '(?:[a-z0-9!#$%&\'*+/=?^_`{|}~-]+(?:\\.[a-z0-9!#$%&\'*+/=?^_`{|}~-]+)*|"(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\\\\[\x01-\x09\x0b\x0c\x0e-\x7f])*")@(?:(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\\.)+[a-z0-9](?:[a-z0-9-]*[a-z0-9])?|\\[(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?|[a-z0-9-]*[a-z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]|\\\\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\\])';
+// The dot-atom local part and domain labels use RFC 5321 length bounds ({1,64}, {0,62})
+// instead of unbounded quantifiers to avoid quadratic backtracking (ReDoS) on long
+// dotted or hyphenated inputs, e.g. text scraped by parseHandlesFromHtml().
+const EMAIL_REGEX_STRING = '(?:[a-z0-9!#$%&\'*+/=?^_`{|}~-]{1,64}(?:\\.[a-z0-9!#$%&\'*+/=?^_`{|}~-]{1,64}){0,32}|"(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\\\\[\x01-\x09\x0b\x0c\x0e-\x7f])*")@(?:(?:[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?\\.)+[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?|\\[(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?|[a-z0-9-]*[a-z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]|\\\\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\\])';
 /**
  * Regular expression to exactly match a single email address.
  * It has the following form: `/^...$/i`.
@@ -587,7 +589,8 @@ export const DISCORD_REGEX_GLOBAL = new RegExp(DISCORD_REGEX_STRING, 'ig');
  *   so that the caller doesn't need to parse the HTML document again, if needed.
  * @return An object with the social handles.
  */
-export function parseHandlesFromHtml(html, data = null) {
+export async function parseHandlesFromHtml(html, data = null) {
+    const cheerio = await import('cheerio');
     const result = {
         emails: [],
         phones: [],
@@ -606,7 +609,7 @@ export function parseHandlesFromHtml(html, data = null) {
     const $ = cheerio.load(html, { xml: { decodeEntities: true } });
     if (data)
         data.$ = $;
-    const text = htmlToText($);
+    const text = await htmlToText($);
     if (data)
         data.text = text;
     // NOTE: we need to parse each text separately, orherwise we might concatenate unrelated texts
@@ -644,4 +647,3 @@ export function parseHandlesFromHtml(html, data = null) {
     }
     return result;
 }
-//# sourceMappingURL=social.js.map

package/internals/url.d.ts

@@ -1,4 +1,73 @@
-export type SearchParams = string | URLSearchParams | Record<string, string | number | boolean | null | undefined>;
+import type { SearchParams } from '@crawlee/types';
+/**
+ * The different enqueueing strategies available.
+ *
+ * Depending on the strategy you select, we will only check certain parts of the URLs found. Here is a diagram of each URL part and their name:
+ *
+ * ```md
+ * Protocol          Domain
+ * ┌────┐          ┌─────────┐
+ * https://example.crawlee.dev/...
+ * │       └─────────────────┤
+ * │             Hostname    │
+ * │                         │
+ * └─────────────────────────┘
+ *          Origin
+ *```
+ *
+ * - The `Protocol` is usually `http` or `https`
+ * - The `Domain` represents the path without any possible subdomains to a website. For example, `crawlee.dev` is the domain of `https://example.crawlee.dev/`
+ * - The `Hostname` is the full path to a website, including any subdomains. For example, `example.crawlee.dev` is the hostname of `https://example.crawlee.dev/`
+ * - The `Origin` is the combination of the `Protocol` and `Hostname`. For example, `https://example.crawlee.dev` is the origin of `https://example.crawlee.dev/`
+ */
+export declare enum EnqueueStrategy {
+    /**
+     * Matches any URLs found
+     */
+    All = "all",
+    /**
+     * Matches any URLs that have the same hostname.
+     * For example, `https://wow.example.com/hello` will be matched for a base url of `https://wow.example.com/`, but
+     * `https://example.com/hello` will not be matched.
+     *
+     * > This strategy will match both `http` and `https` protocols regardless of the base URL protocol.
+     */
+    SameHostname = "same-hostname",
+    /**
+     * Matches any URLs that have the same domain as the base URL.
+     * For example, `https://wow.an.example.com` and `https://example.com` will both be matched for a base url of
+     * `https://example.com`.
+     *
+     * > This strategy will match both `http` and `https` protocols regardless of the base URL protocol.
+     */
+    SameDomain = "same-domain",
+    /**
+     * Matches any URLs that have the same hostname and protocol.
+     * For example, `https://wow.example.com/hello` will be matched for a base url of `https://wow.example.com/`, but
+     * `http://wow.example.com/hello` will not be matched.
+     *
+     * > This strategy will ensure the protocol of the base URL is the same as the protocol of the URL to be enqueued.
+     */
+    SameOrigin = "same-origin"
+}
+/** Reusable suffix for log messages explaining why a non-`http(s)` URL was rejected. */
+export declare const UNSUPPORTED_SCHEME_MESSAGE = "unsupported URL scheme (only http and https are allowed)";
+/**
+ * Check whether `target` matches `origin` under the given enqueue `strategy`. The URL scheme is not
+ * considered here (use {@link filterUrl} for the combined scheme + strategy check).
+ *
+ * The `enqueueLinks` implementation in `@crawlee/core` matches the same strategies via glob patterns
+ * (see `packages/core/src/enqueue_links/enqueue_links.ts`) — keep the two in sync when changing either.
+ */
+export declare function matchesEnqueueStrategy(strategy: EnqueueStrategy | `${EnqueueStrategy}`, target: URL, origin: URL): boolean;
+/**
+ * Check whether `target` may be enqueued under `strategy` relative to `origin`: it must use an `http(s)`
+ * scheme and match the strategy. On rejection, `reason` is a human-readable message for log output.
+ */
+export declare function filterUrl(target: string | URL, origin: string | URL, strategy: EnqueueStrategy | `${EnqueueStrategy}`): {
+    allowed: boolean;
+    reason?: string;
+};
 /**
  * Appends search (query string) parameters to a URL, replacing the original value (if any).
  *
@@ -7,4 +76,3 @@ export type SearchParams = string | URLSearchParams | Record<string, string | nu
  * @internal
  */
 export declare function applySearchParams(url: URL, searchParams: SearchParams | undefined): void;
-//# sourceMappingURL=url.d.ts.map