hobots 0.3.1 → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hobots
+
+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

@@ -0,0 +1,389 @@
+# hobots
+
+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.
+
+**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.
+
+---
+
+## Instalação
+
+```bash
+npm install hobots
+# ou: pnpm add hobots · yarn add hobots
+```
+
+```js
+import * as Hobots from 'hobots'; // um import só — Monitor e Manager
+```
+
+Também funciona em CommonJS: `const Hobots = require('hobots')`.
+
+---
+
+## Um SDK, duas capabilities, um `init()`
+
+O SDK expõe **duas capabilities** autenticadas pela **mesma DSN única do projeto**, configuradas em um único `init()`:
+
+| 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()`. |
+
+Você usa **uma, outra ou as duas**:
+
+- Só saber se o robô quebrou, quanto demora e se está vivo? → `init({ dsn, heartbeat: true })`.
+- Disparar o robô sob demanda a partir de um formulário no app? → `init({ dsn, 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.
+
+```js
+Hobots.init({
+  dsn: 'https://<secretKey>@<host>/<projectSlug>',
+  instanceId: 'vm-cliente-01',
+  heartbeat: true,                              // Monitor: "estou vivo" a cada 30s
+  manager: { pollIntervalMs: 5_000 },           // Manager: execução sob demanda
+});
+
+Hobots.register('processar-nfe', async (params, ctx) => {
+  ctx.log('info', 'começando…');
+  return { processadas: 12 };
+});
+
+Hobots.start(); // inicia o polling do Manager (segura o processo vivo)
+```
+
+---
+
+## O DSN
+
+Cada projeto tem **uma única DSN** — a mesma credencial autentica o Monitor **e** o Manager:
+
+```
+https://<secretKey>@<host>/<projectSlug>
+```
+
+A `secretKey` (64 hex) é **secreta**: vai embutida na DSN só por conveniência — nas requisições viaja sempre no header `Authorization: Bearer`, nunca na URL. O `projectSlug` do path é informativo; a identidade do projeto vem da chave. Copie a DSN pronta no app, em **Configurações → Agentes** — os snippets de integração já vêm prontos.
+
+---
+
+## Monitor
+
+Todas as funções abaixo são **no-op seguras** se `Hobots.init()` não foi chamado (com aviso no console).
+
+### `init(options)`
+
+Inicialize **uma vez**, o mais cedo possível no processo. Cria o cliente, instala handlers globais de erro (a menos que `captureUnhandled: false`) e inicia o heartbeat se configurado.
+
+```js
+Hobots.init({
+  dsn: 'https://<secretKey>@<host>/<projectSlug>',
+  environment: 'production',
+  release: 'robo-nfe@1.4.2',
+  instanceId: 'vm-cliente-01',
+  tags: { squad: 'automacoes' },
+  heartbeat: true, // "estou vivo" a cada 30s
+});
+```
+
+| Opção | Tipo | Default | Descrição |
+| --- | --- | --- | --- |
+| `dsn` | `string` | **obrigatório** | a DSN única do projeto: `https://<secretKey>@host/<projectSlug>` |
+| `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 |
+| `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) |
+| `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 |
+| `maxBatchSize` | `number` | `10` | itens por envelope antes do flush imediato |
+
+### Captura de erros e mensagens
+
+```js
+try {
+  await processarNota(nota);
+} catch (error) {
+  Hobots.captureException(error, {
+    level: 'error',
+    tags: { cliente: 'acme' },
+    fingerprint: ['sefaz-timeout'], // agrupa manualmente; sem isso o servidor agrupa pelo stack
+  });
+  throw error;
+}
+
+Hobots.captureMessage('Lote processado com sucesso', 'info');
+```
+
+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`.
+
+`Severity = 'fatal' | 'error' | 'warning' | 'info' | 'debug'`.
+
+### Breadcrumbs
+
+Trilha do que aconteceu antes do erro; enviada junto do próximo evento (buffer limitado por `maxBreadcrumbs`, mais antigos descartados).
+
+```js
+Hobots.addBreadcrumb({ category: 'nfe', message: 'Baixou XML da nota 123', level: 'info' });
+```
+
+### Escopo: tags, usuário, contexto, extras
+
+Dados anexados a **todos** os eventos seguintes:
+
+```js
+Hobots.setTag('regiao', 'nordeste');
+Hobots.setTags({ squad: 'automacoes', cliente: 'acme' });
+Hobots.setUser({ id: 'op-42', email: 'op@acme.com' });
+Hobots.setContext('vm', { cpu: 4, ram: '8GB' });
+Hobots.setExtra('ultimoLote', 128);
+```
+
+Para um escopo **isolado** (sem vazar para o global), use `withScope`:
+
+```js
+Hobots.withScope((scope) => {
+  scope.setTag('lote', '128').setFingerprint(['reprocessamento']);
+  Hobots.captureMessage('Reprocessando lote 128');
+});
+```
+
+### Performance: transactions e spans
+
+```js
+const tx = Hobots.startTransaction('processar-lote', 'rpa.job');
+
+const span = tx.startChild('http.client', 'GET /api/notas');
+await api.buscarNotas();
+span.setData('notas', 42).finish();
+
+const filho = span.startChild('db.query', 'INSERT INTO notas'); // spans aninham
+await gravar();
+filho.finish();
+
+tx.setStatus('ok');  // ou 'error'
+tx.finish();         // só aqui a transaction é enviada (respeitando tracesSampleRate)
+```
+
+- `startChild(op?, description?)` existe em `Transaction` **e** `Span` (aninhamento arbitrário).
+- 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.
+
+### 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:
+
+```js
+await Hobots.withMonitor(
+  'sync-notas',
+  () => executarSync(),
+  { schedule: '0 */2 * * *', timezone: 'America/Fortaleza' }
+);
+```
+
+O `schedule` (expressão cron) faz o servidor **criar/atualizar o monitor automaticamente** (upsert) e habilita a detecção de **execução perdida**. Para controle manual:
+
+```js
+const id = Hobots.checkIn({ monitorSlug: 'sync-notas', status: 'in_progress' });
+// … trabalho …
+Hobots.checkIn({ monitorSlug: 'sync-notas', status: 'ok', checkInId: id, durationMs: 1234 });
+```
+
+### Heartbeat (uptime)
+
+Bate "estou vivo" periodicamente; o servidor acusa o robô **offline** quando os batimentos param.
+
+```js
+Hobots.init({
+  dsn,
+  heartbeat: { intervalMs: 30_000, name: 'Robô NFe — VM 01' },
+});
+```
+
+`heartbeat: true` usa os defaults. A identidade é o `instanceId` do `init()`. Campos: `intervalMs` (30000), `name` (default: o `instanceId`), `metadata`.
+
+### Flush e close
+
+```js
+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.
+
+---
+
+## Manager
+
+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. Mesma DSN, mesmo `debug` e o `instanceId` como identidade — nenhum handler global extra é instalado.
+
+### Ciclo de vida
+
+```js
+Hobots.init({
+  dsn: 'https://<secretKey>@<host>/<projectSlug>',
+  instanceId: 'vm-cliente-01',
+  manager: true, // ou { pollIntervalMs, concurrency, ... }
+});
+
+Hobots.register('processar-nfe', async (params, ctx) => {
+  ctx.log('info', `processando lote ${params.lote}…`);
+  if (ctx.signal.aborted) return;   // cancelamento cooperativo
+  ctx.log('info', '12 notas processadas');
+});
+
+Hobots.start(); // começa o polling e MANTÉM O PROCESSO VIVO
+
+process.on('SIGINT', () => {
+  void Hobots.close(15_000).then(() => process.exit(0));
+});
+```
+
+- `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.
+- `close(timeoutMs?)` — encerra **tudo**: agente (aguardando runs em voo) → heartbeat → flush final do transport.
+
+| Opção (`ManagerOptions`) | Tipo | Default | Descrição |
+| --- | --- | --- | --- |
+| `pollIntervalMs` | `number` | `5000` | intervalo entre polls sem trabalho (mínimo `1000`) |
+| `concurrency` | `number` | `1` | runs simultâneas (clamp 1..5) |
+| `taskTimeoutMs` | `number` | — | timeout client-side por run (não mata o handler; servidor é o backstop) |
+| `logFlushIntervalMs` | `number` | `2000` | intervalo do envio incremental de logs |
+
+A DSN, 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 handler e o `RunContext`
+
+```ts
+type ManagerTaskHandler<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;
+  signal: AbortSignal;
+}
+```
+
+- **`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.
+- **`ctx.signal`** — `AbortSignal` que dispara quando a run é **cancelada no app**, em **timeout** ou no **shutdown**.
+- **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.
+
+### Cancelamento cooperativo
+
+Uma run cancelada no app **não mata** o handler — o SDK apenas dispara `ctx.signal`. **Verifique `ctx.signal.aborted`** em loops longos:
+
+```js
+Hobots.register('processar-nfe', async (params, ctx) => {
+  for (const nota of params.notas) {
+    if (ctx.signal.aborted) {
+      ctx.log('warning', 'cancelamento detectado — parando');
+      return;
+    }
+    await processar(nota);
+  }
+});
+```
+
+### Concorrência
+
+`concurrency` (default 1, máx 5) controla quantas runs o agente executa em paralelo. Com 1, as runs são sequenciais. O agente só reivindica o que consegue rodar (`max = concurrency - runs ativas`) e entra em **drain mode**: re-pesquisa imediatamente enquanto vem trabalho; quando não vem, espera `pollIntervalMs`.
+
+### Timeout por run
+
+`taskTimeoutMs` é **client-side**. No estouro o SDK **não mata** o handler — dispara `ctx.signal`, libera o slot e reporta a run como falha (`TaskTimeout`). Respeite o `signal` para parar de verdade. Sem ele, o backstop é o servidor.
+
+### Idempotência (at-least-once)
+
+A entrega é **at-least-once**: se o agente morre logo após capturar uma run (antes de reportar a conclusão), ela é re-entregue quando o agente voltar. Escreva handlers **idempotentes** (use uma chave de deduplicação sua, como o número da nota).
+
+---
+
+## 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.
+
+```js
+// só Monitor: 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
+process.on('SIGINT', () => {
+  void Hobots.close(15_000).then(() => process.exit(0));
+});
+```
+
+Para parar de aceitar execuções **sem** derrubar a telemetria, use `stop(timeoutMs?)`.
+
+---
+
+## Entry points / exports
+
+| 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). |
+
+Empacotado em **ESM e CommonJS** com **definições de tipos** (`.d.ts`) para todas as entradas. (`hobots/manager/protocol` segue existindo como alias transitório de tipos.)
+
+---
+
+## Migração 1.x → 2.x
+
+A 2.0 unifica o Manager no import raiz — `hobots/manager` **foi removido**:
+
+```diff
+-import * as Monitor from 'hobots';
+-import * as Manager from 'hobots/manager';
++import * as Hobots from 'hobots';
+
+-Monitor.init({ dsn, serverName: 'vm-01', heartbeat: true });
+-Manager.init({ dsn, agentName: 'vm-01' });
++Hobots.init({ dsn, instanceId: 'vm-01', heartbeat: true, manager: true });
+
+-Manager.register('minha-task', handler);
+-Manager.start();
++Hobots.register('minha-task', handler);
++Hobots.start();
+
+-await Manager.stop(15_000);
+-await Monitor.close(3_000);
++await Hobots.close(15_000);
+```
+
+- `agentName` e `serverName` não existem mais — a identidade do agente é o `instanceId` (obrigatório, sem fallback).
+- As opções do Manager (`pollIntervalMs`, `concurrency`, `taskTimeoutMs`, `logFlushIntervalMs`) vão no campo `manager` do `init()`; `dsn` e `debug` não se repetem.
+- Tipos (`ManagerTaskHandler`, `RunContext`, `ManagerOptions`) e classes (`ManagerAgent`, `ManagerApi`) agora vêm de `hobots`; o wire format vem de `hobots/protocol`.
+
+---
+
+## Documentação completa
+
+Guias detalhados acompanham o pacote em [`docs/`](./docs/README.md):
+
+- [Getting started](./docs/getting-started.md) — instalação, DSN, primeiro `init`, Monitor vs Hobots.
+- [Monitor](./docs/monitor.md) — erros, breadcrumbs, escopo, transactions/spans, crons, heartbeat.
+- [Manager](./docs/manager.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) — a DSN única, endpoints, envelope, retries.
+
+---
+
+## Licença
+
+[MIT](./LICENSE) © Hobots