@onveloz/browser

SDK oficial do Veloz Browser — sessões de navegador headless com stealth garantido, rodando na infraestrutura do Veloz e prontas para connectOverCDP.

Toda sessão já vem com as proteções anti-detecção ativas — não há nada para configurar. O egresso é direto por padrão; se você precisa sair por um proxy, use o seu (proxyServer).

O SDK não embute o Playwright. Ele entrega uma connectUrl e você conecta com o seu próprio playwright/playwright-core.

Instalação

npm install @onveloz/browser playwright-core

Autenticação

Gere uma chave bk_live_* no painel em Browser → Chaves de API. Defina VELOZ_BROWSER_TOKEN no ambiente ou passe { token } ao construtor.

export VELOZ_BROWSER_TOKEN="bk_live_..."

Uso

Conectar-para-acordar (uma linha)

Nenhuma sessão é criada de antemão: um navegador quente é provisionado quando você abre o socket CDP e encerrado automaticamente quando você desconecta.

import { Onveloz } from "@onveloz/browser";
import { chromium } from "playwright-core";

const ov = new Onveloz();

const browser = await chromium.connectOverCDP(await ov.connect());
const page = await browser.newPage();
await page.goto("https://example.com");
console.log(await page.title());
await browser.close(); // desconectar encerra a sessão

Sessão explícita

Crie a sessão, aguarde ficar pronta, conecte e encerre quando terminar.

import { Onveloz } from "@onveloz/browser";
import { chromium } from "playwright-core";

const ov = new Onveloz();

const session = await ov.sessions.create();
const ready = await ov.sessions.waitUntilReady(session.id);

const browser = await chromium.connectOverCDP(ready.connectUrl!);
// ... automação ...
await browser.close();

await ov.sessions.close(session.id);

Usando o seu próprio proxy

Para egressar pelo seu proxy, informe o gateway (e credenciais, se houver). O proxyCountry alinha o fingerprint de stealth (locale/timezone) com a geo de saída do seu proxy. Se você omitir proxyCountry, o padrão é BR — o fingerprint fica coerente com um IP brasileiro (pt-BR / America/Sao_Paulo). Informe proxyCountry explicitamente para outra geo.

const session = await ov.sessions.create({
  proxyServer: "http://gateway.seu-proxy.com:8080", // http, https ou socks5
  proxyUsername: "usuario", // opcional (omita para proxy por IP)
  proxyPassword: "senha", // opcional
  proxyCountry: "US", // opcional — padrão BR
});

API

new Onveloz(options?)

| Opção | Padrão | Descrição | | -------- | --------------------------------- | -------------------------------- | | token | process.env.VELOZ_BROWSER_TOKEN | Chave bk_live_* do painel. | | apiUrl | https://platform.onveloz.com | URL base da API. | | fetch | globalThis.fetch | Implementação de fetch custom. |

ov.connect(config?) → Promise<string>

Gera a connectUrl de conectar-para-acordar. ov.token(config?) é um alias. Aceita o engine e as options de sessions.create(); a URL não passa de 8 KiB, então opções muito grandes (como initScripts) pedem uma sessão criada antes.

ov.sessions

• create(config?) → cria uma sessão (PENDING; o provisionamento roda fora da requisição).
• get(id) → busca uma sessão e sua connectUrl.
• list({ activeOnly? }) → lista as sessões da organização.
• close(id) → encerra uma sessão.
• liveView(id) → gera a URL de visualização ao vivo (sob demanda).
• waitUntilReady(id, { timeoutMs?, pollMs?, signal? }) → faz polling até RUNNING e retorna a sessão.

Visualização ao vivo

Uma sessão RUNNING expõe, sob demanda, a tela do navegador em tempo real. É interativa, e não somente-leitura, já que cliques e teclas voltam como CDP Input.*.

const liveUrl = await ov.sessions.liveView(session.id);
// wss://.../v1/live?token=...

Nada é transmitido até você abrir a URL: o token é inerte e o screencast só começa quando o WebSocket conecta. Por isso ela fica num método próprio, e não num campo de get, que é chamado em polling.

É uma capacidade separada da connectUrl: este token não abre o socket CDP bruto, então dá para entregá-lo sem ceder controle total sobre a automação. Como ele ainda permite dirigir a sessão, trate-o como um segredo. Expira junto com a sessão e lança not_found fora do estado RUNNING.

SessionConfig

O stealth é sempre garantido e não é configurável. O egresso é direto a menos que você traga o seu próprio proxy.

| Campo | Tipo | Descrição | | --------------- | -------- | --------------------------------------------------------------------------------------- | | proxyServer | string | Seu gateway de proxy (scheme://host:porta — http, https ou socks5). Só em create(). | | proxyUsername | string | Usuário do seu proxy (opcional — omita para proxy por IP). | | proxyPassword | string | Senha do seu proxy (opcional). Criptografada em repouso; nunca retornada. | | proxyCountry | string | País de saída do seu proxy (ISO de 2 letras) — alinha o fingerprint de stealth. | | region | string | Região de provisionamento. | | timeoutSec | number | TTL máximo (limitado ao teto do seu plano). |

Erros

• BrowserAccessError — token ausente/inválido ou organização sem acesso.
• BrowserQuotaError — limite de sessões simultâneas do plano atingido.
• BrowserError — falha genérica (code + status).

Licença

MIT