hobots 1.0.0 → 1.1.1

package/README.md

@@ -3,9 +3,9 @@
 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, logs e resultado.
+- **Manager** — execução **sob demanda**: o agente faz polling no app da Hobots, executa handlers registrados e reporta status e logs.
 
-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); o Monitor também roda no browser para captura de erros.
 
 ---
 
@@ -17,63 +17,72 @@ npm install hobots
 ```
 
 ```js
-import * as Monitor from 'hobots';          // capability Monitor (import raiz)
-import * as Manager from 'hobots/manager';  // capability Manager
+import * as Hobots from 'hobots'; // um import só — Monitor e Manager
 ```
 
-Também funciona em CommonJS: `const Monitor = require('hobots')`.
+Também funciona em CommonJS: `const Hobots = require('hobots')`.
 
 ---
 
-## As duas capabilities
+## Um SDK, duas capabilities, um `init()`
 
-O SDK expõe **duas capabilities independentes** — credenciais, entry points e ciclos de vida separados — que podem conviver no mesmo processo.
+O SDK expõe **duas capabilities** autenticadas pelo **mesmo Client Secret do projeto**, configuradas em um único `init()`:
 
-| Capability | Import | Para quê | Ciclo de vida |
+| Capability | Como habilita | Para quê | Ciclo de vida |
 | --- | --- | --- | --- |
-| **Monitor** | `hobots` | Telemetria emitida pelo próprio programa: erros, transactions/spans, crons, heartbeat. | Timers `unref`'d — **não** segura o processo. Chame `close()` no fim. |
-| **Manager** | `hobots/manager` | Execução remota sob demanda via polling. | `start()` **segura o processo vivo** até `stop()`. |
+| **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? → **Monitor**.
-- Disparar o robô sob demanda a partir de um formulário no app? → **Manager**.
-- Ambos? Inicialize os dois no mesmo processo, com credenciais separadas.
+- 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.
+
+```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
+});
+
+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
+## O Client Secret
 
-Toda credencial do SDK é um **DSN** no formato `<protocolo>://<key>@<host>[:porta]/<projeto>`. A `key` vai embutida na URL e o `host` aponta para o app da Hobots. Copie o DSN pronto na página do projeto no app.
+Cada projeto tem **um único Client Secret** — a mesma credencial autentica o Monitor **e** o Manager:
 
 ```
-Monitor:  https://<publicKey>@<host>/<projectId>     ← public key (ingestão), na URL
-Manager:  https://<managerKey>@<host>/<projectSlug>  ← manager key (secreta), via Bearer
+hb_<64 hex>
 ```
 
-- **Monitor** usa a **public key** (chave de ingestão) e o `projectId`. É a chave do snippet de integração em `/monitor`.
-- **Manager** usa a **manager key** (chave secreta do agente, criada em `/manager/agents`) e o `projectSlug`. **Não** é a chave de ingestão; nunca vai na URL da requisição, só no header `Authorization: Bearer`.
+(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. O SDK fala com a API oficial `https://api.hobots.app` automaticamente; em desenvolvimento, aponte para outro host com a env `HOBOTS_API_URL` (ex.: `HOBOTS_API_URL=http://localhost:3001`).
 
 ---
 
 ## Monitor
 
-```js
-import * as Monitor from 'hobots';
-```
-
-Todas as funções abaixo são **no-op seguras** se `Monitor.init()` não foi chamado (com aviso no console).
+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
-Monitor.init({
-  dsn: 'https://<publicKey>@<host>/<projectId>',
+Hobots.init({
+  clientSecret: 'hb_<64 hex>',
   environment: 'production',
   release: 'robo-nfe@1.4.2',
-  serverName: 'vm-cliente-01',
+  instanceId: 'vm-cliente-01',
   tags: { squad: 'automacoes' },
   heartbeat: true, // "estou vivo" a cada 30s
 });
@@ -81,16 +90,17 @@ Monitor.init({
 
 | Opção | Tipo | Default | Descrição |
 | --- | --- | --- | --- |
-| `dsn` | `string` | **obrigatório** | `https://<publicKey>@host/<projectId>` |
+| `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` |
-| `serverName` | `string` | hostname | identifica a máquina; também vira `instanceId` do heartbeat |
+| `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 |
@@ -102,7 +112,7 @@ Monitor.init({
 try {
   await processarNota(nota);
 } catch (error) {
-  Monitor.captureException(error, {
+  Hobots.captureException(error, {
     level: 'error',
     tags: { cliente: 'acme' },
     fingerprint: ['sefaz-timeout'], // agrupa manualmente; sem isso o servidor agrupa pelo stack
@@ -110,7 +120,7 @@ try {
   throw error;
 }
 
-Monitor.captureMessage('Lote processado com sucesso', 'info');
+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`.
@@ -122,7 +132,7 @@ Ambas retornam o `event_id` (ou `undefined` se não inicializado). O hint aceita
 Trilha do que aconteceu antes do erro; enviada junto do próximo evento (buffer limitado por `maxBreadcrumbs`, mais antigos descartados).
 
 ```js
-Monitor.addBreadcrumb({ category: 'nfe', message: 'Baixou XML da nota 123', level: 'info' });
+Hobots.addBreadcrumb({ category: 'nfe', message: 'Baixou XML da nota 123', level: 'info' });
 ```
 
 ### Escopo: tags, usuário, contexto, extras
@@ -130,26 +140,26 @@ Monitor.addBreadcrumb({ category: 'nfe', message: 'Baixou XML da nota 123', leve
 Dados anexados a **todos** os eventos seguintes:
 
 ```js
-Monitor.setTag('regiao', 'nordeste');
-Monitor.setTags({ squad: 'automacoes', cliente: 'acme' });
-Monitor.setUser({ id: 'op-42', email: 'op@acme.com' });
-Monitor.setContext('vm', { cpu: 4, ram: '8GB' });
-Monitor.setExtra('ultimoLote', 128);
+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
-Monitor.withScope((scope) => {
+Hobots.withScope((scope) => {
   scope.setTag('lote', '128').setFingerprint(['reprocessamento']);
-  Monitor.captureMessage('Reprocessando lote 128');
+  Hobots.captureMessage('Reprocessando lote 128');
 });
 ```
 
 ### Performance: transactions e spans
 
 ```js
-const tx = Monitor.startTransaction('processar-lote', 'rpa.job');
+const tx = Hobots.startTransaction('processar-lote', 'rpa.job');
 
 const span = tx.startChild('http.client', 'GET /api/notas');
 await api.buscarNotas();
@@ -172,7 +182,7 @@ tx.finish();         // só aqui a transaction é enviada (respeitando tracesSam
 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 Monitor.withMonitor(
+await Hobots.withMonitor(
   'sync-notas',
   () => executarSync(),
   { schedule: '0 */2 * * *', timezone: 'America/Fortaleza' }
@@ -182,9 +192,9 @@ await Monitor.withMonitor(
 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 = Monitor.checkIn({ monitorSlug: 'sync-notas', status: 'in_progress' });
+const id = Hobots.checkIn({ monitorSlug: 'sync-notas', status: 'in_progress' });
 // … trabalho …
-Monitor.checkIn({ monitorSlug: 'sync-notas', status: 'ok', checkInId: id, durationMs: 1234 });
+Hobots.checkIn({ monitorSlug: 'sync-notas', status: 'ok', checkInId: id, durationMs: 1234 });
 ```
 
 ### Heartbeat (uptime)
@@ -192,19 +202,19 @@ Monitor.checkIn({ monitorSlug: 'sync-notas', status: 'ok', checkInId: id, durati
 Bate "estou vivo" periodicamente; o servidor acusa o robô **offline** quando os batimentos param.
 
 ```js
-Monitor.init({
-  dsn,
+Hobots.init({
+  clientSecret,
   heartbeat: { intervalMs: 30_000, name: 'Robô NFe — VM 01' },
 });
 ```
 
-`heartbeat: true` usa os defaults. Campos: `intervalMs` (30000), `instanceId` (default `serverName`/`HOSTNAME`/id aleatório), `name`, `metadata`.
+`heartbeat: true` usa os defaults. A identidade é o `instanceId` do `init()`. Campos: `intervalMs` (30000), `name` (default: o `instanceId`), `metadata`.
 
 ### Flush e close
 
 ```js
-await Monitor.flush(2000); // envia o buffer, mantém o SDK vivo
-await Monitor.close(2000); // flush final + para o heartbeat + fecha o transport
+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.
@@ -213,50 +223,50 @@ Chame `close` antes do processo sair. Os timers do Monitor são `unref`'d — el
 
 ## Manager
 
-```js
-import * as Manager from 'hobots/manager';
-```
-
-Capability de **execução remota sob demanda**. O agente faz polling no app, executa os handlers registrados quando aparece trabalho e reporta status, logs incrementais e resultado. Credencial própria (**manager key**), singletons próprios, nenhum handler global instalado.
+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.
 
 ### Ciclo de vida
 
 ```js
-Manager.init({ dsn: 'https://<managerKey>@<host>/<projectSlug>', agentName: 'VM Cliente 01' });
+Hobots.init({
+  clientSecret: 'hb_<64 hex>',
+  instanceId: 'vm-cliente-01',
+  manager: true, // ou { pollIntervalMs, concurrency, ... }
+});
 
-Manager.register('processar-nfe', async (params, ctx) => {
+Hobots.register('processar-nfe', async (params, ctx) => {
   ctx.log('info', `processando lote ${params.lote}…`);
   if (ctx.signal.aborted) return;   // cancelamento cooperativo
-  return { processadas: 12 };       // vira o resultado da execução no app
+  ctx.log('info', '12 notas processadas');
 });
 
-Manager.start(); // começa o polling e MANTÉM O PROCESSO VIVO
+Hobots.start(); // começa o polling e MANTÉM O PROCESSO VIVO
 
 process.on('SIGINT', () => {
-  void Manager.stop(15_000).then(() => process.exit(0));
+  void Hobots.close(15_000).then(() => process.exit(0));
 });
 ```
 
-- `init(options)` — cria o agente (singleton). Chamar de novo para o anterior e substitui.
-- `register(task, handler)` — `task` é o `task_slug` configurado no formulário do app. Registre **antes** de `start()`.
-- `start()` — começa o polling. Lança se `init()` não foi chamado ou se nenhuma task foi registrada.
-- `stop(timeoutMs?)` — para o polling e aguarda as runs ativas (default 30s). Retorna `false` se estourou o timeout.
+- `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 (`ManagerInitOptions`) | Tipo | Default | Descrição |
+| Opção (`ManagerOptions`) | Tipo | Default | Descrição |
 | --- | --- | --- | --- |
-| `dsn` | `string` | **obrigatório** | com a **manager key** (não a chave de ingestão) |
 | `pollIntervalMs` | `number` | `5000` | intervalo entre polls sem trabalho (mínimo `1000`) |
 | `concurrency` | `number` | `1` | runs simultâneas (clamp 1..5) |
-| `agentName` | `string` | hostname | nome exibido no dashboard |
 | `taskTimeoutMs` | `number` | — | timeout client-side por run (não mata o handler; servidor é o backstop) |
 | `logFlushIntervalMs` | `number` | `2000` | intervalo do envio incremental de logs |
-| `debug` | `boolean` | `false` | loga atividade do agente |
+
+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 handler e o `RunContext`
 
 ```ts
-type ManagerTaskHandler<P = Record<string, unknown>, R = unknown> =
-  (params: P, ctx: RunContext) => R | Promise<R>;
+type ManagerTaskHandler<P = Record<string, unknown>> =
+  (params: P, ctx: RunContext) => void | Promise<void>;
 
 interface RunContext {
   runId: string;
@@ -266,22 +276,24 @@ interface RunContext {
 }
 ```
 
-- **`params`** — os dados do formulário configurado no app (JSON validado). Tipável: `Manager.register<{ lote: number }, { processadas: number }>(...)`.
+- **`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** — vira o resultado exibido no app (JSON, cap ~100KB; maiores/circulares são descartados com marcador `__truncated`).
+- **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
-Manager.register('processar-nfe', async (params, ctx) => {
+Hobots.register('processar-nfe', async (params, ctx) => {
   for (const nota of params.notas) {
     if (ctx.signal.aborted) {
       ctx.log('warning', 'cancelamento detectado — parando');
-      return { canceladas: true };
+      return;
     }
     await processar(nota);
   }
@@ -298,34 +310,66 @@ Manager.register('processar-nfe', async (params, ctx) => {
 
 ### Idempotência (at-least-once)
 
-A entrega é **at-least-once**: se o agente morre logo após capturar uma run (antes de reportar o resultado), ela é re-entregue quando o agente voltar. Escreva handlers **idempotentes** (use uma chave de deduplicação sua, como o número da nota).
+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
-// Monitor: não segura o processo, mas faça o flush final para não perder eventos
-await Monitor.close(2000);
+// só Monitor: não segura o processo, mas faça o flush final para não perder eventos
+await Hobots.close(2_000);
 
-// Manager: segura o processo por design — aguarde a run atual
+// com Manager: segura o processo por design — aguarde a run atual
 process.on('SIGINT', () => {
-  void Manager.stop(15_000).then(() => process.exit(0));
+  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` | Monitor: funções, `Client`, `Scope`, `Transaction`, `Span`, `parseDsn`, tipos. |
-| `hobots/protocol` | Tipos do wire format do Monitor. |
-| `hobots/manager` | Manager: `init`/`register`/`start`/`stop`, `ManagerAgent`, `ManagerApi`, `ManagerApiError`, `parseManagerDsn`, tipos. |
-| `hobots/manager/protocol` | Tipos do wire format do Manager. |
+| `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({ clientSecret, 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);
+```
 
-Empacotado em **ESM e CommonJS** com **definições de tipos** (`.d.ts`) para todas as entradas.
+- A `dsn` (mecanismo antigo, `https://<secretKey>@host/<slug>`) não existe mais — passe `clientSecret` (em desenvolvimento, aponte para outro host com a env `HOBOTS_API_URL`). Copie o Client Secret em **Configurações → Projetos**.
+- `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()`; `clientSecret` 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`.
 
 ---
 
@@ -333,11 +377,11 @@ Empacotado em **ESM e CommonJS** com **definições de tipos** (`.d.ts`) para to
 
 Guias detalhados acompanham o pacote em [`docs/`](./docs/README.md):
 
-- [Getting started](./docs/getting-started.md) — instalação, DSN, primeiro `init`, Monitor vs Manager.
+- [Getting started](./docs/getting-started.md) — instalação, Client Secret, 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) — DSNs, endpoints, envelope, retries.
+- [Protocolo & transporte](./docs/protocol.md) — o Client Secret, endpoints, envelope, retries.
 
 ---