@koalarx/scrapping 1.5.4 → 2.0.2

package/@types/browser-config.d.ts

@@ -0,0 +1,8 @@
+export interface BrowserConfig {
+    headless?: boolean;
+    proxy?: string;
+    minimalist?: boolean;
+    slowMo?: number;
+    downloadFolderPath?: string;
+    screenshotFolderPath?: string;
+}

package/@types/browser-config.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/@types/dom-options.d.ts

@@ -0,0 +1,4 @@
+export interface DOMOptions {
+    downloadFolderPath?: string;
+    screenshotFolderPath?: string;
+}

package/@types/dom-options.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/@types/get-datatable-options.d.ts

@@ -0,0 +1,9 @@
+export interface GetDatatableOptions {
+    withPagination?: {
+        nextButtonSelector: string;
+    };
+    infiniteScroll?: {
+        scrollContainerSelector: string;
+    };
+    limit?: number;
+}

package/@types/get-datatable-options.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/Browser.d.ts

@@ -0,0 +1,11 @@
+import type { BrowserConfig } from './@types/browser-config';
+import { Page } from './Page';
+export declare class Browser {
+    private config;
+    private _browser?;
+    private _page?;
+    constructor(config: BrowserConfig);
+    get page(): Page;
+    init(): Promise<this>;
+    close(): Promise<void>;
+}

package/Browser.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Browser = void 0;
+const puppeteer_1 = require("puppeteer");
+const args_1 = require("./constants/args");
+const Page_1 = require("./Page");
+const node_fs_1 = require("node:fs");
+class Browser {
+    config;
+    _browser;
+    _page;
+    constructor(config) {
+        this.config = config;
+    }
+    get page() {
+        if (!this._page) {
+            throw new Error('DOM is not lauched. Certificate you call init method.');
+        }
+        return this._page;
+    }
+    async init() {
+        const { headless, proxy, minimalist, slowMo } = this.config;
+        const downloadPath = this.config.downloadFolderPath ?? './downloads';
+        if (!(0, node_fs_1.existsSync)(downloadPath)) {
+            (0, node_fs_1.mkdirSync)(downloadPath);
+        }
+        const args = args_1.BROWSER_ARGS.concat(proxy ? [`--proxy-server=${proxy}`] : []).concat(headless ? [] : ['--start-maximized']);
+        const browser = await puppeteer_1.default.launch({
+            args,
+            headless,
+            defaultViewport: null,
+            slowMo,
+            downloadBehavior: {
+                policy: 'allow',
+                downloadPath,
+            },
+        });
+        const page = await browser.pages().then((pages) => pages[0]);
+        if (minimalist) {
+            page.removeAllListeners('request');
+            await page.setRequestInterception(true);
+            page.on('request', (req) => {
+                if (req.resourceType() === 'stylesheet' ||
+                    req.resourceType() === 'font' ||
+                    req.resourceType() === 'image') {
+                    req.abort();
+                }
+                else {
+                    req.continue();
+                }
+            });
+        }
+        this._browser = browser;
+        this._page = new Page_1.Page(page);
+        return this;
+    }
+    async close() {
+        if (!this._browser) {
+            throw new Error('Browser is not lauched. Certificate you call init method.');
+        }
+        await this._page.close();
+        await this._browser.close();
+    }
+}
+exports.Browser = Browser;

package/Dom.d.ts

@@ -0,0 +1,21 @@
+import type { KeyInput, Page } from 'puppeteer';
+import { Frame as PuppeteerFrame } from 'puppeteer';
+import type { DOMOptions } from './@types/dom-options';
+import type { GetDatatableOptions } from './@types/get-datatable-options';
+export declare class DOM {
+    private readonly _page;
+    private readonly _options?;
+    constructor(_page: Page | PuppeteerFrame, _options?: DOMOptions);
+    protected get page(): Page;
+    close(): Promise<void>;
+    screenshot(): Promise<void>;
+    pressKey(key: KeyInput, combine?: KeyInput): Promise<void>;
+    goTo(url: string): Promise<void>;
+    fill(selector: string, value: string): Promise<void>;
+    click(selector: string): Promise<void>;
+    focus(selector: string): Promise<void>;
+    content(selector: string): Promise<string[]>;
+    getDatatable<T = any>(selector: string, options?: GetDatatableOptions): Promise<T[]>;
+    waitNavigation(): Promise<void>;
+    getDownloadedFiles(): Promise<Buffer<ArrayBufferLike>[]>;
+}

package/Dom.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DOM = void 0;
+const utils_1 = require("@koalarx/utils");
+const html_table_to_json_1 = require("html-table-to-json");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const puppeteer_1 = require("puppeteer");
+class DOM {
+    _page;
+    _options;
+    constructor(_page, _options) {
+        this._page = _page;
+        this._options = _options;
+    }
+    get page() {
+        return this._page instanceof puppeteer_1.Frame ? this._page.page() : this._page;
+    }
+    async close() {
+        await this.page.close();
+    }
+    async screenshot() {
+        const folderPath = this._options?.screenshotFolderPath ?? './screenshots';
+        if (!(0, node_fs_1.existsSync)(folderPath)) {
+            (0, node_fs_1.mkdirSync)(folderPath);
+        }
+        const screenshotPath = node_path_1.default.join(folderPath, `${new utils_1.KlDate().format('ddMMyyyyHHmmss')}.jpg`);
+        await this.page.screenshot({ path: screenshotPath });
+    }
+    async pressKey(key, combine) {
+        if (combine) {
+            await this.page.keyboard.down(combine);
+        }
+        await this.page.keyboard.press(key);
+    }
+    async goTo(url) {
+        await this._page.goto(url, { waitUntil: 'networkidle2' });
+    }
+    async fill(selector, value) {
+        await this._page.locator(selector).scroll();
+        await this._page.focus(selector);
+        await this._page.locator(selector).fill(value);
+    }
+    async click(selector) {
+        await this._page.locator(selector).scroll();
+        await this._page.click(selector);
+    }
+    async focus(selector) {
+        await this._page.locator(selector).scroll();
+        await this._page.focus(selector);
+    }
+    async content(selector) {
+        await this._page.locator(selector).scroll();
+        return this._page.$$eval(selector, (elements) => {
+            return elements.map((el) => el.innerText.trim());
+        });
+    }
+    async getDatatable(selector, options) {
+        const table = await this._page.$eval(selector, (table) => table.outerHTML);
+        const tableData = html_table_to_json_1.default.parse(table).results[0];
+        const result = tableData.map((row) => {
+            const rowData = {};
+            Object.keys(row).forEach((key) => {
+                const value = row[key];
+                const numberValue = Number(value);
+                rowData[(0, utils_1.toCamelCase)(key)] = isNaN(numberValue) ? value : numberValue;
+            });
+            return rowData;
+        });
+        if (options?.withPagination) {
+            const nextButtonSelector = options.withPagination.nextButtonSelector;
+            const nextButton = await this._page.$(nextButtonSelector);
+            if (nextButton &&
+                !(await nextButton.evaluate((btn) => btn.classList.contains('disabled') || btn.hasAttribute('disabled')))) {
+                await nextButton.click();
+                const nextPageData = await this.getDatatable(selector, options);
+                result.push(...nextPageData);
+            }
+        }
+        return result;
+    }
+    async waitNavigation() {
+        await this._page
+            .waitForNavigation({ waitUntil: 'domcontentloaded', timeout: 5000 })
+            .catch(() => null);
+    }
+    async getDownloadedFiles() {
+        const downloadPath = this._options?.downloadFolderPath ?? './downloads';
+        if ((0, node_fs_1.existsSync)(downloadPath)) {
+            let contentDir = [];
+            do {
+                await (0, utils_1.delay)(1000);
+                contentDir = (0, node_fs_1.readdirSync)(downloadPath);
+            } while (contentDir.filter((filepath) => filepath.indexOf('.crdownload') >= 0)
+                .length > 0);
+            const files = [];
+            contentDir.forEach((filepath) => files.push((0, node_fs_1.readFileSync)(`${downloadPath}/${filepath}`)));
+            return files;
+        }
+        return [];
+    }
+}
+exports.DOM = DOM;

package/Frame.d.ts

@@ -0,0 +1,5 @@
+import { Frame as PuppeteerFrame } from 'puppeteer';
+import { DOM } from './Dom';
+export declare class Frame extends DOM {
+    constructor(frame: PuppeteerFrame);
+}

package/Frame.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Frame = void 0;
+const Dom_1 = require("./Dom");
+class Frame extends Dom_1.DOM {
+    constructor(frame) {
+        super(frame);
+    }
+}
+exports.Frame = Frame;

package/Page.d.ts

@@ -0,0 +1,8 @@
+import type { Page as PuppeteerPage } from 'puppeteer';
+import { DOM } from './Dom';
+import { Frame } from './Frame';
+export declare class Page extends DOM {
+    constructor(page: PuppeteerPage);
+    getFrameByURL(url: string): Promise<Frame>;
+    getFrameByName(name: string): Promise<Frame>;
+}

package/Page.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Page = void 0;
+const Dom_1 = require("./Dom");
+const Frame_1 = require("./Frame");
+class Page extends Dom_1.DOM {
+    constructor(page) {
+        super(page);
+    }
+    async getFrameByURL(url) {
+        const frames = this.page.frames();
+        const frame = frames.find((frame) => frame.url() === url);
+        if (!frame) {
+            throw new Error(`Frame with URL "${url}" not found`);
+        }
+        return new Frame_1.Frame(frame);
+    }
+    async getFrameByName(name) {
+        const frames = this.page.frames();
+        let frame;
+        for (const f of frames) {
+            const frameElement = await f.frameElement();
+            if (!frameElement) {
+                continue;
+            }
+            const frameName = await frameElement.evaluate((el) => el.getAttribute('name'));
+            if (frameName === name) {
+                frame = f;
+                break;
+            }
+            const frameId = await frameElement.evaluate((el) => el.getAttribute('id'));
+            if (frameId === name) {
+                frame = f;
+                break;
+            }
+        }
+        if (!frame) {
+            throw new Error(`Frame with name "${name}" not found`);
+        }
+        return new Frame_1.Frame(frame);
+    }
+}
+exports.Page = Page;

package/README.md

@@ -1,2 +1,359 @@
-# koala-scrapping
-Uma abstração utilizando Puppeteer para Web Scrapping
+# koala-scrapping
+
+Uma poderosa biblioteca de abstração do [Puppeteer](https://pptr.dev/) para automação de navegadores e web scraping. Fornece uma API simplificada e intuitiva para interagir com páginas web, extrair dados e automatizar tarefas de RPA (Robotic Process Automation).
+
+## Características
+
+- ✅ Abstração elegante do Puppeteer
+- ✅ Suporte a navegação, cliques e preenchimento de formulários
+- ✅ Extração de dados de tabelas com paginação automática
+- ✅ Interação com frames e iframes
+- ✅ Download de arquivos
+- ✅ Captura de screenshots
+- ✅ API intuitiva e fácil de usar
+- ✅ Suporte a teclado (pressionar teclas com combinações)
+
+## Instalação
+
+```bash
+npm install @koalarx/scrapping puppeteer
+```
+
+Ou com Bun:
+
+```bash
+bun install @koalarx/scrapping puppeteer
+```
+
+## Uso Básico
+
+### 1. Inicializar o Browser
+
+```typescript
+import { Browser } from '@koalarx/scrapping'
+
+const browser = new Browser({
+  headless: false,        // true para modo headless
+  slowMo: 100,           // delay em ms entre ações (útil para debug)
+})
+
+await browser.init()
+const page = browser.page
+
+// ... suas ações aqui ...
+
+await browser.close()
+```
+
+### 2. Navegar para uma URL
+
+```typescript
+await page.goTo('https://example.com')
+```
+
+### 3. Interagir com Elementos
+
+#### Clicar em um elemento
+
+```typescript
+await page.click('#button-id')
+// ou
+await page.click('button.submit-btn')
+```
+
+#### Preencher um campo de input
+
+```typescript
+await page.fill('#email-input', 'user@example.com')
+await page.fill('#password-input', 'senha123')
+```
+
+#### Focar em um elemento
+
+```typescript
+await page.focus('#search-input')
+```
+
+#### Pressionar teclas
+
+```typescript
+// Pressionar uma tecla simples
+await page.pressKey('Enter')
+
+// Pressionar combinações de teclas (ex: Ctrl+A)
+await page.pressKey('a', 'Control')
+```
+
+### 4. Extrair Conteúdo
+
+```typescript
+// Extrair texto de elementos
+const paragrafos = await page.content('#content p')
+console.log(paragrafos) // Array de strings
+```
+
+### 5. Capturar Screenshot
+
+```typescript
+await page.screenshot()
+// Salva a screenshot em ./screenshots/ por padrão
+```
+
+## Casos de Uso Avançados
+
+### Extração de Dados de Tabelas
+
+A biblioteca pode extrair dados de tabelas HTML automaticamente, convertendo para objetos TypeScript tipados:
+
+```typescript
+interface DadosTabela {
+  nome: string
+  posicao: string
+  departamento: string
+  salario: number
+}
+
+const dados = await page.getDatatable<DadosTabela>('#tabela-exemplo')
+console.log(dados[0].nome)  // TypeScript com autocompletar
+```
+
+**Com paginação automática:**
+
+```typescript
+const dados = await page.getDatatable<DadosTabela>('#example', {
+  withPagination: {
+    nextButtonSelector: '#btn-proxima'
+  }
+})
+// Extrai todas as páginas automaticamente!
+```
+
+📝 **Exemplo prático:** Ver [get-datatable.spec.ts](lib/test/get-datatable.spec.ts)
+
+### Download de Arquivos
+
+```typescript
+await page.goTo('https://exemplo.com/arquivos')
+await page.click('a.download-link')
+
+// Aguardar e obter os arquivos baixados
+const arquivos = await page.getDownloadedFiles()
+console.log(arquivos[0])  // Buffer do arquivo
+```
+
+📝 **Exemplo prático:** Ver [download-file.spec.ts](lib/test/download-file.spec.ts)
+
+### Interação com Frames e iFrames
+
+A biblioteca oferece suporte completo para trabalhar com frames e iframes:
+
+#### Buscar frame por URL
+
+```typescript
+const frame = await page.getFrameByURL('https://example.com')
+// O frame também possui todos os métodos da classe Page/DOM
+await frame.click('a.link')
+await frame.fill('#input', 'valor')
+```
+
+#### Buscar frame por nome ou ID
+
+```typescript
+const frame = await page.getFrameByName('iframe-principal')
+await frame.fill('#search', 'Einstein')
+await frame.pressKey('Enter')
+```
+
+**Exemplo completo:**
+
+```typescript
+await page.goTo('https://iframetester.com/?url=https://pt.wikipedia.org')
+
+// Encontrar o frame pelo atributo name
+const frame = await page.getFrameByName('iframe-window')
+
+// Interagir dentro do frame como se fosse uma página normal
+await frame.click('#search-button')
+await frame.fill('#search-input', 'Einstein')
+await frame.pressKey('Enter')
+
+const conteudo = await frame.content('#resultado p')
+console.log(conteudo)
+```
+
+📝 **Exemplo prático:** Ver [frame-interaction.spec.ts](lib/test/frame-interaction.spec.ts)
+
+### Web Scraping Completo
+
+Exemplo de busca e extração de dados do Wikipedia:
+
+```typescript
+await page.goTo('https://pt.wikipedia.org')
+
+// Clicar no campo de busca
+await page.click('#searchInput')
+
+// Preencher com termo de busca
+await page.fill(
+  '#searchform > div > div > div.cdx-text-input #search-input',
+  'Einstein'
+)
+
+// Pressionar Enter
+await page.pressKey('Enter')
+
+// Aguardar navegação
+await page.waitNavigation()
+
+// Extrair conteúdo
+const conteudo = await page.content('#mw-content-text p')
+console.log(conteudo)  // Array com paragrafos
+```
+
+📝 **Exemplo prático:** Ver [search-wikipidea.spec.ts](lib/test/search-wikipidea.spec.ts)
+
+## Configuração Avançada
+
+### Opções do Browser
+
+```typescript
+const browser = new Browser({
+  headless: true,              // Modo headless (sem UI)
+  slowMo: 0,                   // Delay entre ações em ms
+  proxy: 'http://proxy:8080',  // Usar proxy
+  minimalist: true,            // Bloquear CSS, fonts e imagens (mais rápido)
+  downloadFolderPath: './meus-downloads'  // Pasta para downloads
+})
+```
+
+### Opções do DOM
+
+```typescript
+const page = browser.page
+
+// Customizar pasta de screenshots
+page = new Page(puppeteerPage, {
+  screenshotFolderPath: './meus-screenshots',
+  downloadFolderPath: './meus-downloads'
+})
+```
+
+## API Referência
+
+### Classe Browser
+
+| Método | Descrição |
+|--------|-----------|
+| `init()` | Inicializa o navegador |
+| `close()` | Fecha o navegador |
+| `get page` | Obtém a página ativa |
+
+### Classe Page extend DOM
+
+| Método | Descrição |
+|--------|-----------|
+| `getFrameByURL(url)` | Busca um frame pela URL |
+| `getFrameByName(name)` | Busca um frame pelo name ou id |
+
+### Classe DOM (base para Page e Frame)
+
+| Método | Retorno | Descrição |
+|--------|---------|-----------|
+| `goTo(url)` | `void` | Navega para uma URL |
+| `click(selector)` | `void` | Clica em um elemento |
+| `fill(selector, value)` | `void` | Preenche um campo |
+| `focus(selector)` | `void` | Foca em um elemento |
+| `pressKey(key, combine?)` | `void` | Pressiona uma tecla |
+| `content(selector)` | `string[]` | Extrai texto de elementos |
+| `getDatatable<T>(selector, options?)` | `T[]` | Extrai dados de tabela |
+| `getDownloadedFiles()` | `Buffer[]` | Obtém arquivos baixados |
+| `screenshot()` | `void` | Captura screenshot |
+| `waitNavigation()` | `void` | Aguarda navegação |
+| `close()` | `void` | Fecha a página |
+
+## Exemplos Completos
+
+### Exemplo 1: Buscar e Extrair Dados
+
+```typescript
+import { Browser } from '@koalarx/scrapping'
+
+const browser = new Browser({ headless: true })
+await browser.init()
+const page = browser.page
+
+// Ir para o site
+await page.goTo('https://datatables.net')
+
+// Extrair tabela
+interface Funcionario {
+  name: string
+  position: string
+  office: string
+  age: number
+  startDate: string
+  salary: number
+}
+
+const funcionarios = await page.getDatatable<Funcionario>('#example', {
+  withPagination: {
+    nextButtonSelector: '.next-button'
+  }
+})
+
+console.log(funcionarios)
+
+await browser.close()
+```
+
+### Exemplo 2: Login e Scraping
+
+```typescript
+const browser = new Browser({ headless: false })
+await browser.init()
+const page = browser.page
+
+// Navegar ao site
+await page.goTo('https://exemplo.com/login')
+
+// Fazer login
+await page.fill('#email', 'user@example.com')
+await page.fill('#password', 'senha123')
+await page.click('#btn-login')
+
+// Aguardar redirecionamento
+await new Promise(r => setTimeout(r, 2000))
+
+// Extrair dados
+const dados = await page.getDatatable('#dados-tabela')
+console.log(dados)
+
+// Screenshot do resultado
+await page.screenshot()
+
+await browser.close()
+```
+
+## Development
+
+Para instalar dependências:
+
+```bash
+bun install
+```
+
+Para compilar:
+
+```bash
+bun run build
+```
+
+Para rodar os testes:
+
+```bash
+bun test
+```
+
+## Licença
+
+Ver arquivo [LICENSE](LICENSE)

package/constants/args.d.ts

@@ -0,0 +1,2 @@
+import { KlArray } from '@koalarx/utils';
+export declare const BROWSER_ARGS: KlArray<string>;