@wenathlan/saddle 1.8.17 → 2.0.2

package/docs/plans/16.research.crawling.md

@@ -1,1417 +0,0 @@
-# Pesquisa: Web Crawling Patterns (2026)
-
-## Table of Contents
-
-- [Visão Geral](#visão-geral)
-- [BFS vs DFS Crawling](#bfs-vs-dfs-crawling)
-- [robots.txt Parsing](#robotstxt-parsing)
-- [Sitemap Parsing](#sitemap-parsing)
-- [URL Frontier com Prioridade](#url-frontier-com-prioridade)
-- [URL Normalization](#url-normalization)
-- [Depth-Limited Crawling](#depth-limited-crawling)
-- [Domain-Specific Crawl Rules](#domain-specific-crawl-rules)
-- [Canonical URLs e Redirect Handling](#canonical-urls-e-redirect-handling)
-- [Código Completo](#código-completo)
-
----
-
-## Visão Geral
-
-Web crawling patterns define como um crawler descobre, prioriza e acessa URLs em um site. A escolha entre BFS (Breadth-First Search) e DFS (Depth-First Search), combined com normalização de URLs, respeito a robots.txt, e limitação de profundidade, determina a eficiência e robustez do crawler.
-
-### Bibliotecas Principais (2026)
-
-| Biblioteca | Versão | Uso |
-|---|---|---|
-| `crawlee` | 3.x | Framework completo de crawling |
-| `robots-parser` | 3.0.1 | Parsing de robots.txt (RFC 9309) |
-| `sitemapper` | 4.1.6 | Parsing de sitemaps XML |
-| `p-queue` | 9.3.0 | Fila com prioridade |
-| `normalize-url` | 9.0.0 | Normalização de URLs |
-| `ufo` | latest | Normalização leve de URLs |
-
----
-
-## BFS vs DFS Crawling
-
-### Breadth-First Search (BFS)
-
-BFS visita todas as URLs de um nível antes de descer para o próximo nível. É o padrão em Crawlee porque garante cobertura uniforme e evita ficar preso em sub-árvores profundas.
-
-```
-Level 0:  [https://example.com]
-              │
-Level 1:  [A] [B] [C]
-              │       │
-Level 2:  [D] [E] [F] [G]
-```
-
-**Por que BFS é o padrão:**
-- Cobertura uniforme de todas as seções do site
-- Menor risco de ficar preso em páginas infinitas
-- Distribuição mais equilibrada de carga
-- Mais previsível para controle de taxa
-
-### Depth-First Search (DFS)
-
-DFS explora um caminho completo antes de voltar. Útil para crawl de árvores de navegação, categorias, ou quando se quer explorar um sub-site completamente.
-
-```
-Start → [A] → [D] → [H] → backtrack → [E] → backtrack → [B] → [F] → ...
-```
-
-**Quando usar DFS:**
-- Crawl de documentação hierárquica
-- Exploração de categorias/subcategorias
-- Quando a prioridade é profundidade sobre amplitude
-
-### Crawlee: RequestQueue
-
-O `RequestQueue` do Crawlee é a fila persistente que gerencia URLs. Por padrão, opera em BFS. A ordem de inserção determina a ordem de processamento.
-
-```ts
-import { RequestQueue, PlaywrightCrawler } from 'crawlee';
-
-const requestQueue = await RequestQueue.open('my-queue');
-
-// Inserir URLs — ordem de inserção = ordem de processamento (BFS)
-await requestQueue.addRequest({ url: 'https://example.com' });        // Nível 0
-await requestQueue.addRequest({ url: 'https://example.com/a' });      // Nível 1
-await requestQueue.addRequest({ url: 'https://example.com/b' });      // Nível 1
-await requestQueue.addRequest({ url: 'https://example.com/a/d' });    // Nível 2
-await requestQueue.addRequest({ url: 'https://example.com/a/e' });    // Nível 2
-```
-
-### Crawlee: enqueueLinks
-
-`enqueueLinks()` extrai e enfileira links da página atual. Por padrão usa BFS (insere no final da fila).
-
-```ts
-import { PlaywrightCrawler } from 'crawlee';
-
-const crawler = new PlaywrightCrawler({
-    requestQueue,
-    async requestHandler({ page, enqueueLinks }) {
-        // BFS padrão — links vão para o FINAL da fila
-        await enqueueLinks();
-    },
-});
-
-await crawler.run(['https://example.com']);
-```
-
-### DFS com forefront: true
-
-Para DFS, use `forefront: true` na `enqueueLinks()`. Isso insere os novos links no INÍCIO da fila, fazendo o crawler explorar profundidade antes de largura.
-
-```ts
-const crawler = new PlaywrightCrawler({
-    requestQueue,
-    async requestHandler({ page, enqueueLinks }) {
-        // DFS — links vão para o INÍCIO da fila
-        await enqueueLinks({ forefront: true });
-    },
-});
-
-await crawler.run(['https://example.com']);
-```
-
-### Comparação BFS vs DFS
-
-| Característica | BFS | DFS |
-|---|---|---|
-| Cobertura | Uniforme, amplo | Profundo, focado |
-| Risco de loop | Baixo | Alto |
-| Uso de memória | Médio (muitas URLs pendentes) | Baixo (poucas URLs pendentes) |
-| Velocidade de descoberta | Lenta (explora tudo) | Rápida (explora fundo) |
-| Uso ideal | Sites grandes, e-commerce | Documentação, árvores |
-| Crawlee padrão | `enqueueLinks()` | `enqueueLinks({ forefront: true })` |
-
----
-
-## robots.txt Parsing
-
-### robots-parser 3.0.1
-
-`robots-parser` é a biblioteca mais completa para parsing de robots.txt. Versão 3.0.1 é compatível com RFC 9309 (a versão atual do padrão).
-
-**Características RFC 9309:**
-- Suporte a `User-agent`, `Allow`, `Disallow`, `Crawl-delay`, `Sitemap`
-- Suporte a `*` como curinga no User-agent
-- Suporte a `$` como curinga no final de Allow/Disallow
-- Suporte a linhas de comment (`#`)
-
-```ts
-import robotsParser from 'robots-parser';
-
-const robotsTxt = `
-User-agent: *
-Disallow: /admin/
-Disallow: /private/
-Allow: /admin/dashboard
-Crawl-delay: 2
-Sitemap: https://example.com/sitemap.xml
-
-User-agent: Googlebot
-Allow: /
-`;
-
-const robots = robotsParser('https://example.com/robots.txt', robotsTxt);
-
-// Verificar se um URL é permitido
-const isAllowed = robots.isAllowed('https://example.com/page');
-// → true
-
-const isDisallowed = robots.isAllowed('https://example.com/admin/settings');
-// → false
-
-// Obter crawl-delay
-const delay = robots.getCrawlDelay('Googlebot');
-// → undefined (não definido para Googlebot)
-
-// Obter Sitemap
-const sitemaps = robots.getSitemaps();
-// → ['https://example.com/sitemap.xml']
-
-// Obter Allowed/Disallow para um user-agent específico
-const rules = robots.getDisallowedPaths('*');
-// → ['/admin/', '/private/']
-```
-
-### Crawlee: RobotsTxtFile
-
-Crawlee tem suporte built-in a robots.txt via `RobotsTxtFile`. Ele é integrado automaticamente ao crawler, respeitando regras.
-
-```ts
-import { RobotsTxtFile } from 'crawlee';
-
-// Crawlee respeita robots.txt automaticamente
-const crawler = new PlaywrightCrawler({
-    // robots.txt é checado antes de cada request
-    // URLs bloqueadas são ignoradas silenciosamente
-});
-
-// Forçar desabilitação (não recomendado)
-const crawler = new PlaywrightCrawler({
-    // NOTA: Não há opção direta para desabilitar robots.txt check
-    // Robots.txt é sempre respeitado pelo Crawlee
-});
-```
-
-### Parsing Manual com robots-parser
-
-Para controle total, use `robots-parser` diretamente:
-
-```ts
-import robotsParser from 'robots-parser';
-import { gotScraping } from 'got-scraping';
-
-async function checkRobotsTxt(url: string, userAgent = '*'): Promise<{
-    allowed: boolean;
-    crawlDelay: number | null;
-    sitemaps: string[];
-}> {
-    const parsedUrl = new URL(url);
-    const robotsUrl = `${parsedUrl.origin}/robots.txt`;
-
-    const response = await gotScraping(robotsUrl);
-    const robots = robotsParser(robotsUrl, response.body);
-
-    return {
-        allowed: robots.isAllowed(url, userAgent) ?? true,
-        crawlDelay: robots.getCrawlDelay(userAgent) ?? null,
-        sitemaps: robots.getSitemaps() ?? [],
-    };
-}
-
-// Usar
-const result = await checkRobotsTxt('https://example.com/page');
-if (!result.allowed) {
-    console.log('URL bloqueada por robots.txt');
-    if (result.crawlDelay) {
-        console.log(`Aguardar ${result.crawlDelay} segundos`);
-    }
-}
-```
-
-### Rate Limiting Baseado em Crawl-Delay
-
-```ts
-function getCrawlDelayMs(robots: ReturnType<typeof robotsParser>, userAgent: string): number {
-    const delay = robots.getCrawlDelay(userAgent);
-    if (delay === null || delay === undefined) return 1000; // Default 1s
-    return delay * 1000;
-}
-
-// Usar no crawler
-const crawler = new PlaywrightCrawler({
-    async requestHandler({ page, enqueueLinks }) {
-        const robots = robotsParser('https://example.com/robots.txt', robotsContent);
-        const delayMs = getCrawlDelayMs(robots, '*');
-
-        // Aplicar delay entre requests
-        await new Promise(resolve => setTimeout(resolve, delayMs));
-
-        // ... processar página
-    },
-});
-```
-
----
-
-## Sitemap Parsing
-
-### sitemapper 4.1.6
-
-`sitemapper` é a biblioteca mais rápida para parsing de sitemaps XML. Suporta sitemaps com milhões de URLs.
-
-**Características:**
-- Parsing streaming (não carrega tudo na memória)
-- Suporte a sitemap index (sitemaps que referenciam outros sitemaps)
-- Tratamento de erros robusto
-
-```ts
-import { Sitemapper } from 'sitemapper';
-
-const sitemapper = new Sitemapper({
-    timeout: 15000,
-    url: 'https://example.com/sitemap.xml',
-});
-
-const { sites } = await sitemapper.fetch();
-console.log(sites);
-// → ['https://example.com/', 'https://example.com/page1', ...]
-```
-
-### Crawlee RobotsTxtFile.parseUrlsFromSitemaps()
-
-Crawlee pode extrair URLs de sitemaps referenciados no robots.txt:
-
-```ts
-import { RobotsTxtFile } from 'crawlee';
-
-const robotsContent = `
-User-agent: *
-Disallow: /admin/
-Sitemap: https://example.com/sitemap.xml
-Sitemap: https://example.com/sitemap-products.xml
-`;
-
-const robots = RobotsTxtFile.parse(robotsContent);
-const sitemapUrls = robots.getSitemaps();
-// → ['https://example.com/sitemap.xml', 'https://example.com/sitemap-products.xml']
-
-// Para cada sitemap, usar sitemapper para extrair URLs
-import { Sitemapper } from 'sitemapper';
-
-const allUrls: string[] = [];
-for (const sitemapUrl of sitemapUrls) {
-    const sitemapper = new Sitemapper({ url: sitemapUrl });
-    const { sites } = await sitemapper.fetch();
-    allUrls.push(...sites);
-}
-
-console.log(`Encontradas ${allUrls.length} URLs em sitemaps`);
-```
-
-### Parsing Combinado: robots.txt + sitemaps
-
-```ts
-import robotsParser from 'robots-parser';
-import { Sitemapper } from 'sitemapper';
-import { gotScraping } from 'got-scraping';
-
-async function discoverUrlsFromSitemaps(
-    baseUrl: string,
-): Promise<{ urls: string[]; robots: ReturnType<typeof robotsParser> }> {
-    const parsedUrl = new URL(baseUrl);
-    const robotsUrl = `${parsedUrl.origin}/robots.txt`;
-
-    // 1. Buscar e parsear robots.txt
-    const robotsResponse = await gotScraping(robotsUrl);
-    const robots = robotsParser(robotsUrl, robotsResponse.body);
-
-    // 2. Extrair URLs de sitemaps
-    const sitemapUrls = robots.getSitemaps() ?? [];
-    const discoveredUrls: string[] = [];
-
-    for (const sitemapUrl of sitemapUrls) {
-        try {
-            const sitemapper = new Sitemapper({
-                url: sitemapUrl,
-                timeout: 30000,
-            });
-            const { sites } = await sitemapper.fetch();
-            discoveredUrls.push(...sites);
-        } catch (error) {
-            console.error(`Erro ao parse sitemap ${sitemapUrl}:`, error);
-        }
-    }
-
-    // 3. Filtrar por robots.txt
-    const allowedUrls = discoveredUrls.filter(url => robots.isAllowed(url) ?? true);
-
-    return { urls: allowedUrls, robots };
-}
-
-const { urls } = await discoverUrlsFromSitemaps('https://example.com');
-console.log(`${urls.length} URLs permitidas por robots.txt`);
-```
-
-### Sitemap Index com Muitas URLs
-
-```ts
-// Para sitemaps muito grandes, usar streaming
-import { Sitemapper } from 'sitemapper';
-
-const sitemapper = new Sitemapper({
-    url: 'https://example.com/sitemap.xml',
-    timeout: 60000, // 60s para sitemaps grandes
-});
-
-// Processar em lotes para memória
-const { sites } = await sitemapper.fetch();
-const batchSize = 1000;
-
-for (let i = 0; i < sites.length; i += batchSize) {
-    const batch = sites.slice(i, i + batchSize);
-    // Processar batch
-    console.log(`Processando batch ${Math.floor(i / batchSize) + 1}: ${batch.length} URLs`);
-}
-```
-
----
-
-## URL Frontier com Prioridade
-
-### p-queue 9.3.0
-
-`p-queue` é a fila com prioridade mais popular no Node.js. Permite controle fino de concorrência e prioridade.
-
-**Características:**
-- Prioridade 1-10 (1 = mais alta, 10 = mais baixa)
-- Controle de concorrência (limite de workers)
-- Intervalos entre requests (rate limiting)
-- Timeout por item
-- Persistência (pode ser combinada com storage)
-
-```ts
-import PQueue from 'p-queue';
-
-const queue = new PQueue({
-    concurrency: 5,          // 5 requests simultâneos
-    intervalCap: 10,         // Máximo 10 requests por intervalo
-    interval: 1000,          // 1 segundo entre intervalos
-    timeout: 30000,          // Timeout de 30s por request
-});
-
-// Prioridade: 1 = mais alta, 10 = mais baixa
-queue.add(() => fetch('https://example.com'), { priority: 1 });   // Alta
-queue.add(() => fetch('https://example.com/a'), { priority: 5 }); // Média
-queue.add(() => fetch('https://example.com/b'), { priority: 10 }); // Baixa
-```
-
-### microfrontier
-
-`microfrontier` é uma alternativa leve para frontiers de URL. Oferece persistência em disco e controle de prioridade.
-
-```ts
-import { Microfrontier } from 'microfrontier';
-
-const frontier = new Microfrontier({
-    storage: './frontier-storage',
-    maxConcurrent: 5,
-});
-
-// Adicionar URLs com prioridade
-frontier.push({ url: 'https://example.com', priority: 1 });
-frontier.push({ url: 'https://example.com/a', priority: 5 });
-
-// Pegar próxima URL
-const next = frontier.shift();
-```
-
-### Frontier com p-queue para Crawlee
-
-```ts
-import PQueue from 'p-queue';
-import { PlaywrightCrawler } from 'crawlee';
-
-const queue = new PQueue({ concurrency: 3, intervalCap: 5, interval: 2000 });
-
-const crawler = new PlaywrightCrawler({
-    maxConcurrency: 3,
-    requestHandlerTimeoutSecs: 30,
-    async requestHandler({ page, enqueueLinks }) {
-        // Extrair e classificar links
-        const links = await page.$$eval('a[href]', anchors =>
-            anchors.map(a => ({
-                url: a.href,
-                priority: a.closest('nav') ? 1 :     // Navegação = alta
-                         a.closest('article') ? 3 :  // Artigo = média
-                         a.closest('footer') ? 8 :   // Footer = baixa
-                         5                            // Default
-            }))
-        );
-
-        // Adicionar com prioridade
-        await queue.addAll(
-            links.map(link => async () => {
-                await page.goto(link.url);
-                // Processar...
-            }),
-            { priority: link.priority }
-        );
-    },
-});
-```
-
-### Rate Limiting por Domínio
-
-```ts
-import PQueue from 'p-queue';
-
-// Filas separadas por domínio
-const domainQueues = new Map<string, PQueue>();
-
-function getQueueForDomain(domain: string): PQueue {
-    if (!domainQueues.has(domain)) {
-        domainQueues.set(domain, new PQueue({
-            concurrency: 2,
-            intervalCap: 3,
-            interval: 5000, // 3 requests a cada 5 segundos por domínio
-        }));
-    }
-    return domainQueues.get(domain)!;
-}
-
-// Usar
-const domain = new URL(url).hostname;
-const queue = getQueueForDomain(domain);
-await queue.add(() => fetchAndProcess(url));
-```
-
----
-
-## URL Normalization
-
-### normalize-url 9.0.0
-
-`normalize-url` é a biblioteca mais completa para normalização de URLs. Remove tracking params, sorting query strings, e muito mais.
-
-**Características:**
-- Remove `utm_*`, `fbclid`, `gclid` e outros tracking params
-- Sorting de query string
-- Conversão de protocolo
-- Remoção de trailing slashes
-- Normalização de host (lowercase)
-
-```ts
-import normalizeUrl from 'normalize-url';
-
-// Remover tracking params
-normalizeUrl('https://example.com/page?utm_source=google&utm_medium=cpc&id=123');
-// → 'https://example.com/page?id=123'
-
-// Sorting de query
-normalizeUrl('https://example.com/page?z=1&a=2&m=3');
-// → 'https://example.com/page?a=2&m=3&z=1'
-
-// Normalização completa
-normalizeUrl('https://Example.COM/Page/?id=123#section', {
-    sortQueryParams: true,
-    removeTrailingSlash: true,
-    removeExplicitPort: true,
-    stripWWW: true,
-    stripHash: true,
-    removeDuplicateSlash: true,
-});
-// → 'https://example.com/Page?id=123'
-
-// Configuração customizada
-normalizeUrl('https://example.com/page', {
-    protocols: ['https'],
-    forceHttp: false,
-    forceHttps: true,
-    stripAuthentication: true,
-    stripWWW: true,
-    removeTrailingSlash: true,
-    removeSingleDotSlash: true,
-    sortQueryParams: true,
-    removeDirectoryIndex: true,
-});
-```
-
-### Tracking Parameters Comuns para Remoção
-
-```ts
-const TRACKING_PARAMS = new Set([
-    // Google Analytics
-    'utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',
-    'utm_id', 'utm_cid', 'utm_reader', 'utm_name', 'utm_social',
-    'utm_social-type', 'utm_internal',
-    // Google Ads
-    'gclid', 'gclsrc', 'dclid', 'gbraid', 'wbraid',
-    // Facebook
-    'fbclid', 'fb_action_ids', 'fb_action_types', 'fb_ref', 'fb_source',
-    // Microsoft
-    'msclkid', 'mc_cid', 'mc_eid',
-    // Twitter
-    'twclid',
-    // HubSpot
-    'hsa_cam', 'hsa_grp', 'hsa_mt', 'hsa_src', 'hsa_ad', 'hsa_acc',
-    'hsa_net', 'hsa_ver', 'hsa_la', 'hsa_ol', 'hsa_kw', 'hsa_target',
-    'hsa addTarget', 'hsa_src_campaign', 'hsa_src_ad',
-    // Outros
-    'ref', 'source', 'medium', 'campaign', 'content', 'term',
-    'spm', 'from', 'share_id',
-]);
-
-function normalizeForDedup(url: string): string {
-    const parsed = new URL(url);
-
-    // Remove tracking params
-    const params = [...parsed.searchParams.entries()]
-        .filter(([key]) => !TRACKING_PARAMS.has(key.toLowerCase()));
-
-    // Sort params
-    params.sort((a, b) => a[0].localeCompare(b[0]));
-
-    // Reconstruir URL
-    parsed.search = params.length > 0
-        ? new URLSearchParams(params).toString()
-        : '';
-
-    // Normalizar
-    return normalizeUrl(parsed.toString(), {
-        sortQueryParams: true,
-        removeTrailingSlash: true,
-        stripWWW: true,
-        stripHash: true,
-    });
-}
-
-// Resultados
-normalizeForDedup('https://example.com/page?utm_source=google&id=123');
-// → 'https://example.com/page?id=123'
-
-normalizeForDedup('https://www.example.com/page/?utm_campaign=test#section');
-// → 'https://example.com/page'
-```
-
-### url-normalize (Alternativa)
-
-```ts
-import { normalize } from 'url-normalize';
-
-const normalized = normalize('https://example.com/./page/../page?id=123');
-// → 'https://example.com/page?id=123'
-```
-
-### ufo (Alternativa Leve)
-
-```ts
-import { normalizeURL, withQuery } from 'ufo';
-
-const normalized = normalizeURL('https://example.com/page/?id=123');
-// → 'https://example.com/page?id=123'
-```
-
-### Deduplicação de URLs Normalizadas
-
-```ts
-import normalizeUrl from 'normalize-url';
-
-class UrlDeduplicator {
-    private seen = new Set<string>();
-
-    isUnique(url: string): boolean {
-        const normalized = normalizeUrl(url, {
-            sortQueryParams: true,
-            removeTrailingSlash: true,
-            stripWWW: true,
-            stripHash: true,
-        });
-
-        if (this.seen.has(normalized)) {
-            return false;
-        }
-
-        this.seen.add(normalized);
-        return true;
-    }
-
-    get size(): number {
-        return this.seen.size;
-    }
-
-    clear(): void {
-        this.seen.clear();
-    }
-}
-
-// Usar no crawler
-const dedup = new UrlDeduplicator();
-const urls = [
-    'https://example.com/page?utm_source=google',
-    'https://www.example.com/page/',
-    'https://example.com/page#section',
-    'https://example.com/page?id=123',
-];
-
-const unique = urls.filter(url => dedup.isUnique(url));
-// → ['https://example.com/page?utm_source=google'] (primeira única)
-```
-
----
-
-## Depth-Limited Crawling
-
-### Crawlee maxCrawlDepth
-
-`maxCrawlDepth` controla a profundidade máxima do crawl. A página inicial tem profundidade 0, links dela têm profundidade 1, e assim por diante.
-
-```ts
-import { PlaywrightCrawler } from 'crawlee';
-
-const crawler = new PlaywrightCrawler({
-    maxCrawlDepth: 3,  // Máximo 3 níveis de profundidade
-    requestHandlerTimeoutSecs: 30,
-    async requestHandler({ page, enqueueLinks, request }) {
-        const depth = request.userData?.depth ?? 0;
-        console.log(`Processando: ${request.url} (profundidade: ${depth})`);
-
-        // Só enfileirar se não atingiu o limite
-        if (depth < 3) {
-            await enqueueLinks({
-                userData: { depth: depth + 1 },
-            });
-        }
-    },
-});
-
-await crawler.run(['https://example.com']);
-```
-
-### Controle de Profundidade Manual
-
-```ts
-import { PlaywrightCrawler } from 'crawlee';
-
-interface CrawlState {
-    url: string;
-    depth: number;
-    parent: string | null;
-}
-
-const MAX_DEPTH = 3;
-
-const crawler = new PlaywrightCrawler({
-    requestHandlerTimeoutSecs: 30,
-    async requestHandler({ page, enqueueLinks, request }) {
-        const state: CrawlState = request.userData ?? { url: request.url, depth: 0, parent: null };
-
-        console.log(`${'  '.repeat(state.depth)}[${state.depth}] ${request.url}`);
-
-        // Processar página...
-
-        // Enfileirar com controle de profundidade
-        if (state.depth < MAX_DEPTH) {
-            const links = await page.$$eval('a[href]', anchors =>
-                anchors.map(a => a.href)
-            );
-
-            // Filtrar links internos
-            const internalLinks = links.filter(link => {
-                try {
-                    return new URL(link).hostname === new URL(request.url).hostname;
-                } catch {
-                    return false;
-                }
-            });
-
-            // Enfileirar com profundidade incrementada
-            await enqueueLinks({
-                userData: internalLinks.map(link => ({
-                    url: link,
-                    depth: state.depth + 1,
-                    parent: request.url,
-                })),
-            });
-        }
-    },
-});
-
-await crawler.run(['https://example.com']);
-```
-
-### Profundidade por Seção
-
-```ts
-// Profundidade diferente por seção do site
-function getMaxDepthForPath(pathname: string): number {
-    if (pathname.startsWith('/docs')) return 5;     // Docs: mais profundo
-    if (pathname.startsWith('/blog')) return 3;     // Blog: médio
-    if (pathname.startsWith('/products')) return 2; // Produtos: raso
-    return 4; // Default
-}
-
-const crawler = new PlaywrightCrawler({
-    async requestHandler({ page, enqueueLinks, request }) {
-        const url = new URL(request.url);
-        const maxDepth = getMaxDepthForPath(url.pathname);
-        const currentDepth = request.userData?.depth ?? 0;
-
-        if (currentDepth < maxDepth) {
-            await enqueueLinks({
-                userData: { depth: currentDepth + 1 },
-            });
-        }
-    },
-});
-```
-
----
-
-## Domain-Specific Crawl Rules
-
-### Crawlee EnqueueStrategy
-
-Crawlee oferece estratégias de enfileiramento por domínio/origem:
-
-```ts
-import { PlaywrightCrawler, EnqueueStrategy } from 'crawlee';
-
-const crawler = new PlaywrightCrawler({
-    async requestHandler({ page, enqueueLinks }) {
-        // SameHostname: mesmo host (subdomínios diferentes NÃO são incluídos)
-        await enqueueLinks({ strategy: EnqueueStrategy.SameHostname });
-        // Exemplo: example.com → example.com OK, sub.example.com NÃO
-
-        // SameDomain: mesmo domínio (subdomínios SÃO incluídos)
-        await enqueueLinks({ strategy: EnqueueStrategy.SameDomain });
-        // Exemplo: example.com → sub.example.com OK, other.com NÃO
-
-        // SameOrigin: mesma origem (host + porta)
-        await enqueueLinks({ strategy: EnqueueStrategy.SameOrigin });
-        // Exemplo: https://example.com:443 → https://example.com:443 OK
-
-        // All: todos os links (incluindo externos)
-        await enqueueLinks({ strategy: EnqueueStrategy.All });
-        // Exemplo: example.com → qualquer site
-    },
-});
-```
-
-### Globs e Regexps
-
-```ts
-const crawler = new PlaywrightCrawler({
-    async requestHandler({ page, enqueueLinks }) {
-        // Glob patterns — incluir apenas URLs que correspondem
-        await enqueueLinks({
-            globs: [
-                'https://example.com/blog/**',      // Blog e subpáginas
-                'https://example.com/docs/**/api/**', // Documentação API
-            ],
-        });
-
-        // Regex patterns — incluir apenas URLs que correspondem
-        await enqueueLinks({
-            regexps: [
-                /https:\/\/example\.com\/products\/\d+/,  // Páginas de produto
-                /https:\/\/example\.com\/categories\/\w+/, // Categorias
-            ],
-        });
-
-        // Excluir URLs com patterns
-        await enqueueLinks({
-            exclude: [
-                '**/login',           // Páginas de login
-                '**/signup',          // Cadastro
-                '**/*.pdf',           // PDFs
-                '**/admin/**',        // Admin
-                '**/*?sort=*',        // Ordenação
-                '**/*?page=*',        // Paginação
-            ],
-        });
-    },
-});
-```
-
-### Regras Combinadas
-
-```ts
-const crawler = new PlaywrightCrawler({
-    async requestHandler({ page, enqueueLinks }) {
-        await enqueueLinks({
-            strategy: EnqueueStrategy.SameDomain,
-            globs: [
-                'https://example.com/**',
-            ],
-            exclude: [
-                '**/login',
-                '**/signup',
-                '**/admin/**',
-                '**/*.pdf',
-                '**/*.zip',
-            ],
-            regexps: [],
-            userData: { crawledBy: 'main-crawler' },
-        });
-    },
-});
-```
-
-### Filtragem por Tipo de Link
-
-```ts
-function classifyLink(url: string, text: string): 'high' | 'medium' | 'low' | 'skip' {
-    const parsed = new URL(url);
-
-    // Pular links indesejados
-    if (parsed.pathname.match(/\.(pdf|zip|jpg|png|gif|mp4)$/i)) return 'skip';
-    if (parsed.pathname.includes('/login') || parsed.pathname.includes('/signup')) return 'skip';
-    if (parsed.search.includes('sort=') || parsed.search.includes('page=')) return 'skip';
-
-    // Links de alta prioridade
-    if (parsed.pathname.startsWith('/docs')) return 'high';
-    if (parsed.pathname.startsWith('/api')) return 'high';
-    if (parsed.pathname.startsWith('/blog')) return 'medium';
-
-    // Links de baixa prioridade
-    if (parsed.pathname.startsWith('/terms')) return 'low';
-    if (parsed.pathname.startsWith('/privacy')) return 'low';
-
-    return 'medium';
-}
-
-const crawler = new PlaywrightCrawler({
-    async requestHandler({ page, enqueueLinks }) {
-        const links = await page.$$eval('a[href]', anchors =>
-            anchors.map(a => ({ url: a.href, text: a.textContent?.trim() ?? '' }))
-        );
-
-        const priorityMap = { high: 1, medium: 5, low: 8, skip: 10 };
-
-        // Filtrar e classificar
-        const filtered = links
-            .map(link => ({
-                ...link,
-                priority: classifyLink(link.url, link.text),
-            }))
-            .filter(link => link.priority !== 'skip');
-
-        // Enfileirar com prioridade
-        for (const link of filtered) {
-            await enqueueLinks({
-                userData: { priority: priorityMap[link.priority] },
-            });
-        }
-    },
-});
-```
-
----
-
-## Canonical URLs e Redirect Handling
-
-### Canonical URLs
-
-Canonical URLs indicam a URL preferida para uma página. Crawlers devem usar a canonical em vez da URL original para evitar conteúdo duplicado.
-
-```ts
-import { PlaywrightCrawler } from 'crawlee';
-
-const crawler = new PlaywrightCrawler({
-    async requestHandler({ page, enqueueLinks, request }) {
-        // Extrair canonical URL
-        const canonical = await page.$eval(
-            'link[rel="canonical"]',
-            el => el.getAttribute('href'),
-        ).catch(() => null);
-
-        // Se canonical existe e é diferente, usar canonical
-        if (canonical && canonical !== request.url) {
-            const canonicalUrl = new URL(canonical, request.url).toString();
-            console.log(`Canonical: ${request.url} → ${canonicalUrl}`);
-
-            // Enfileirar canonical se ainda não foi visitado
-            await enqueueLinks({
-                globs: [canonicalUrl],
-            });
-        }
-
-        // Processar normalmente...
-    },
-});
-```
-
-### Redirect Handling
-
-```ts
-import { PlaywrightCrawler } from 'crawlee';
-
-const crawler = new PlaywrightCrawler({
-    async requestHandler({ page, enqueueLinks, request }) {
-        // Capturar redirects durante a navegação
-        const response = await page.goto(request.url);
-
-        if (response) {
-            const finalUrl = page.url();
-            const status = response.status();
-
-            // 301/302 redirects
-            if ([301, 302, 307, 308].includes(status)) {
-                console.log(`Redirect ${status}: ${request.url} → ${finalUrl}`);
-            }
-
-            // URL final pode ter mudado
-            if (finalUrl !== request.url) {
-                console.log(`Final URL: ${finalUrl}`);
-            }
-        }
-
-        // Extrair canonical
-        const canonical = await page.$eval(
-            'link[rel="canonical"]',
-            el => el.getAttribute('href'),
-        ).catch(() => null);
-
-        // Usar canonical se disponível
-        const effectiveUrl = canonical
-            ? new URL(canonical, page.url()).toString()
-            : page.url();
-
-        console.log(`Effective URL: ${effectiveUrl}`);
-    },
-});
-```
-
-### Redirect Chain Tracking
-
-```ts
-import { PlaywrightCrawler } from 'crawlee';
-
-interface RedirectChain {
-    original: string;
-    redirects: Array<{ url: string; status: number; timestamp: number }>;
-    final: string;
-}
-
-const crawler = new PlaywrightCrawler({
-    async requestHandler({ page, request }) {
-        const chain: RedirectChain = {
-            original: request.url,
-            redirects: [],
-            final: '',
-        };
-
-        // Interceptar redirects
-        page.on('response', response => {
-            const status = response.status();
-            if ([301, 302, 307, 308].includes(status)) {
-                chain.redirects.push({
-                    url: response.url(),
-                    status,
-                    timestamp: Date.now(),
-                });
-            }
-        });
-
-        await page.goto(request.url, { waitUntil: 'networkidle' });
-        chain.final = page.url();
-
-        if (chain.redirects.length > 0) {
-            console.log(`Redirect chain: ${chain.original}`);
-            for (const redirect of chain.redirects) {
-                console.log(`  ${redirect.status} → ${redirect.url}`);
-            }
-            console.log(`  Final: ${chain.final}`);
-        }
-    },
-});
-```
-
-### Canonical + Redirect Combinado
-
-```ts
-function resolveEffectiveUrl(pageUrl: string, canonicalHref: string | null): string {
-    // 1. Se canonical existe, é a fonte de verdade
-    if (canonicalHref) {
-        try {
-            return new URL(canonicalHref, pageUrl).toString();
-        } catch {
-            // Canonical inválido, usar pageUrl
-        }
-    }
-
-    // 2. Caso contrário, usar a URL da página
-    return pageUrl;
-}
-
-const crawler = new PlaywrightCrawler({
-    async requestHandler({ page, request }) {
-        const canonical = await page.$eval(
-            'link[rel="canonical"]',
-            el => el.getAttribute('href'),
-        ).catch(() => null);
-
-        const effectiveUrl = resolveEffectiveUrl(request.url, canonical);
-
-        // Verificar se já processamos esta canonical
-        if (effectiveUrl !== request.url) {
-            console.log(`Canonical mismatch: ${request.url} → ${effectiveUrl}`);
-        }
-
-        // Processar com a URL efetiva
-    },
-});
-```
-
----
-
-## Código Completo
-
-### Exemplo 1: Crawler BFS com robots.txt, Sitemap, e Profundidade
-
-```ts
-import { PlaywrightCrawler, RobotsTxtFile } from 'crawlee';
-import robotsParser from 'robots-parser';
-import { Sitemapper } from 'sitemapper';
-import { gotScraping } from 'got-scraping';
-import normalizeUrl from 'normalize-url';
-
-interface CrawlConfig {
-    startUrls: string[];
-    maxDepth: number;
-    maxConcurrency: number;
-    crawlDelay: number;
-    userAgent: string;
-}
-
-async function buildCrawler(config: CrawlConfig) {
-    // 1. Descobrir URLs via sitemap
-    const sitemapUrls: string[] = [];
-    for (const startUrl of config.startUrls) {
-        const parsedUrl = new URL(startUrl);
-
-        try {
-            const robotsResponse = await gotScraping(`${parsedUrl.origin}/robots.txt`);
-            const robots = robotsParser(`${parsedUrl.origin}/robots.txt`, robotsResponse.body);
-
-            const sitemapEndpoints = robots.getSitemaps() ?? [];
-            for (const sitemapUrl of sitemapEndpoints) {
-                const sitemapper = new Sitemapper({ url: sitemapUrl, timeout: 30000 });
-                const { sites } = await sitemapper.fetch();
-                sitemapUrls.push(...sites);
-            }
-        } catch (error) {
-            console.error(`Erro ao descobrir sitemaps para ${parsedUrl.origin}:`, error);
-        }
-    }
-
-    console.log(`Descobertas ${sitemapUrls.length} URLs via sitemaps`);
-
-    // 2. Deduplicar URLs normalizadas
-    const seen = new Set<string>();
-    const uniqueUrls = sitemapUrls.filter(url => {
-        const normalized = normalizeUrl(url, {
-            sortQueryParams: true,
-            stripWWW: true,
-            stripHash: true,
-            removeTrailingSlash: true,
-        });
-        if (seen.has(normalized)) return false;
-        seen.add(normalized);
-        return true;
-    });
-
-    console.log(`${uniqueUrls.length} URLs únicas após normalização`);
-
-    // 3. Criar crawler BFS com controle de profundidade
-    const crawler = new PlaywrightCrawler({
-        maxConcurrency: config.maxConcurrency,
-        requestHandlerTimeoutSecs: 30,
-        async requestHandler({ page, enqueueLinks, request }) {
-            const depth = request.userData?.depth ?? 0;
-            const indent = '  '.repeat(depth);
-
-            console.log(`${indent}[Depth ${depth}] ${request.url}`);
-
-            // Extrair dados da página
-            const title = await page.title();
-            const content = await page.content();
-
-            // Processar dados...
-
-            // Enfileirar links se não atingiu limite de profundidade
-            if (depth < config.maxDepth) {
-                await enqueueLinks({
-                    strategy: 'same-domain',
-                    userData: { depth: depth + 1 },
-                });
-            }
-        },
-    });
-
-    // 4. Executar
-    const seedUrls = uniqueUrls.slice(0, 100); // Limitar URLs iniciais
-    await crawler.run(seedUrls);
-
-    return {
-        totalProcessed: crawler.requestQueue?.handledCount() ?? 0,
-        totalEnqueued: crawler.requestQueue?.pendingCount() ?? 0,
-    };
-}
-
-// Executar
-const result = await buildCrawler({
-    startUrls: ['https://example.com'],
-    maxDepth: 3,
-    maxConcurrency: 3,
-    crawlDelay: 2,
-    userAgent: 'MyBot/1.0',
-});
-
-console.log(`Crawl completo: ${result.totalProcessed} processadas, ${result.totalEnqueued} enfileiradas`);
-```
-
-### Exemplo 2: Crawler DFS com Prioridade
-
-```ts
-import { PlaywrightCrawler } from 'crawlee';
-import PQueue from 'p-queue';
-
-const queue = new PQueue({ concurrency: 5, intervalCap: 10, interval: 1000 });
-
-function classifyPriority(url: string): number {
-    const parsed = new URL(url);
-    if (parsed.pathname.startsWith('/docs')) return 1;      // Alta
-    if (parsed.pathname.startsWith('/api')) return 2;       // Alta
-    if (parsed.pathname.startsWith('/blog')) return 4;      // Média
-    if (parsed.pathname.startsWith('/products')) return 6;  // Média-baixa
-    return 8;                                               // Baixa
-}
-
-const crawler = new PlaywrightCrawler({
-    requestQueue: await (await import('crawlee')).RequestQueue.open('dfs-queue'),
-    async requestHandler({ page, enqueueLinks, request }) {
-        const depth = request.userData?.depth ?? 0;
-
-        // DFS: forefront = true para ir para o início da fila
-        await enqueueLinks({
-            forefront: true,  // DFS!
-            userData: { depth: depth + 1 },
-        });
-    },
-});
-
-// Iniciar com URLs seed
-await crawler.run([
-    'https://example.com/docs',
-    'https://example.com/api',
-]);
-```
-
-### Exemplo 3: Rate Limiting por Domínio com p-queue
-
-```ts
-import PQueue from 'p-queue';
-
-const domainQueues = new Map<string, PQueue>();
-
-function getDomainQueue(domain: string): PQueue {
-    if (!domainQueues.has(domain)) {
-        domainQueues.set(domain, new PQueue({
-            concurrency: 2,
-            intervalCap: 3,
-            interval: 5000, // 3 requests a cada 5s por domínio
-        }));
-    }
-    return domainQueues.get(domain)!;
-}
-
-async function crawlWithRateLimit(urls: string[]): Promise<void> {
-    const promises = urls.map(async (url) => {
-        const domain = new URL(url).hostname;
-        const queue = getDomainQueue(domain);
-
-        await queue.add(async () => {
-            console.log(`Crawling: ${url}`);
-            // Simular crawl
-            await new Promise(resolve => setTimeout(resolve, 1000));
-            console.log(`Concluído: ${url}`);
-        });
-    });
-
-    await Promise.all(promises);
-}
-
-await crawlWithRateLimit([
-    'https://example.com/page1',
-    'https://example.com/page2',
-    'https://other.com/page1',
-    'https://other.com/page2',
-]);
-```
-
-### Exemplo 4: Crawler Completo com Todas as Funcionalidades
-
-```ts
-import { PlaywrightCrawler, RequestQueue } from 'crawlee';
-import robotsParser from 'robots-parser';
-import { Sitemapper } from 'sitemapper';
-import { gotScraping } from 'got-scraping';
-import normalizeUrl from 'normalize-url';
-
-interface FullCrawlConfig {
-    startUrls: string[];
-    maxDepth: number;
-    maxConcurrency: number;
-    crawlDelay: number;
-    respectRobotsTxt: boolean;
-    useSitemaps: boolean;
-}
-
-class WebCrawler {
-    private queue: RequestQueue;
-    private robots: Map<string, ReturnType<typeof robotsParser>> = new Map();
-    private seen: Set<string> = new Set();
-    private config: FullCrawlConfig;
-
-    constructor(config: FullCrawlConfig) {
-        this.config = config;
-    }
-
-    async initialize(): Promise<void> {
-        this.queue = await RequestQueue.open('full-crawl');
-
-        // Descobrir sitemaps se habilitado
-        if (this.config.useSitemaps) {
-            await this.discoverFromSitemaps();
-        }
-    }
-
-    private async discoverFromSitemaps(): Promise<void> {
-        for (const url of this.config.startUrls) {
-            const origin = new URL(url).origin;
-
-            try {
-                // Buscar robots.txt
-                const robotsResponse = await gotScraping(`${origin}/robots.txt`);
-                const robots = robotsParser(`${origin}/robots.txt`, robotsResponse.body);
-                this.robots.set(origin, robots);
-
-                // Extrair sitemaps
-                const sitemapEndpoints = robots.getSitemaps() ?? [];
-                for (const sitemapUrl of sitemapEndpoints) {
-                    const sitemapper = new Sitemapper({ url: sitemapUrl, timeout: 30000 });
-                    const { sites } = await sitemapper.fetch();
-
-                    for (const siteUrl of sites) {
-                        const normalized = this.normalizeUrl(siteUrl);
-                        if (!this.seen.has(normalized) && this.isAllowed(siteUrl)) {
-                            this.seen.add(normalized);
-                            await this.queue.addRequest({
-                                url: siteUrl,
-                                userData: { depth: 0 },
-                            });
-                        }
-                    }
-                }
-            } catch (error) {
-                console.error(`Erro ao processar ${origin}:`, error);
-            }
-        }
-    }
-
-    private normalizeUrl(url: string): string {
-        return normalizeUrl(url, {
-            sortQueryParams: true,
-            stripWWW: true,
-            stripHash: true,
-            removeTrailingSlash: true,
-        });
-    }
-
-    private isAllowed(url: string): boolean {
-        if (!this.config.respectRobotsTxt) return true;
-
-        const origin = new URL(url).origin;
-        const robots = this.robots.get(origin);
-        if (!robots) return true;
-
-        return robots.isAllowed(url) ?? true;
-    }
-
-    async crawl(): Promise<{ processed: number; enqueued: number }> {
-        const crawler = new PlaywrightCrawler({
-            maxConcurrency: this.config.maxConcurrency,
-            requestHandlerTimeoutSecs: 30,
-            requestQueue: this.queue,
-            async requestHandler({ page, enqueueLinks, request }) {
-                const depth = request.userData?.depth ?? 0;
-                const indent = '  '.repeat(depth);
-
-                console.log(`${indent}[${depth}] ${request.url}`);
-
-                // Extrair dados...
-                const title = await page.title();
-                console.log(`${indent}  Title: ${title}`);
-
-                // Enfileirar links
-                if (depth < this.config.maxDepth) {
-                    const links = await page.$$eval('a[href]', anchors =>
-                        anchors.map(a => a.href)
-                    );
-
-                    for (const link of links) {
-                        const normalized = this.normalizeUrl(link);
-                        if (!this.seen.has(normalized) && this.isAllowed(link)) {
-                            this.seen.add(normalized);
-                            await this.queue.addRequest({
-                                url: link,
-                                userData: { depth: depth + 1 },
-                            });
-                        }
-                    }
-                }
-            },
-        });
-
-        await crawler.run(this.config.startUrls);
-
-        return {
-            processed: this.queue.handledCount(),
-            enqueued: this.queue.pendingCount(),
-        };
-    }
-}
-
-// Executar crawler completo
-const crawler = new WebCrawler({
-    startUrls: ['https://example.com'],
-    maxDepth: 3,
-    maxConcurrency: 3,
-    crawlDelay: 2,
-    respectRobotsTxt: true,
-    useSitemaps: true,
-});
-
-await crawler.initialize();
-const result = await crawler.crawl();
-console.log(`Crawl completo: ${result.processed} processadas`);
-```
-
----
-
-## Referências
-
-- [Crawlee Documentation](https://crawlee.dev)
-- [robots-parser npm](https://www.npmjs.com/package/robots-parser)
-- [RFC 9309 - Robots Exclusion Protocol](https://www.rfc-editor.org/rfc/rfc9309)
-- [sitemapper npm](https://www.npmjs.com/package/sitemapper)
-- [p-queue npm](https://www.npmjs.com/package/p-queue)
-- [normalize-url npm](https://www.npmjs.com/package/normalize-url)
-- [ufo npm](https://www.npmjs.com/package/ufo)