hobots 0.3.1 → 1.1.0

package/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/docs/README.md

@@ -0,0 +1,41 @@
+# Documentação — hobots
+
+SDK JavaScript da **Hobots** para instrumentar funcionários digitais (RPAs) e integrações. Cliente HTTP puro, sem dependências de runtime, para Node 18+ (o Monitor também roda no browser para captura de erros).
+
+O SDK expõe **duas capabilities** autenticadas pela **mesma DSN única do projeto**, configuradas em **um único `init()`** com **um único import** (`import * as Hobots from 'hobots'`):
+
+| Capability | Como habilita | Para quê |
+| --- | --- | --- |
+| **Monitor** | sempre ativo no `init()` | Telemetria que o programa **emite** sozinho: erros com stack trace, performance (transactions/spans), check-ins de cron e heartbeats de uptime. Instala handlers globais de erro; os timers são `unref`'d, então nunca seguram o processo vivo. |
+| **Manager** | `manager: true` (ou opções) no `init()` | Execução **sob demanda**: o agente faz polling no app, executa handlers registrados e reporta status/logs. `start()` **mantém o processo vivo** até `stop()`/`close()`. |
+
+## Páginas
+
+- [Getting started](./getting-started.md) — instalação, DSN, o `init` único, Monitor e Manager.
+- [Monitor](./monitor.md) — erros, breadcrumbs, escopo, transactions/spans, crons e heartbeat.
+- [Manager](./manager.md) — registro de handlers, `RunContext`, cancelamento, concorrência, idempotência.
+- [Referência de API](./api-reference.md) — todas as funções e tabelas de opções com defaults.
+- [Protocolo & transporte](./protocol.md) — a DSN única, endpoints, envelope, retries e onde vive o claim atômico.
+
+## Exemplo mínimo
+
+```js
+import * as Hobots from 'hobots';
+
+// A DSN única do projeto — copie em Configurações → Agentes no app
+const dsn = 'http://<secretKey>@localhost:3002/<projectSlug>';
+
+// Um init só: telemetria sempre ativa; manager habilita a execução sob demanda.
+// O instanceId é a identidade única — o robô aparece como um agente só no painel.
+Hobots.init({ dsn, instanceId: 'vm-cliente-01', heartbeat: true, manager: true });
+
+Hobots.register('processar-nfe', async (params, ctx) => {
+  ctx.log('info', `processando lote ${params.lote}…`);
+  return { processadas: 12 };
+});
+Hobots.start(); // mantém o processo vivo aguardando execuções
+```
+
+> Exemplos runnable de toda a API pública (incluindo as duas capabilities juntas em
+> [`full.ts`](../../hobots-sdk-demos/src/full.ts)) estão em
+> [`packages/hobots-sdk-demos`](../../hobots-sdk-demos).

package/docs/api-reference.md

@@ -0,0 +1,153 @@
+# Referência de API
+
+## Entry points
+
+| Import | Conteúdo |
+| --- | --- |
+| `hobots` | Tudo: `init` único, funções do Monitor, `register`/`start`/`stop` do Manager, `close`, classes (`Client`, `Scope`, `Transaction`, `Span`, `ManagerAgent`, `ManagerApi`), `parseDsn` e tipos. |
+| `hobots/protocol` | Tipos do wire format (Monitor e Manager). |
+
+`hobots/manager/protocol` segue existindo como alias transitório dos tipos do wire format do Manager.
+
+---
+
+## Monitor — funções
+
+| Função | Assinatura | Retorno |
+| --- | --- | --- |
+| `init` | `init(options: InitOptions): void` | — |
+| `getClient` | `getClient(): Client \| undefined` | cliente atual |
+| `captureException` | `captureException(error: unknown, hint?: CaptureHint)` | `string \| undefined` (event_id) |
+| `captureMessage` | `captureMessage(message: string, level?: Severity, hint?: CaptureHint)` | `string \| undefined` |
+| `addBreadcrumb` | `addBreadcrumb(crumb: BreadcrumbInput): void` | — |
+| `setTag` / `setTags` | `setTag(key, value)` · `setTags(tags)` | — |
+| `setUser` | `setUser(user: EventUser \| null): void` | — |
+| `setContext` | `setContext(name: string, ctx: Record<string,unknown> \| null): void` | — |
+| `setExtra` | `setExtra(key: string, value: unknown): void` | — |
+| `withScope` | `withScope<T>(cb: (scope: Scope) => T): T` | retorno do callback |
+| `startTransaction` | `startTransaction(name: string, op?: string): Transaction` | transaction |
+| `checkIn` | `checkIn(options: CheckInOptions): string \| undefined` | check_in_id |
+| `withMonitor` | `withMonitor<T>(slug: string, fn: () => T \| Promise<T>, options?: WithMonitorOptions): Promise<T>` | retorno de `fn` |
+| `flush` | `flush(timeoutMs?: number): Promise<boolean>` | enviou tudo? |
+| `close` | `close(timeoutMs?: number): Promise<boolean>` | para o Manager (aguarda runs) + heartbeat + flush final do transport |
+
+Classes exportadas: `Client`, `Scope`, `Transaction`, `Span`. Função `parseDsn(dsn): ParsedDsn` — parseia a DSN única do projeto:
+
+```ts
+interface ParsedDsn {
+  key: string;            // chave secreta do projeto (vai no Authorization: Bearer, nunca na URL)
+  projectSlug: string;    // slug do projeto (informativo — a identidade real vem da chave)
+  origin: string;
+  ingestEndpoint: string; // <origin>/api/ingest
+  managerBaseUrl: string; // <origin>/api/manager
+}
+```
+
+### Métodos de `Transaction` / `Span`
+
+- `Transaction`: `startChild(op?, description?) → Span`, `setTag(k, v)`, `setStatus(s)`, `setName(n)`, `finish()`.
+- `Span`: `startChild(op?, description?) → Span`, `setStatus(s)`, `setData(k, v)`, `finish()`, `toJSON()`.
+- `Scope`: `setTag/setTags/setUser/setContext/setExtra/setExtras/setLevel/setFingerprint/addBreadcrumb/clearBreadcrumbs/clone` (todos encadeáveis).
+
+---
+
+## Manager — funções
+
+Habilitado com `manager: true` (ou `ManagerOptions`) no `init()` único. Todas exportadas do import raiz `hobots`:
+
+| Função | Assinatura |
+| --- | --- |
+| `register` | `register<P, R>(task: string, handler: ManagerTaskHandler<P, R>): void` |
+| `start` | `start(): void` — lança se o `init()` não configurou `manager` ou sem tasks registradas |
+| `stop` | `stop(timeoutMs?: number): Promise<boolean>` — para só o Manager; a telemetria continua |
+
+Classes/erros exportados: `ManagerAgent`, `ManagerApi`, `ManagerApiError`.
+
+No poll, o agente se identifica com `ManagerAgentInfo` (`hobots/protocol`): o campo `instance_id` (o `instanceId` do `init()`) é a identidade canônica do agente — a mesma do heartbeat do Monitor, então os dois canais convergem em um agente no painel.
+
+---
+
+## Tabelas de opções
+
+### InitOptions
+
+| 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 |
+| `heartbeat` | `boolean \| HeartbeatOptions` | `false` | heartbeat periódico |
+| `manager` | `boolean \| ManagerOptions` | `false` | habilita o agente Manager (`true` usa defaults) |
+| `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 |
+
+### HeartbeatOptions
+
+| Opção | Tipo | Default | Descrição |
+| --- | --- | --- | --- |
+| `intervalMs` | `number` | `30000` | intervalo entre batimentos |
+| `name` | `string` | o `instanceId` | nome amigável no dashboard |
+| `metadata` | `Record<string,unknown>` | — | metadados anexados ao batimento |
+
+### CaptureHint
+
+| Campo | Tipo | Descrição |
+| --- | --- | --- |
+| `level` | `Severity` | nível do evento |
+| `tags` | `Record<string,string>` | tags só deste evento |
+| `extra` | `Record<string,unknown>` | dados extras |
+| `fingerprint` | `string[]` | agrupamento manual |
+
+`Severity = 'fatal' | 'error' | 'warning' | 'info' | 'debug'`.
+
+### CheckInOptions
+
+| Campo | Tipo | Descrição |
+| --- | --- | --- |
+| `monitorSlug` | `string` | **obrigatório**; identifica o monitor |
+| `status` | `'in_progress' \| 'ok' \| 'error'` | **obrigatório** |
+| `checkInId` | `string` | reutilize o id do `in_progress` para fechar a execução |
+| `durationMs` | `number` | duração medida |
+| `schedule` | `string` | expressão cron — cria/atualiza o monitor no servidor (upsert) |
+| `timezone` | `string` | fuso do `schedule` |
+
+### WithMonitorOptions
+
+| Campo | Tipo | Descrição |
+| --- | --- | --- |
+| `schedule` | `string` | expressão cron (upsert do monitor) |
+| `timezone` | `string` | fuso do `schedule` |
+
+### ManagerOptions
+
+Valor do campo `manager` do `InitOptions`. A DSN, o `debug` e a identidade (`instanceId`) vêm do `init()`.
+
+| Opção | 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 |
+
+### ManagerTaskHandler / RunContext
+
+```ts
+// o retorno do handler é ignorado — nada além de status/logs/erro é enviado ao servidor
+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;
+}
+```

package/docs/getting-started.md

@@ -0,0 +1,103 @@
+# Getting started
+
+## Instalação
+
+```bash
+pnpm add hobots
+```
+
+Sem dependências de runtime. Requer **Node 18+** (usa o `fetch` global). O Monitor também funciona no browser para captura de erros.
+
+## O DSN
+
+Cada projeto tem **uma única DSN** — a mesma credencial autentica o Monitor **e** o Manager:
+
+```
+<protocolo>://<secretKey>@<host>[:porta]/<projectSlug>
+```
+
+A `secretKey` (64 hex) é **secreta**: ela vai embutida na DSN só por conveniência — nas requisições viaja sempre no header `Authorization: Bearer`, nunca na URL. O `projectSlug` no 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.
+
+```
+http://<secretKey>@localhost:3002/<projectSlug>
+```
+
+Veja [Protocolo & transporte](./protocol.md) para os endpoints que a DSN deriva.
+
+## Monitor e Manager — qual usar
+
+As duas capabilities vivem no mesmo `init()` e você usa **uma, outra ou as duas**:
+
+- Quer só saber se o robô quebrou, quanto demora e se está vivo? → `init({ dsn, heartbeat: true })`.
+- Quer 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 cenário do
+  [`full.ts`](../../hobots-sdk-demos/src/full.ts) nos demos do SDK.
+
+## O `init` único
+
+```js
+import * as Hobots from 'hobots';
+
+Hobots.init({
+  dsn: 'http://<secretKey>@localhost:3002/<projectSlug>',
+  environment: 'production',
+  release: 'robo-nfe@1.4.2',
+  instanceId: 'vm-cliente-01', // identidade única: heartbeat + agente Manager
+  heartbeat: true, // "estou vivo" a cada 30s
+});
+
+// Erros não tratados são capturados automaticamente.
+// Captura manual:
+try {
+  await processarNota(nota);
+} catch (error) {
+  Hobots.captureException(error, { tags: { cliente: 'acme' } });
+  throw error;
+}
+```
+
+Chame `Hobots.init` **uma vez**, o mais cedo possível no processo. Detalhes em [Monitor](./monitor.md).
+
+## Primeiro agente (Manager)
+
+Habilite a execução sob demanda com o campo `manager` no mesmo `init()`:
+
+```js
+import * as Hobots from 'hobots';
+
+Hobots.init({
+  dsn: 'http://<secretKey>@localhost:3002/<projectSlug>',
+  instanceId: 'vm-cliente-01',
+  manager: true, // ou { pollIntervalMs, concurrency, ... }
+});
+
+Hobots.register('processar-nfe', async (params, ctx) => {
+  ctx.log('info', `processando lote ${params.lote}…`);
+  return { processadas: 12 };
+});
+Hobots.start(); // mantém o processo vivo até stop()/close()
+```
+
+> O `instanceId` é a identidade dos **dois** canais (heartbeat do Monitor e agente do Manager) — o robô aparece como **um agente só** no painel, sem configuração extra.
+
+Detalhes (cancelamento, concorrência, idempotência) em [Manager](./manager.md).
+
+## Encerramento
+
+`close()` encerra tudo na ordem certa: para o Manager (aguardando a run atual), o heartbeat e faz o flush final do transport.
+
+Sem Manager iniciado, o SDK não segura o processo (timers `unref`'d), mas faça o flush final para não perder eventos em buffer:
+
+```js
+await Hobots.close(2000);
+```
+
+Com o Manager, `start()` segura o processo por design. Encerre de forma graciosa aguardando a run atual:
+
+```js
+process.on('SIGINT', () => {
+  void Hobots.close(15_000).then(() => process.exit(0));
+});
+```
+
+Para parar de aceitar execuções **sem** derrubar a telemetria, use `Hobots.stop(timeoutMs?)`.

package/docs/manager.md

@@ -0,0 +1,95 @@
+# Manager
+
+Capability de **execução remota sob demanda**, habilitada com `manager: true` (ou opções) no `init()` único. O agente faz polling no app, executa os handlers registrados quando aparece trabalho e reporta status e logs incrementais. Usa a mesma DSN, o mesmo `debug` e o `instanceId` como identidade — nenhum handler global extra é instalado.
+
+## Ciclo de vida
+
+```js
+import * as Hobots from 'hobots';
+
+Hobots.init({
+  dsn: 'http://<secretKey>@localhost:3002/<projectSlug>',
+  instanceId: 'vm-cliente-01',
+  manager: true, // ou { pollIntervalMs, concurrency, taskTimeoutMs, logFlushIntervalMs }
+});
+
+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 (os handlers registrados são preservados).
+- `register(task, handler)` — `task` é o `task_slug` configurado no formulário do app. Registre **antes** de `start()`. Pode ser chamado antes do `init()`; se o `init()` não habilitou o Manager, o SDK 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.
+
+O `instanceId` (obrigatório) é a identidade do agente no painel — o poll o envia como `agent.instance_id`, a **mesma identidade** do heartbeat do Monitor. Com o `init()` único, os dois canais convergem em **um agente** automaticamente.
+
+> **Atenção:** ao contrário da telemetria, `start()` **segura o processo vivo** aguardando trabalho até `stop()`/`close()` — o agente é a razão do processo existir.
+
+## 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 (o JSON validado).
+- **`ctx.log(level, message)`** — logs enviados **incrementalmente** ao app (PATCHes com throttle), visíveis na run em tempo quase real.
+- **`ctx.signal`** — `AbortSignal` que dispara quando a run é **cancelada no app**, em **timeout** ou no **shutdown**. Cancelamento é cooperativo (veja abaixo).
+- **Retorno** — **ignorado**. O SDK não captura nem envia o valor retornado pelo handler ao servidor — resultados de execução podem conter dados sensíveis e não são coletados.
+- **Erro lançado** — a run é reportada como `failed` com tipo/mensagem/stack (mensagem cap 10k, stack 20k).
+
+Você pode tipar os params: `Hobots.register<{ lote: number }>(...)`.
+
+> **Dados sensíveis:** o que você escreve em `ctx.log()` e as mensagens/stack de erros lançados **são enviados ao servidor** e ficam visíveis na execução no app. Não inclua senhas, tokens, documentos, 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 seu handler — o SDK não interrompe código em execução. Ele apenas dispara `ctx.signal`. **Verifique `ctx.signal.aborted`** em loops longos e pontos de parada:
+
+```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);
+  }
+});
+```
+
+## Idempotência (at-least-once)
+
+A entrega é **at-least-once**: se o agente morrer logo após capturar uma run (antes de reportar a conclusão), ela é re-entregue quando o agente voltar. Escreva handlers **idempotentes** — processar a mesma run duas vezes não pode causar efeito duplicado (use uma chave de deduplicação sua, como o número da 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**: enquanto vêm runs, re-pesquisa imediatamente; quando não vem nada, espera `pollIntervalMs`.
+
+## Timeout por run
+
+`taskTimeoutMs` é um timeout **client-side**. No estouro o SDK **não mata** o handler — ele dispara `ctx.signal`, libera o slot de concorrência e reporta a run como falha (`TaskTimeout`). O handler pode continuar rodando em background; respeite o `signal` para parar de verdade. Sem `taskTimeoutMs`, o backstop é o servidor.
+
+Todas as opções em [Referência de API → ManagerOptions](./api-reference.md#manageroptions).
+
+## Como o claim funciona (resumo)
+
+O SDK é um cliente HTTP: ele faz `POST /api/manager/poll` e o **servidor** reivindica as runs pendentes de forma atômica com `FOR UPDATE SKIP LOCKED` — dois agentes nunca pegam a mesma run. Detalhes em [Protocolo & transporte](./protocol.md).

package/docs/monitor.md

@@ -0,0 +1,138 @@
+# Monitor
+
+Capability de telemetria: erros, performance, crons e uptime. Sempre ativa no `init()` único:
+
+```js
+import * as Hobots from 'hobots';
+```
+
+Todas as funções abaixo são no-op seguros se `Hobots.init()` não foi chamado (com aviso no console). Assinaturas completas em [Referência de API](./api-reference.md).
+
+## init
+
+```js
+Hobots.init({
+  dsn: 'http://<secretKey>@localhost:3002/<projectSlug>',
+  environment: 'production',
+  release: 'robo-nfe@1.4.2',
+  instanceId: 'vm-cliente-01',
+  tags: { squad: 'automacoes' },
+  heartbeat: true,
+});
+```
+
+Cria o cliente, instala handlers globais de erro (a menos que `captureUnhandled: false`) e inicia o heartbeat se configurado. Chamar de novo substitui o cliente. Todos os campos em [Referência de API → InitOptions](./api-reference.md#initoptions).
+
+## Captura de erros e mensagens
+
+```js
+// exceções
+Hobots.captureException(error, {
+  tags: { cliente: 'acme' },
+  level: 'error',
+  fingerprint: ['sefaz-timeout'], // agrupa manualmente; sem isso o servidor agrupa pelo stack
+});
+
+// mensagens sem exceção
+Hobots.captureMessage('Lote processado com sucesso', 'info');
+```
+
+Ambas retornam o `event_id` (ou `undefined` se não inicializado). O segundo argumento é um [`CaptureHint`](./api-reference.md#capturehint) (`level`, `tags`, `extra`, `fingerprint`).
+
+Erros **não tratados** (`uncaughtException` / `unhandledRejection`) são capturados e flushados automaticamente antes do processo sair — desligue com `captureUnhandled: false`.
+
+## Breadcrumbs
+
+Trilha do que aconteceu antes do erro; enviada junto do próximo evento.
+
+```js
+Hobots.addBreadcrumb({ category: 'nfe', message: 'Baixou XML da nota 123', level: 'info' });
+```
+
+O buffer é limitado por `maxBreadcrumbs` (default 100, mais antigos descartados).
+
+## 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 tanto em `Transaction` quanto em `Span` (aninhamento arbitrário).
+- Métodos encadeáveis: `setStatus`, `setData` (span), `setTag`/`setName` (transaction).
+- `finish()` na transaction fecha spans abertos e envia o payload; nada é enviado se ela não foi amostrada.
+
+## Crons (check-ins)
+
+Monitora jobs agendados: um 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, use `checkIn` diretamente (veja [Referência](./api-reference.md#checkinoptions)):
+
+```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 em [HeartbeatOptions](./api-reference.md#heartbeatoptions).
+
+Essa identidade é a mesma que o Manager envia no poll (`agent.instance_id`) — os dois canais derivam do `instanceId` do `init()`, então o robô aparece como **um agente só** em Monitor → Agentes automaticamente.
+
+## Flush e close
+
+```js
+await Hobots.flush(2000); // envia o que está em buffer, mantém o SDK vivo
+await Hobots.close(2000); // para o Manager (se ativo) + heartbeat + flush final do transport
+```
+
+Chame `close` antes do processo sair. Os timers do Monitor são `unref`'d, então a telemetria **não** segura o processo vivo sozinha (só o `start()` do Manager segura).

package/docs/protocol.md

@@ -0,0 +1,101 @@
+# Protocolo & transporte
+
+O SDK é um **cliente HTTP puro**, sem dependências de runtime: ele só fala com o app da Hobots por HTTP. Não abre conexão com banco e **não** roda `SKIP LOCKED` — a reivindicação atômica de runs é server-side (veja o fim desta página).
+
+Os arquivos `src/protocol.ts` e `src/manager/protocol.ts` são a **fonte de verdade do wire format**: o app valida os payloads com zod travados nesses tipos (`satisfies z.ZodType<...>`), então não podem sofrer drift.
+
+## A DSN e os endpoints derivados
+
+Cada projeto tem **uma única DSN secreta**, a mesma para as duas capabilities:
+
+```
+<proto>://<secretKey>@host[:porta]/<projectSlug>
+```
+
+| Canal | Endpoint | Autenticação |
+| --- | --- | --- |
+| Monitor (ingestão) | `POST <origin>/api/ingest` | `Authorization: Bearer <secretKey>` |
+| Manager (execução) | `<origin>/api/manager/*` | `Authorization: Bearer <secretKey>` |
+
+`parseDsn(dsn) → { key, projectSlug, origin, ingestEndpoint, managerBaseUrl }` (em `src/dsn.ts`). A chave é **secreta** (64 hex) e viaja **só no header** `Authorization: Bearer` — nunca na URL da requisição. O `projectSlug` do path é informativo: a identidade real do projeto vem da chave.
+
+> A DSN antiga do Monitor (public key na URL, `POST /api/ingest/<key>`) foi descontinuada — o endpoint responde **410** e o transport descarta sem retry. Copie a DSN nova em **Configurações → Agentes** no app.
+
+## Monitor — ingestão
+
+Endpoint fixo `POST /api/ingest` recebe **envelopes** JSON autenticados por Bearer. O transport mantém uma fila em memória, agrupa itens em envelopes e faz POST via `fetch`.
+
+```jsonc
+{
+  "sdk": { "name": "hobots", "version": "1.0.0" },
+  "sent_at": "2024-01-01T00:00:00.000Z",
+  "items": [
+    { "type": "event",       "payload": { /* EventPayload */ } },
+    { "type": "transaction", "payload": { /* TransactionPayload */ } },
+    { "type": "check_in",    "payload": { /* CheckInPayload */ } },
+    { "type": "heartbeat",   "payload": { /* HeartbeatPayload */ } }
+  ]
+}
+```
+
+Tipos de item: `event`, `transaction`, `check_in`, `heartbeat` (definidos em `hobots/protocol`).
+
+**Flush & retries:** o transport flusha por `flushIntervalMs` (default 2s) ou ao atingir `maxBatchSize` (default 10). Ladder de retry `[1s, 4s, 16s]`; respostas 4xx (exceto 429) são descartadas sem retry; a fila tem teto de 200 itens (descarta os mais antigos).
+
+## Manager — polling e reporte
+
+Dois endpoints sob `<origin>/api/manager`, ambos com `Authorization: Bearer <secretKey>` (a chave única do projeto):
+
+### `POST /api/manager/poll`
+
+Corpo `ManagerPollRequest`:
+
+```jsonc
+{
+  "agent": {
+    "instance_id": "vm-01",       // identidade canônica do agente (obrigatória)
+    "name": "VM 01",
+    "version": "1.0.0",
+    "host": "vm-01",
+    "tasks": ["processar-nfe"]
+  },
+  "max": 1,                       // quantas reivindicar (1..5)
+  "tasks": ["processar-nfe"]      // só runs destas tasks registradas
+}
+```
+
+Resposta `ManagerPollResponse` = `{ runs: ManagerRunDescriptor[] }`, cada `{ id, task, params, form, source, created_at }`.
+
+O `agent.instance_id` é a **mesma identidade** do heartbeat do Monitor (`instance_id`): o servidor correlaciona os dois canais numa tabela `agents` por `(project_id, instance_id)`. Com o `init()` único, os dois derivam do `instanceId` — o robô aparece como um agente só no painel automaticamente.
+
+**Backoff:** um request por poll; o loop decide o ritmo. HTTP 401 (key rejeitada) → retry lento a 30s com log throttled; outros erros → ladder `[1s, 4s, 16s]`.
+
+### `PATCH /api/manager/runs/{id}`
+
+Corpo `ManagerRunUpdateRequest`:
+
+```jsonc
+{
+  "status": "running",            // 'running' | 'succeeded' | 'failed'
+  "logs":   [{ "ts": "…", "level": "info", "message": "…" }], // delta; o servidor concatena
+  "error":  { "type": "Error", "message": "…", "stack": "…" } // só com 'failed'
+}
+```
+
+- `status: 'running'` pode repetir para enviar **logs incrementais** (throttle por `logFlushIntervalMs`, flush ao acumular 20, chunk de 100, teto de 500 logs/run, mensagem cap 10k).
+- 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`).
+- 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).
+
+Ciclo de vida completo da run no servidor: `pending → claimed → running → succeeded | failed | canceled`. O agente só transiciona para `running`/`succeeded`/`failed`.
+
+## Onde vive o claim atômico
+
+O `POST /api/manager/poll` no app chama `claimPendingRuns()` em
+[`apps/webapp/lib/manager/claim.ts`](../../../apps/webapp/lib/manager/claim.ts): um CTE que seleciona runs `pending` vencidas com `FOR UPDATE SKIP LOCKED` e as promove a `claimed` num único `UPDATE ... RETURNING`. Isso garante que dois agentes concorrentes nunca peguem a mesma run. **Nada disso está no SDK** — ele só faz o HTTP.
+
+## Identidade do SDK
+
+`SDK_NAME = 'hobots'` e `SDK_VERSION` ficam em `src/utils.ts` e vão em todo envelope (campo `sdk`) e no `agent.version` do poll.
+
+> **Nota de manutenção:** `SDK_VERSION` é uma constante fixa e precisa ser mantida em sincronia com a `version` do `package.json` manualmente ao publicar.