hobots 1.6.0 → 1.7.0

package/README.md

@@ -2,10 +2,10 @@
 
 SDK JavaScript/TypeScript da **Hobots** para instrumentar funcionários digitais (RPAs) e integrações.
 
-- **Monitor** — telemetria que o programa **emite** sozinho: erros com stack trace, performance (transactions/spans), check-ins de cron e heartbeats de uptime.
-- **Manager** — execução **sob demanda**: o agente faz polling no app da Hobots, executa handlers registrados e reporta status e logs.
+- **Telemetria** — o que o programa **emite** sozinho: erros com stack trace (módulo **Issues** do app), performance (transactions/spans) e heartbeats de uptime (módulo **Agentes**), check-ins de cron (módulo **Monitores**).
+- **Tasks** — execução **sob demanda**: o agente faz polling no app da Hobots, executa handlers registrados e reporta status e logs (módulo **Solicitações**).
 
-**Um único import e um único `init()`** cobrem as duas capabilities. Cliente HTTP puro, **sem dependências de runtime**. Requer **Node 18+** (usa o `fetch` global); o Monitor também roda no browser para captura de erros.
+**Um único import e um único `init()`** cobrem as duas capabilities. Cliente HTTP puro, **sem dependências de runtime**. Requer **Node 18+** (usa o `fetch` global); a telemetria também roda no browser para captura de erros.
 
 ---
 
@@ -17,7 +17,7 @@ npm install hobots
 ```
 
 ```js
-import * as Hobots from 'hobots'; // um import só — Monitor e Manager
+import * as Hobots from 'hobots'; // um import só — telemetria e tasks
 ```
 
 Também funciona em CommonJS: `const Hobots = require('hobots')`.
@@ -30,21 +30,21 @@ O SDK expõe **duas capabilities** autenticadas pelo **mesmo Client Secret do pr
 
 | Capability | Como habilita | Para quê | Ciclo de vida |
 | --- | --- | --- | --- |
-| **Monitor** | sempre ativo no `init()` | Telemetria emitida pelo próprio programa: erros, transactions/spans, crons, heartbeat. | Timers `unref`'d — **não** segura o processo. Chame `close()` no fim. |
-| **Manager** | `manager: true` (ou opções) no `init()` | Execução remota sob demanda via polling. | `start()` **segura o processo vivo** até `stop()`/`close()`. |
+| **Telemetria** | sempre ativa no `init()` | O que o programa emite sozinho: erros, transactions/spans, crons, heartbeat. | Timers `unref`'d — **não** segura o processo. Chame `close()` no fim. |
+| **Tasks** | `tasks: true` (ou opções) no `init()` | Execução remota sob demanda via polling. | `start()` **segura o processo vivo** até `stop()`/`close()`. |
 
 Você usa **uma, outra ou as duas**:
 
 - Só saber se o robô quebrou, quanto demora e se está vivo? → `init({ clientSecret, heartbeat: true })`.
-- Disparar o robô sob demanda a partir de um formulário no app? → `init({ clientSecret, manager: true })` + `register()` + `start()`.
-- Ambos? Passe `heartbeat` e `manager` no mesmo `init()` — o `instanceId` é a identidade única, e os dois canais convergem em **um agente** no painel.
+- Disparar o robô sob demanda a partir de um formulário no app? → `init({ clientSecret, tasks: true })` + `register()` + `start()`.
+- Ambos? Passe `heartbeat` e `tasks` no mesmo `init()` — o `instanceId` é a identidade única, e os dois canais convergem em **um agente** no painel. Com `tasks: true`, o heartbeat é **opcional**: o próprio poll de tasks já marca a presença do agente.
 
 ```js
 Hobots.init({
   clientSecret: 'hb_<64 hex>',
   instanceId: 'vm-cliente-01',
-  heartbeat: true,                              // Monitor: "estou vivo" a cada 30s
-  manager: { pollIntervalMs: 5_000 },           // Manager: execução sob demanda
+  heartbeat: true,                              // telemetria: "estou vivo" a cada 30s
+  tasks: { pollIntervalMs: 5_000 },             // execução sob demanda
 });
 
 Hobots.register('processar-nfe', async (params, ctx) => {
@@ -52,14 +52,14 @@ Hobots.register('processar-nfe', async (params, ctx) => {
   ctx.log.info('12 notas processadas'); // o retorno do handler é ignorado — reporte por log
 });
 
-Hobots.start(); // inicia o polling do Manager (segura o processo vivo)
+Hobots.start(); // inicia o polling de tasks (segura o processo vivo)
 ```
 
 ---
 
 ## O Client Secret
 
-Cada projeto tem **um único Client Secret** — a mesma credencial autentica o Monitor **e** o Manager:
+Cada projeto tem **um único Client Secret** — a mesma credencial autentica a telemetria **e** as tasks:
 
 ```
 hb_<64 hex>
@@ -69,7 +69,7 @@ A credencial é **secreta** e viaja sempre no header `Authorization: Bearer` —
 
 ---
 
-## Monitor
+## Telemetria
 
 Todas as funções abaixo são **no-op seguras** se `Hobots.init()` não foi chamado (com aviso no console).
 
@@ -93,14 +93,14 @@ Hobots.init({
 | `clientSecret` | `string` | **obrigatório** | o Client Secret do projeto (`hb_<64 hex>`), copiado em **Configurações → Projetos** |
 | `environment` | `string` | `'production'` | ambiente lógico |
 | `release` | `string` | — | versão do programa, ex. `robo-nfe@1.4.2` |
-| `instanceId` | `string` | **obrigatório** | identidade única da instância — heartbeat do Monitor e agente do Manager convergem nela |
+| `instanceId` | `string` | **obrigatório** | identidade única da instância — heartbeat e poll de tasks convergem nela |
 | `tags` | `Record<string,string>` | — | tags aplicadas a todos os eventos |
 | `sampleRate` | `number` | `1` | amostragem de erros (0..1) |
 | `tracesSampleRate` | `number` | `1` | amostragem de transactions (0..1) |
 | `maxBreadcrumbs` | `number` | `100` | tamanho do buffer de breadcrumbs |
 | `captureUnhandled` | `boolean` | `true` | handlers globais de erro (`uncaughtException`/`unhandledRejection`) |
 | `heartbeat` | `boolean \| HeartbeatOptions` | `false` | heartbeat periódico (`true` usa defaults) |
-| `manager` | `boolean \| ManagerOptions` | `false` | habilita o agente Manager (`true` usa defaults) — veja [Manager](#manager) |
+| `tasks` | `boolean \| TasksOptions` | `false` | habilita a execução sob demanda (`true` usa defaults) — veja [Tasks](#tasks-execução-sob-demanda) |
 | `beforeSend` | `(event) => event \| null` | — | edita/descarta evento (retorne `null` para descartar) |
 | `debug` | `boolean` | `false` | loga atividade do SDK |
 | `flushIntervalMs` | `number` | `2000` | intervalo do flush automático do transport |
@@ -123,7 +123,7 @@ try {
 Hobots.captureMessage('Lote processado com sucesso', 'success');
 ```
 
-Ambas retornam o `event_id` (ou `undefined` se não inicializado). O hint aceita `level`, `tags`, `extra` e `fingerprint`. Erros **não tratados** são capturados e flushados automaticamente antes do processo sair — desligue com `captureUnhandled: false`.
+Ambas retornam o `event_id` (ou `undefined` se não inicializado). O hint aceita `level`, `tags`, `extra` e `fingerprint`. Erros **não tratados** são capturados e flushados automaticamente antes do processo sair — desligue com `captureUnhandled: false`. Os eventos aparecem agrupados em issues no módulo **Issues** do app.
 
 `Severity = 'fatal' | 'error' | 'warning' | 'info' | 'debug' | 'success'`. Use `'success'` para reportar itens concluídos com êxito — contam como eventos, mas **não** viram issue nem disparam alertas.
 
@@ -179,11 +179,11 @@ tx.finish();         // só aqui a transaction é enviada (respeitando tracesSam
 - Métodos encadeáveis: `setStatus`, `setData` (span), `setTag`/`setName` (transaction).
 - `finish()` na transaction fecha os spans abertos e envia o payload; nada é enviado se ela não foi amostrada. A amostragem é decidida no `startTransaction()`.
 
-Dentro de um handler do Manager não abra transaction — já existe uma em `ctx.tx`. Conceitos: [Transaction](./docs/concepts.md#transaction) · [Span](./docs/concepts.md#span).
+Dentro de um handler de task, `startTransaction()` **retorna a transaction da própria run** (`ctx.tx`) em vez de criar uma segunda — cada execução tem exatamente **uma** transaction. Conceitos: [Transaction](./docs/concepts.md#transaction) · [Span](./docs/concepts.md#span).
 
 ### Crons (check-ins)
 
-Monitora jobs agendados: check-in `in_progress` na entrada, `ok`/`error` na saída, com duração medida. O jeito recomendado é `withMonitor`, que faz o par e captura exceções:
+Monitora jobs agendados no módulo **Monitores** do app: check-in `in_progress` na entrada, `ok`/`error` na saída, com duração medida. O jeito recomendado é `withMonitor`, que faz o par e captura exceções:
 
 ```js
 await Hobots.withMonitor(
@@ -212,7 +212,9 @@ Hobots.init({
 });
 ```
 
-`heartbeat: true` usa os defaults. A identidade é o `instanceId` do `init()`; os campos são `intervalMs`, `name` (default: o `instanceId`) e `metadata` — valores em [Tempos e intervalos](./docs/api-reference.md#tempos-e-intervalos). O primeiro batimento sai **na hora** em que o `init()` roda, não depois do primeiro intervalo. Conceito: [Heartbeat](./docs/concepts.md#heartbeat).
+`heartbeat: true` usa os defaults. A identidade é o `instanceId` do `init()`; os campos são `intervalMs`, `name` (default: o `instanceId`) e `metadata` — valores em [Tempos e intervalos](./docs/api-reference.md#tempos-e-intervalos). O primeiro batimento sai **na hora** em que o `init()` roda, não depois do primeiro intervalo.
+
+O heartbeat é **essencial** para agentes só de telemetria; com `tasks: true` ele é **opcional**, porque o poll de tasks já marca a presença do agente no painel. Conceito: [Heartbeat](./docs/concepts.md#heartbeat).
 
 ### Flush e close
 
@@ -221,13 +223,13 @@ await Hobots.flush(2000); // envia o buffer, mantém o SDK vivo
 await Hobots.close(2000); // flush final + para o heartbeat + fecha o transport
 ```
 
-Chame `close` antes do processo sair. Os timers do Monitor são `unref`'d — ele **não** segura o processo vivo sozinho.
+Chame `close` antes do processo sair. Os timers da telemetria são `unref`'d — ela **não** segura o processo vivo sozinha.
 
 ---
 
-## Manager
+## Tasks (execução sob demanda)
 
-Capability de **execução remota sob demanda**, habilitada com `manager: true` (ou opções) no `init()`. O agente faz polling no app, executa os handlers registrados quando aparece trabalho e reporta status e logs incrementais. Mesmo Client Secret, mesmo `debug` e o `instanceId` como identidade — nenhum handler global extra é instalado.
+Capability de **execução remota sob demanda**, habilitada com `tasks: true` (ou opções) no `init()`. O agente faz polling no app, executa os handlers registrados quando aparece trabalho e reporta status e logs incrementais — cada execução aparece no módulo **Solicitações** do app. Mesmo Client Secret, mesmo `debug` e o `instanceId` como identidade — nenhum handler global extra é instalado.
 
 ### Ciclo de vida
 
@@ -235,7 +237,7 @@ Capability de **execução remota sob demanda**, habilitada com `manager: true`
 Hobots.init({
   clientSecret: 'hb_<64 hex>',
   instanceId: 'vm-cliente-01',
-  manager: true, // ou { pollIntervalMs, concurrency, ... }
+  tasks: true, // ou { pollIntervalMs, concurrency, ... }
 });
 
 Hobots.register('processar-nfe', async (params, ctx) => {
@@ -251,13 +253,13 @@ process.on('SIGINT', () => {
 });
 ```
 
-- `init({ manager })` — cria o agente. Chamar `init()` de novo para o agente anterior e o substitui (o registry de handlers é preservado).
-- `register(task, handler)` — `task` é o `task_slug` configurado no formulário do app. Registre **antes** de `start()`. Funciona até antes do `init()`; com o Manager desabilitado, avisa no console.
-- `start()` — começa o polling. Lança se o `init()` não configurou `manager` ou se nenhuma task foi registrada.
-- `stop(timeoutMs?)` — para **só o Manager**: encerra o polling e aguarda as runs ativas (default 30s); a telemetria continua. Retorna `false` se estourou o timeout.
+- `init({ tasks })` — cria o agente. Chamar `init()` de novo para o agente anterior e o substitui (o registry de handlers é preservado).
+- `register(task, handler)` — `task` é o `task_slug` configurado no formulário do app (**Configurações → Formulários**). Registre **antes** de `start()`. Funciona até antes do `init()`; com as tasks desabilitadas, avisa no console.
+- `start()` — começa o polling. Lança se o `init()` não configurou `tasks` ou se nenhuma task foi registrada.
+- `stop(timeoutMs?)` — para **só o polling de tasks**: encerra o polling e aguarda as runs ativas (default 30s); a telemetria continua. Retorna `false` se estourou o timeout.
 - `close(timeoutMs?)` — encerra **tudo**: agente (aguardando runs em voo) → heartbeat → flush final do transport.
 
-| Opção (`ManagerOptions`) | Tipo | Default | Descrição |
+| Opção (`TasksOptions`) | Tipo | Default | Descrição |
 | --- | --- | --- | --- |
 | `pollIntervalMs` | `number` | `5000` | intervalo entre polls sem trabalho (mínimo `1000`) |
 | `concurrency` | `number` | `1` | runs simultâneas (clamp 1..5) |
@@ -266,18 +268,18 @@ process.on('SIGINT', () => {
 | `cancelCheckIntervalMs` | `number` | `5000` | heartbeat de cancelamento por run (clamp 1000..15000) — também é o sinal de vida da run |
 | `installExitHandlers` | `boolean` | `true` | handlers de SIGINT/SIGTERM/uncaughtException que reportam as runs ativas como `AgentTerminated` antes do processo morrer; nunca interferem quando o programa tem handler próprio |
 
-O Client Secret, o `debug` e a identidade do agente (`instanceId`) vêm do `init()` — o heartbeat do Monitor e o agente do Manager convergem em **um agente** no painel automaticamente.
+O Client Secret, o `debug` e a identidade do agente (`instanceId`) vêm do `init()` — o heartbeat e o poll de tasks convergem em **um agente** no painel automaticamente.
 
 ### O handler e o `RunContext`
 
 ```ts
-type ManagerTaskHandler<P = Record<string, unknown>> =
+type TaskHandler<P = Record<string, unknown>> =
   (params: P, ctx: RunContext) => void | Promise<void>;
 
 interface RunContext {
   runId: string;
   task: string;
-  log(level: 'debug' | 'info' | 'warning' | 'error', message: string): void;
+  log: RunLogger; // ctx.log.debug/info/warn/error/success(message)
   tx: Transaction; // transaction desta run — correlacionada e finalizada pelo SDK
   signal: AbortSignal;
   throwIfCanceled(): void; // lança RunCanceled se o signal já disparou
@@ -286,15 +288,15 @@ interface RunContext {
 ```
 
 - **`params`** — os dados do formulário configurado no app (JSON validado). Tipável: `Hobots.register<{ lote: number }>(...)`.
-- **`ctx.log.<level>(message)`** — logs enviados **incrementalmente** ao app (PATCHes com throttle), visíveis na run quase em tempo real; também impressos no terminal local, coloridos por nível.
-- **`ctx.tx`** — a transaction de performance desta run, já correlacionada e finalizada pelo SDK. Use `ctx.tx.startChild(op, description)` para medir as etapas — elas viram o waterfall da execução no app. Conceito: [ctx.tx](./docs/concepts.md#transaction-de-run-ctxtx).
+- **`ctx.log.<level>(message)`** — níveis `debug`, `info`, `warn`, `error` e `success`; logs enviados **incrementalmente** ao app (PATCHes com throttle), visíveis na solicitação quase em tempo real; também impressos no terminal local, coloridos por nível.
+- **`ctx.tx`** — a transaction de performance desta run, já correlacionada e finalizada pelo SDK. Use `ctx.tx.startChild(op, description)` para medir as etapas — elas viram o waterfall da execução no app. `startTransaction()` chamado dentro do handler retorna essa mesma transaction. Conceito: [ctx.tx](./docs/concepts.md#transaction-de-run-ctxtx).
 - **`ctx.signal`** — `AbortSignal` que dispara quando a run é **cancelada no app**, em **timeout** ou no **shutdown**.
 - **`ctx.throwIfCanceled()`** — o ponto de parada de uma linha; lança `RunCanceled` se o `signal` já disparou.
 - **`ctx.sleep(ms)`** — espera que respeita o `signal` (rejeita com `RunCanceled` em vez de dormir até o fim).
 - **Retorno** — **ignorado**: o SDK não captura nem envia o valor retornado pelo handler (resultados podem conter dados sensíveis e não são coletados).
 - **Erro lançado** — a run é reportada como `failed` (mensagem cap 10k, stack 20k).
 
-> **Dados sensíveis:** `ctx.log()` e mensagens/stack de erros **são enviados ao servidor** e ficam visíveis no app. Não inclua senhas, tokens, dados pessoais ou qualquer informação sensível em logs e mensagens de erro.
+> **Dados sensíveis:** `ctx.log` e mensagens/stack de erros **são enviados ao servidor** e ficam visíveis no app. Não inclua senhas, tokens, dados pessoais ou qualquer informação sensível em logs e mensagens de erro.
 
 ### Cancelamento cooperativo
 
@@ -331,13 +333,13 @@ Ainda assim, escreva handlers **idempotentes**: a janela de re-entrega pós-clai
 
 ## Encerramento gracioso
 
-`close(timeoutMs?)` encerra tudo na ordem certa: para o Manager (aguardando a run atual), para o heartbeat e faz o flush final do transport.
+`close(timeoutMs?)` encerra tudo na ordem certa: para o polling de tasks (aguardando a run atual), para o heartbeat e faz o flush final do transport.
 
 ```js
-// só Monitor: não segura o processo, mas faça o flush final para não perder eventos
+// só telemetria: não segura o processo, mas faça o flush final para não perder eventos
 await Hobots.close(2_000);
 
-// com Manager: segura o processo por design — aguarde a run atual
+// com tasks: segura o processo por design — aguarde a run atual
 process.on('SIGINT', () => {
   void Hobots.close(15_000).then(() => process.exit(0));
 });
@@ -351,8 +353,8 @@ Para parar de aceitar execuções **sem** derrubar a telemetria, use `stop(timeo
 
 | Import | Conteúdo |
 | --- | --- |
-| `hobots` | Tudo: `init`, Monitor (captura, transactions, crons, heartbeat), Manager (`register`/`start`/`stop`), `close`, classes e tipos. |
-| `hobots/protocol` | Tipos do wire format (Monitor e Manager). |
+| `hobots` | Tudo: `init`, telemetria (captura, transactions, crons, heartbeat), tasks (`register`/`start`/`stop`), `close`, classes e tipos. |
+| `hobots/protocol` | Tipos do wire format (telemetria e tasks). |
 
 Empacotado em **ESM e CommonJS** com **definições de tipos** (`.d.ts`) para todas as entradas.
 
@@ -365,9 +367,9 @@ Guias detalhados acompanham o pacote em [`docs/`](./docs/README.md).
 Novo no vocabulário de observabilidade (transaction, span, breadcrumb, tag, context, extra, flush, close)? Comece por [Conceitos](./docs/concepts.md) — as outras páginas assumem esses termos.
 
 - [Conceitos](./docs/concepts.md) — o que cada coisa é, por que existe e quando escolher uma em vez da outra.
-- [Getting started](./docs/getting-started.md) — instalação, Client Secret, primeiro `init`, Monitor e Manager.
-- [Monitor](./docs/monitor.md) — erros, breadcrumbs, escopo, transactions/spans, crons, heartbeat.
-- [Manager](./docs/manager.md) — handlers, `RunContext`, cancelamento, concorrência, idempotência.
+- [Getting started](./docs/getting-started.md) — instalação, Client Secret, primeiro `init`, telemetria e tasks.
+- [Telemetria](./docs/monitor.md) — erros, breadcrumbs, escopo, transactions/spans, crons, heartbeat.
+- [Tasks](./docs/tasks.md) — handlers, `RunContext`, cancelamento, concorrência, idempotência.
 - [Referência de API](./docs/api-reference.md) — todas as funções e tabelas de opções com defaults.
 - [Protocolo & transporte](./docs/protocol.md) — o Client Secret, endpoints, envelope, retries.