@koalarx/scrapping 1.5.4 → 2.0.0

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,32 @@
+name: NPM PUBLISH
+on:
+  push:
+    branches: [main]
+jobs:
+  build:
+    name: "npm publish library"
+    runs-on: ubuntu-latest
+    steps:
+      - name: 🚚 Get latest code
+        uses: actions/checkout@v3
+        with:
+          ref: main
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v1
+        with:
+          bun-version: latest
+
+      - name: 🔨 Install Dependencies
+        run: bun ci
+
+      - name: 🔨 Build Project
+        run: bun run build
+
+      - name: 🔑 Configure NPM
+        run: npm config set "//registry.npmjs.org/:_authToken" "${{ secrets.NPM_TOKEN }}"
+      
+      - name: 📚 Publish @koalarx/nest
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.prettierrc.json

@@ -0,0 +1,9 @@
+{
+  "printWidth": 80,
+  "tabWidth": 2,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "arrowParens": "always",
+  "semi": false,
+  "endOfLine": "lf"
+}

package/.vscode/launch.json

@@ -0,0 +1,13 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "bun",
+      "request": "launch",
+      "name": "Debug Bun File",
+      "program": "${file}", // This runs the currently active file
+      "cwd": "${workspaceFolder}",
+      "stopOnEntry": false // Set to true to pause on the first line
+    },
+  ]
+}

package/.vscode/mcp.json

@@ -0,0 +1,10 @@
+{
+  "servers": {
+    "koala-nest-docs": {
+      "command": "bunx",
+      "args": [
+        "@koalarx/mcp-server"
+      ]
+    }
+  }
+}

package/.vscode/settings.json

@@ -0,0 +1,151 @@
+{
+  "material-icon-theme.activeIconPack": "nest",
+  "editor.fontFamily": "Fira Code",
+  "editor.fontSize": 15,
+  "editor.fontLigatures": true,
+  "emmet.syntaxProfiles": {
+    "javascript": "jsx"
+  },
+  "workbench.startupEditor": "newUntitledFile",
+  "javascript.suggest.autoImports": true,
+  "javascript.updateImportsOnFileMove.enabled": "always",
+  "editor.rulers": [80, 120],
+  "extensions.ignoreRecommendations": true,
+  "typescript.tsserver.log": "off",
+  "files.associations": {
+    ".sequelizerc": "javascript",
+    ".stylelintrc": "json",
+    "*.tsx": "typescriptreact",
+    ".env.*": "dotenv",
+    ".prettierrc": "json"
+  },
+  "editor.parameterHints.enabled": false,
+  "editor.renderLineHighlight": "gutter",
+  "editor.lineHeight": 26,
+  "editor.suggestSelection": "first",
+  "explorer.confirmDelete": false,
+  "gitlens.codeLens.recentChange.enabled": false,
+  "terminal.integrated.showExitAlert": false,
+  "[prisma]": {
+    "editor.formatOnSave": true
+  },
+  "typescript.suggest.autoImports": true,
+  "terminal.integrated.env.osx": {
+    "FIG_NEW_SESSION": "1"
+  },
+  "workbench.editor.labelFormat": "short",
+  "editor.acceptSuggestionOnCommitCharacter": false,
+  "explorer.compactFolders": false,
+  "git.enableSmartCommit": true,
+  "editor.accessibilitySupport": "off",
+  "explorer.confirmDragAndDrop": false,
+  "terminal.integrated.fontSize": 14,
+  "editor.semanticHighlighting.enabled": false,
+  "breadcrumbs.enabled": true,
+  "gitlens.codeLens.authors.enabled": false,
+  "editor.tabSize": 2,
+  "files.exclude": {
+    "**/CVS": true,
+    "**/.DS_Store": true,
+    "**/.hg": true,
+    "**/.svn": true,
+    "**/.git": true
+  },
+  "gitlens.codeLens.enabled": false,
+  "workbench.iconTheme": "material-icon-theme",
+  "material-icon-theme.languages.associations": {
+    "dotenv": "tune"
+  },
+  "material-icon-theme.files.associations": {
+    "vitest.config.e2e.ts": "vitest",
+    "*.e2e-spec.ts": "test-js",
+    "*.dto.ts": "diff",
+    "*.handler.ts": "esbuild",
+    "*.request.ts": "log",
+    "*.schema.ts": "scheme",
+    "*.response.ts": "conduct",
+    "*.validator.ts": "commitlint"
+  },
+  "material-icon-theme.folders.associations": {
+    "adapters": "contract",
+    "grpc": "pipe",
+    "kube": "kubernetes",
+    "main": "lib",
+    "websockets": "pipe",
+    "implementations": "core",
+    "protos": "pipe",
+    "entities": "class",
+    "kafka": "pipe",
+    "use-cases": "functions",
+    "migrations": "tools",
+    "schemas": "class",
+    "useCases": "functions",
+    "eslint-config": "tools",
+    "typeorm": "database",
+    "_shared": "shared",
+    "mappers": "meta",
+    "fakes": "mock",
+    "modules": "components",
+    "subscribers": "messages",
+    "domain": "class",
+    "protocols": "contract",
+    "infra": "app",
+    "view-models": "views",
+    "presentation": "template",
+    "dtos": "typescript",
+    "http": "container",
+    "providers": "include",
+    "factories": "class",
+    "repositories": "mappings",
+    "filters": "pipe"
+  },
+  "[javascript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode",
+    "editor.formatOnSave": true,
+    "editor.codeActionsOnSave": {
+      "source.fixAll.eslint": "explicit"
+    }
+  },
+  "[typescript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode",
+    "editor.formatOnSave": true,
+    "editor.codeActionsOnSave": {
+      "source.fixAll.eslint": "explicit"
+    }
+  },
+  "prettier.documentSelectors": ["**/*.ts", "**/*.tsx", "**/*.js"],
+  "terminal.integrated.defaultProfile.windows": "Command Prompt",
+  "git.confirmSync": false,
+  "files.eol": "\n",
+  "workbench.productIconTheme": "Default",
+  "npm.scriptExplorerAction": "run",
+  "npm.packageManager": "npm",
+  "editor.wordWrap": "on",
+  "editor.wrappingIndent": "indent",
+  "chat.mcp.serverSampling": {
+    "globo-seguros-api/.vscode/mcp.json: koala-nest-docs": {
+      "allowedModels": [
+        "copilot/claude-sonnet-4.5",
+        "copilot/auto",
+        "copilot/claude-haiku-4.5",
+        "copilot/claude-opus-4.5",
+        "copilot/claude-sonnet-4",
+        "copilot/gemini-2.5-pro",
+        "copilot/gemini-3-flash-preview",
+        "copilot/gemini-3-pro-preview",
+        "copilot/gpt-4.1",
+        "copilot/gpt-4o",
+        "copilot/gpt-5",
+        "copilot/gpt-5-mini",
+        "copilot/gpt-5-codex",
+        "copilot/gpt-5.1",
+        "copilot/gpt-5.1-codex",
+        "copilot/gpt-5.1-codex-max",
+        "copilot/gpt-5.1-codex-mini",
+        "copilot/gpt-5.2",
+        "copilot/gpt-5.2-codex",
+        "copilot/grok-code-fast-1"
+      ]
+    }
+  }
+}

package/.vscode/tasks.json

@@ -0,0 +1,17 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "bun: start:debug",
+      "type": "shell",
+      "command": "bun",
+      "args": ["run", "start:debug"],
+      "group": {
+        "kind": "build",
+        "isDefault": true
+      },
+      "problemMatcher": [],
+      "isBackground": true
+    }
+  ]
+}

package/LICENSE

@@ -1,24 +1,21 @@
-This is free and unencumbered software released into the public domain.
-
-Anyone is free to copy, modify, publish, use, compile, sell, or
-distribute this software, either in source code form or as a compiled
-binary, for any purpose, commercial or non-commercial, and by any
-means.
-
-In jurisdictions that recognize copyright laws, the author or authors
-of this software dedicate any and all copyright interest in the
-software to the public domain. We make this dedication for the benefit
-of the public at large and to the detriment of our heirs and
-successors. We intend this dedication to be an overt act of
-relinquishment in perpetuity of all present and future rights to this
-software under copyright law.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
-OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-OTHER DEALINGS IN THE SOFTWARE.
-
-For more information, please refer to <https://unlicense.org>
+MIT License
+
+Copyright (c) 2023 Igor D. Rangel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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)