hobots 1.5.1 → 1.6.0

package/docs/concepts.md

@@ -8,30 +8,30 @@ Os defaults numéricos **não** estão aqui — eles vivem em [Tempos e interval
 
 ## Mapa rápido
 
-| Conceito | Em uma frase | Quando você usa |
-| --- | --- | --- |
-| [Evento](#evento) | Uma foto de algo que aconteceu — um erro ou uma mensagem | `captureException` / `captureMessage` |
-| [Level](#level-severity) | A gravidade do evento | Para separar o que acorda alguém do que é só registro |
-| [Fingerprint](#fingerprint) | A chave de agrupamento dos eventos em issues | Quando o agrupamento automático erra |
-| [Scope](#scope) | A mochila de contexto que viaja com todo evento | Você raramente mexe direto; mexe pelos `set*` |
-| [withScope](#withscope) | Um scope temporário e isolado | Contexto que **não** deve vazar para o resto do programa |
-| [Tag](#tag) | Rótulo curto e indexável (`string` → `string`) | Você vai **filtrar** ou **agrupar** por isso |
-| [Context](#context) | Grupo nomeado de dados estruturados | Você vai **ler** isso ao abrir o evento |
-| [Extra](#extra) | Depósito livre, sem estrutura | Não é filtro nem grupo coerente — é anexo |
-| [Breadcrumb](#breadcrumb) | Migalha da trilha que levou até o erro | Marcar cada passo relevante do robô |
-| [Transaction](#transaction) | Unidade de trabalho nomeada, com duração | Medir quanto uma rotina inteira demorou |
-| [Span](#span) | Uma etapa medida dentro da transaction | Descobrir **onde** o tempo foi gasto |
-| [ctx.tx](#transaction-de-run-ctxtx) | A transaction que o SDK já abriu para a run | Medir as etapas de um handler do Manager |
-| [Amostragem](#amostragem-samplerate-e-tracessamplerate) | Enviar só uma fração do que acontece | Volume alto demais para enviar tudo |
-| [Check-in](#check-in) | Par de avisos "comecei" / "terminei" de um job agendado | Cron que precisa ser vigiado |
-| [Heartbeat](#heartbeat) | Batimento "estou vivo" | Saber que o robô está de pé, mesmo parado |
-| [instanceId](#instanceid) | A identidade da instância do robô | Sempre — é obrigatório no `init()` |
-| [Release e environment](#release-e-environment) | Qual versão, em qual ambiente | Separar produção de homologação; achar a versão que quebrou |
-| [Run](#run) | Uma execução solicitada no app | O Manager inteiro gira em volta disso |
-| [Claim](#claim) | O ato de um agente pegar uma run para si | Entender por que dois agentes nunca colidem |
-| [Drain mode](#drain-mode) | O agente acelera o poll enquanto tem trabalho | Entender o ritmo do polling |
-| [Fila, flush e close](#fila-flush-e-close) | Nada é enviado na hora — vai para uma fila | Encerrar o processo sem perder telemetria |
-| [beforeSend](#beforesend) | O último gancho antes do envio | Censurar ou descartar eventos |
+| Conceito                                                | Em uma frase                                             | Quando você usa                                             |
+| ------------------------------------------------------- | -------------------------------------------------------- | ----------------------------------------------------------- |
+| [Evento](#evento)                                       | Uma foto de algo que aconteceu — um erro ou uma mensagem | `captureException` / `captureMessage`                       |
+| [Level](#level-severity)                                | A gravidade do evento                                    | Para separar o que acorda alguém do que é só registro       |
+| [Fingerprint](#fingerprint)                             | A chave de agrupamento dos eventos em issues             | Quando o agrupamento automático erra                        |
+| [Scope](#scope)                                         | A mochila de contexto que viaja com todo evento          | Você raramente mexe direto; mexe pelos `set*`               |
+| [withScope](#withscope)                                 | Um scope temporário e isolado                            | Contexto que **não** deve vazar para o resto do programa    |
+| [Tag](#tag)                                             | Rótulo curto e indexável (`string` → `string`)           | Você vai **filtrar** ou **agrupar** por isso                |
+| [Context](#context)                                     | Grupo nomeado de dados estruturados                      | Você vai **ler** isso ao abrir o evento                     |
+| [Extra](#extra)                                         | Depósito livre, sem estrutura                            | Não é filtro nem grupo coerente — é anexo                   |
+| [Breadcrumb](#breadcrumb)                               | Migalha da trilha que levou até o erro                   | Marcar cada passo relevante do robô                         |
+| [Transaction](#transaction)                             | Unidade de trabalho nomeada, com duração                 | Medir quanto uma rotina inteira demorou                     |
+| [Span](#span)                                           | Uma etapa medida dentro da transaction                   | Descobrir **onde** o tempo foi gasto                        |
+| [ctx.tx](#transaction-de-run-ctxtx)                     | A transaction que o SDK já abriu para a run              | Medir as etapas de um handler do Manager                    |
+| [Amostragem](#amostragem-samplerate-e-tracessamplerate) | Enviar só uma fração do que acontece                     | Volume alto demais para enviar tudo                         |
+| [Check-in](#check-in)                                   | Par de avisos "comecei" / "terminei" de um job agendado  | Cron que precisa ser vigiado                                |
+| [Heartbeat](#heartbeat)                                 | Batimento "estou vivo"                                   | Saber que o robô está de pé, mesmo parado                   |
+| [instanceId](#instanceid)                               | A identidade da instância do robô                        | Sempre — é obrigatório no `init()`                          |
+| [Release e environment](#release-e-environment)         | Qual versão, em qual ambiente                            | Separar produção de homologação; achar a versão que quebrou |
+| [Run](#run)                                             | Uma execução solicitada no app                           | O Manager inteiro gira em volta disso                       |
+| [Claim](#claim)                                         | O ato de um agente pegar uma run para si                 | Entender por que dois agentes nunca colidem                 |
+| [Drain mode](#drain-mode)                               | O agente acelera o poll enquanto tem trabalho            | Entender o ritmo do polling                                 |
+| [Fila, flush e close](#fila-flush-e-close)              | Nada é enviado na hora — vai para uma fila               | Encerrar o processo sem perder telemetria                   |
+| [beforeSend](#beforesend)                               | O último gancho antes do envio                           | Censurar ou descartar eventos                               |
 
 > **Nota de manutenção:** esta página é a fonte canônica das explicações de conceito. As outras páginas da doc, o `README.md` do pacote e os tooltips do app parafraseiam daqui — quando um conceito muda, muda aqui primeiro.
 
@@ -112,7 +112,7 @@ Dois pontos importantes:
 `withScope` executa um callback com uma **cópia isolada** do scope. O que você escrever lá dentro vale para os eventos capturados dentro do callback e **não vaza** para fora.
 
 ```js
-Hobots.withScope((scope) => {
+Hobots.withScope(scope => {
   scope.setTag('lote', '128').setFingerprint(['reprocessamento']);
   Hobots.captureMessage('Reprocessando lote 128');
 });
@@ -172,11 +172,11 @@ Hobots.setExtra('tentativas', [1, 2, 3]);
 
 É deliberadamente o menos estruturado dos três, e por isso o critério de escolha é simples:
 
-| Você vai… | Use |
-| --- | --- |
-| filtrar, agrupar, contar por isso | [tag](#tag) |
-| ler isso como um conjunto coerente | [context](#context) |
-| nenhum dos dois — é só um dado a mais | **extra** |
+| Você vai…                             | Use                 |
+| ------------------------------------- | ------------------- |
+| filtrar, agrupar, contar por isso     | [tag](#tag)         |
+| ler isso como um conjunto coerente    | [context](#context) |
+| nenhum dos dois — é só um dado a mais | **extra**           |
 
 Extra não é indexado: não dá para filtrar por ele nem construir gráfico com ele. Se você se pegar querendo isso, o campo era uma tag.
 
@@ -207,7 +207,7 @@ Tamanho do buffer: [`maxBreadcrumbs`](./api-reference.md#initoptions).
 
 Uma **transaction** é uma unidade de trabalho **nomeada** e **medida**: ela começa, termina, e o que fica registrado é quanto tempo levou. É a resposta para "quanto demora minha rotina de emissão?" — e, quando você adiciona [spans](#span), para "onde foram esses minutos?".
 
-Enquanto o [evento](#evento) responde *o que quebrou*, a transaction responde *quanto tempo levou*. São os dois eixos do Monitor.
+Enquanto o [evento](#evento) responde _o que quebrou_, a transaction responde _quanto tempo levou_. São os dois eixos do Monitor.
 
 ```js
 const tx = Hobots.startTransaction('processar-lote', 'rpa.job');
@@ -272,7 +272,7 @@ Sem nenhum `startChild` a transaction ainda existe e ainda mede o tempo total da
 
 - **Não chame `Hobots.startTransaction()` dentro de um handler.** Você criaria uma segunda transaction, **sem** correlação com a run, e ela não apareceria na execução.
 - `ctx.tx` **não respeita o `tracesSampleRate`** — toda run gera uma transaction. A amostragem vale para as transactions que **você** abre com `startTransaction()`.
-- O nome é `run:<task>` e o `op` é `manager.run`, preenchidos pelo SDK.
+- O nome é `run:<task>` e o `op` é `hobots.task`, preenchidos pelo SDK.
 
 ## Amostragem (sampleRate e tracesSampleRate)
 
@@ -280,9 +280,9 @@ Sem nenhum `startChild` a transaction ainda existe e ainda mede o tempo total da
 
 São dois controles independentes, os dois de `0` a `1`:
 
-| Opção | Afeta | `0.1` significa |
-| --- | --- | --- |
-| `sampleRate` | [eventos](#evento) (`captureException`, `captureMessage`) | ~10% dos erros são enviados |
+| Opção              | Afeta                                                         | `0.1` significa                    |
+| ------------------ | ------------------------------------------------------------- | ---------------------------------- |
+| `sampleRate`       | [eventos](#evento) (`captureException`, `captureMessage`)     | ~10% dos erros são enviados        |
 | `tracesSampleRate` | [transactions](#transaction) abertas por `startTransaction()` | ~10% das transactions são enviadas |
 
 O sorteio é por item, no momento em que ele é criado — nunca "1 a cada 10", e sim 10% de chance cada.
@@ -319,7 +319,7 @@ Detalhes que importam:
 
 O **heartbeat** é um batimento periódico dizendo "estou vivo". O servidor conhece a cadência esperada e marca a instância como **offline** quando os batimentos param.
 
-É o complemento do [check-in](#check-in): check-in vigia *execuções agendadas*, heartbeat vigia *o processo*. Um robô que fica de plantão esperando trabalho não tem cron para monitorar — mas você ainda quer saber quando a VM dele caiu.
+É o complemento do [check-in](#check-in): check-in vigia _execuções agendadas_, heartbeat vigia _o processo_. Um robô que fica de plantão esperando trabalho não tem cron para monitorar — mas você ainda quer saber quando a VM dele caiu.
 
 ```js
 Hobots.init({
@@ -350,8 +350,8 @@ O que o torna especial é que ele é a identidade dos **dois** canais ao mesmo t
 
 Servem a duas perguntas concretas:
 
-- *"quebrou desde quando?"* — com `release`, você compara o antes e o depois de um deploy e sabe qual versão introduziu o erro.
-- *"isso é real ou é teste?"* — com `environment`, o ruído da homologação não polui os alertas de produção.
+- _"quebrou desde quando?"_ — com `release`, você compara o antes e o depois de um deploy e sabe qual versão introduziu o erro.
+- _"isso é real ou é teste?"_ — com `environment`, o ruído da homologação não polui os alertas de produção.
 
 `environment` default é `production`. Se você roda homologação sem definir isso, os dois ambientes se misturam na mesma issue — vale configurar no primeiro dia.
 
@@ -424,9 +424,9 @@ Defaults e tempos dos dois: [Tempos e intervalos](./api-reference.md#tempos-e-in
 Hobots.init({
   clientSecret,
   instanceId: 'vm-cliente-01',
-  beforeSend: (event) => {
+  beforeSend: event => {
     if (event.exception?.type === 'AbortError') return null; // não me interessa
-    delete event.extra?.senha;                                // censura
+    delete event.extra?.senha; // censura
     return event;
   },
 });

package/docs/getting-started.md

@@ -29,7 +29,7 @@ Cada projeto tem **um único Client Secret** — a mesma credencial autentica o
 hb_<64 hex>
 ```
 
-(Chaves antigas, 64 hex puros, continuam válidas no servidor.) A credencial é **secreta** e viaja sempre no header `Authorization: Bearer` — nunca na URL. Copie o Client Secret no app, em **Configurações → Projetos** — os snippets de integração já vêm prontos.
+A credencial é **secreta** e viaja sempre no header `Authorization: Bearer` — nunca na URL. Copie o Client Secret no app, em **Configurações → Projetos** — os snippets de integração já vêm prontos.
 
 O SDK fala com a API oficial `https://api2.hobots.app` automaticamente — não há configuração de host no `init()`. Em desenvolvimento, aponte para outro host com a env `HOBOTS_API_URL`:
 

package/docs/protocol.md

@@ -17,9 +17,7 @@ hb_<64 hex>
 | Monitor (ingestão) | `POST <baseUrl>/v1/ingest` | `Authorization: Bearer <clientSecret>` |
 | Manager (execução) | `<baseUrl>/v1/manager/*` | `Authorization: Bearer <clientSecret>` |
 
-`resolveConfig({ clientSecret }) → { key, baseUrl, ingestEndpoint, managerBaseUrl }` (em `src/config.ts`, com a constante `DEFAULT_BASE_URL = 'https://api2.hobots.app'`; em desenvolvimento a env `HOBOTS_API_URL` sobrescreve a URL base). A credencial é **secreta** (formato `hb_<64 hex>`; chaves antigas de 64 hex puros continuam válidas no servidor) e viaja **só no header** `Authorization: Bearer` — nunca na URL da requisição.
-
-> As DSNs foram **descontinuadas** em favor do Client Secret — tanto a antiga do Monitor (public key na URL, `POST /v1/ingest/<key>`, que responde **410** e o transport descarta sem retry) quanto a de key-na-URL (`https://<secretKey>@host/<slug>`). Copie o Client Secret em **Configurações → Projetos** no app.
+`resolveConfig({ clientSecret }) → { key, baseUrl, ingestEndpoint, managerBaseUrl }` (em `src/config.ts`, com a constante `DEFAULT_BASE_URL = 'https://api2.hobots.app'`; em desenvolvimento a env `HOBOTS_API_URL` sobrescreve a URL base — apenas `http(s)`, e `http` para host fora de loopback gera aviso porque o secret trafega sem TLS). A credencial é **secreta** (formato `hb_<64 hex>`) e viaja **só no header** `Authorization: Bearer` — nunca na URL da requisição.
 
 ## Monitor — ingestão
 
@@ -88,7 +86,7 @@ Corpo `ManagerRunUpdateRequest`:
 - Ordem garantida `running → logs → terminal` (PATCHes serializados numa cadeia de promise).
 - Retry `[1s, 4s, 16s]`; 4xx exceto 429 é terminal (**409** = run cancelada / transição inválida → marca a run como morta e dispara `ctx.signal`).
 - Todo PATCH atualiza `last_report_at` no servidor (relógio do servidor) — é o **sinal de vida da run**. O heartbeat de cancelamento (PATCH `running` vazio a cada `cancelCheckIntervalMs`, máx 15s) garante reporte contínuo; um sweep server-side marca como `failed` com erro `AgentTerminated` ("execução encerrada inesperadamente") toda run `running` sem reporte há **60s**, sem re-entrega. No exit path (sinal/erro fatal com runs ativas), o SDK envia um único PATCH `failed`/`AgentTerminated` com timeout curto (~2s), sem retry — o sweep é o backstop.
-- O protocolo **não transporta resultado** de execução: o retorno do handler é ignorado pelo SDK e o servidor descarta qualquer campo `result` de SDKs antigos (dados de negócio podem ser sensíveis e não são coletados).
+- O protocolo **não transporta resultado** de execução: o retorno do handler é ignorado pelo SDK e o servidor descarta qualquer campo `result` (dados de negócio podem ser sensíveis e não são coletados).
 
 Ciclo de vida completo da run no servidor: `pending → claimed → running → succeeded | failed | canceled`. O agente só transiciona para `running`/`succeeded`/`failed`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hobots",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "SDK JavaScript da Hobots — captura de erros, transactions, check-ins de cron e heartbeats (Monitor) e execução remota de tarefas sob demanda (Manager) para RPAs e integrações. Um único import e um único init().",
   "type": "module",
   "sideEffects": false,
@@ -36,6 +36,7 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "lint": "eslint . --max-warnings 0",
+    "test": "node --test \"test/**/*.test.mjs\"",
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {