hobots 4.1.0 → 4.5.0

package/README.md

@@ -27,11 +27,13 @@ CommonJS: `const { hobots } = require('hobots')`.
 ## Em 30 segundos
 
 ```bash
-export HOBOTS_CLIENT_SECRET=hb_<64 hex>   # Configurações → Agentes
+export HOBOTS_CLIENT_SECRET=hb_<64 hex>   # Central: agente → Configurações → agente → aba credenciais
 export HOBOTS_INSTANCE_ID=vm-cliente-01   # opcional — default: hostname da máquina
 export HOBOTS_ENVIRONMENT=staging         # opcional — default: production
 ```
 
+Ou num arquivo `.env` na pasta de onde o bot é executado — o SDK o carrega sozinho (sem `dotenv`), veja [Credenciais e identidade](#credenciais-e-identidade).
+
 ```js
 import hobots from 'hobots';
 
@@ -55,8 +57,14 @@ Um robô que vive rodando usa `start` no lugar de `register` — o handler é o
 hobots.start(async () => {
   while (true) {
     await hobots.sleep(60_000); // cancelável
-    for (const arquivo of await novosArquivos()) hobots.items.succeeded({ arquivo });
+    for (const arquivo of await novosArquivos()) {
+      const step = hobots.transaction.start('arquivo', arquivo);
+      await processar(arquivo);
+      step.succeeded();
+      hobots.items.succeeded({ arquivo });
+    }
     hobots.log.info('ciclo ok');
+    await hobots.flush(); // envia as etapas, itens e logs deste ciclo agora
   }
 });
 ```
@@ -69,13 +77,16 @@ O objeto **`hobots`** é global: `hobots.log`, `hobots.items`, `hobots.progress`
 
 | Env | Opção | O que é |
 | --- | --- | --- |
-| `HOBOTS_CLIENT_SECRET` | `clientSecret` | O **Client Secret do agente** (`hb_<64 hex>`), copiado em **Configurações → Agentes**. Viaja só no header `Authorization: Bearer`, nunca na URL. Ausente ou inválido → `register()`/`start()` lança na hora, citando a env (sem ecoar o valor). |
+| `HOBOTS_CLIENT_SECRET` | `clientSecret` | O **Client Secret do agente** (`hb_<64 hex>`), copiado na Central em **agente → Configurações → agente → aba credenciais**. Viaja só no header `Authorization: Bearer`, nunca na URL. Ausente ou inválido → `register()`/`start()` lança na hora, citando a env (sem ecoar o valor). |
 | `HOBOTS_INSTANCE_ID` | `instanceId` | Identidade **estável** desta instância do robô (`vm-cliente-01`). Sem ela, o hostname. Heartbeat e execuções convergem nela: **um agente só** no painel. |
+| `HOBOTS_RUN_ID` | `runId` | Definida por quem lança o processo (o Studio): o `register()` não faz poll — inicia essa run, executa o handler uma vez e sai. O código do bot não muda. |
 | `HOBOTS_ENVIRONMENT` | `environment` | Ambiente lógico do robô (`development` \| `testing` \| `staging` \| `production`). Sem ela, `production`. |
 | `HOBOTS_API_URL` | — | Só em desenvolvimento: aponta o SDK para outro host (`http://localhost:3001`). Em produção é sempre `https://api2.hobots.app`. |
 
 A opção passada em `register()`/`start()` tem precedência sobre a env — útil para copiar e colar o snippet do app.
 
+**`.env` automático.** Ao ser importado, o SDK carrega o arquivo `.env` da pasta de trabalho (`process.cwd()`) em `process.env` — o bot não precisa de `dotenv` nem de `--env-file`, e o próprio código do bot também enxerga as variáveis (`process.env.SENHA_PORTAL`), inclusive no topo do módulo. A env já definida no ambiente **vence** o arquivo. Sem `.env`, nada muda. Usa o parser nativo do Node (`process.loadEnvFile`, Node ≥ 20.12); em Node mais antigo o arquivo é ignorado.
+
 ---
 
 ## Os dois modos
@@ -104,12 +115,13 @@ A opção passada em `register()`/`start()` tem precedência sobre a env — út
 | `hobots.items.each(lista, async (el, item) => …, { id, payload }?)` | **Loop com o contrato garantido**: cada elemento vira step + item; exceção no handler = item `failed` com a mensagem e o loop **segue** até o fim; progresso automático. Só cancelamento/timeout interrompem. |
 | `hobots.progress.total(n)` · `.advance(k = 1)` · `.set(atual, total?)` · `.current` · `.snapshot` | Barra, percentual e tempo restante na execução. Sem `total()` nada é enviado. |
 | `hobots.flush(timeoutMs?)` | **Entrega já** o que a execução fez: as steps raiz finalizadas viram transactions parciais (waterfall na Central sem esperar a run terminar) e itens, logs e progresso pendentes saem sem esperar o throttle. O bot decide quando — num agente `start()`, ao fim de cada rodada que processou itens. Aguarda com teto (15 s) e nunca lança. |
-| `hobots.transaction.startChild(op, descrição)` | Uma **step** no waterfall de performance da execução. A transaction da execução (`run`) já existe e é finalizada pelo SDK. `step.setStatus(status, msg?, { image })` / `setError(err, msg?, { image })` penduram um print na step. |
+| `hobots.transaction.start(op, descrição)` | Uma **step** no waterfall de performance da execução. A transaction da execução (`run`) já existe e é finalizada pelo SDK. `step.setStatus(status, msg?, { image })` / `failed(err, msg?, { image })` penduram um print na step. |
 | `hobots.image(bytes \| caminho, { caption?, contentType? })` | Embrulha um **print** (PNG/JPEG/WEBP, até 5 MB, 20 por execução) para ir junto de um log, item ou step. Puro: o upload roda em segundo plano quando o evento é registrado; nunca lança nem bloqueia. |
 | `hobots.captureException(erro, hint?)` | Abre uma **issue** (módulo Issues). `hint.attachment` anexa um print à linha de log correspondente. |
 | `hobots.retry(fn, { retries = 3, delayMs = 1_000, shouldRetry? })` | async-retry ciente do cancelamento da execução. `delayMs` aceita função `(tentativa) => ms`. |
 | `hobots.sleep(ms)` | Espera **cancelável**: rejeita com `RunCanceled` se a execução for cancelada. |
 | `hobots.signal` · `hobots.throwIfCanceled()` | Cancelamento cooperativo manual, para controle fino. |
+| `hobots.files.list()` · `.get(campo)` · `.download(refOuCampo, { dest }?)` · `.downloadAll(campo)` · `.read(refOuCampo)` | **Arquivos dos campos de upload** do formulário: baixa para o disco (ou para a memória) e consome na origem — ver [Arquivos do formulário](#arquivos-do-formulário). `isFileRef(valor)` reconhece um arquivo nos params. |
 | `hobots.runId` · `hobots.params` | Identidade da execução atual. |
 | `hobots.register(...)` · `hobots.start(...)` · `hobots.close(timeoutMs?)` | Ciclo de vida do processo. |
 
@@ -117,11 +129,40 @@ O handler também recebe o mesmo contexto como 2º argumento (`(params, ctx) =>
 
 ---
 
+## Arquivos do formulário
+
+Um campo de **upload** no formulário do agente chega nos `params` como um `FileRef` — `{ id, name, size, contentType, storage }` — ou uma lista deles (campo "vários arquivos"). O bot não precisa saber de onde o arquivo veio: `hobots.files.download` traz para o disco desta máquina e devolve o caminho.
+
+```js
+import { hobots } from 'hobots';
+
+hobots.register(async () => {
+  // campo único: o caminho do arquivo baixado (pasta temporária da execução)
+  const planilha = await hobots.files.download('planilha');
+  await importarPlanilha(planilha);
+
+  // campo "vários arquivos": um caminho por arquivo, na ordem, na pasta escolhida
+  const notas = await hobots.files.downloadAll('notas', { dest: './entrada' });
+  for (const nota of notas) await lancarNota(nota);
+
+  // ou direto em memória (Buffer) — a cópia temporária é apagada
+  const contrato = await hobots.files.read('contrato');
+});
+```
+
+- **Cada arquivo é baixado uma vez.** O download consome a origem: enviado pela Central (`storage: 's3'`), o SDK pede uma URL temporária, baixa em streaming, confere o tamanho e **só então** confirma — o servidor apaga o arquivo na hora; uma segunda tentativa recebe `arquivo "x" já baixado ou expirado` (`TasksApiError` com `status` 410). Escolhido no Studio (`storage: 'local'`), o arquivo nunca sai do computador: o SDK copia de `$HOBOTS_LOCAL_FILES_DIR/<id>/` e apaga a pasta de origem — num bot de outro computador (sem a env ou sem a pasta), o erro é `arquivo "x" enviado pelo Studio de outro computador ou já consumido`.
+- **Falha não perde o arquivo:** rede caiu, tamanho divergente, execução cancelada — nada é confirmado e o `download` pode ser tentado de novo (ex.: dentro de `hobots.retry`).
+- **Onde o arquivo vai parar:** sem `dest`, numa pasta temporária **da execução, apagada quando ela termina** — guarde o que precisar além disso com `dest`. `dest` pasta (existente ou terminada em `/`) recebe o nome original; outro caminho vira o nome do arquivo final.
+- `hobots.files.list()` lista todos os arquivos dos params; `hobots.files.get('campo')` devolve o `FileRef` (ou a lista); `download` aceita o nome do campo ou o próprio `FileRef` (um item da lista, por exemplo). Para campo com vários arquivos use `downloadAll` (o `download('campo')` lança, apontando para ele).
+- Respeita o cancelamento: uma execução cancelada no meio do download lança `RunCanceled` e não consome o arquivo.
+
+---
+
 ## Cancelamento automático
 
 Uma execução cancelada no app **não mata** o handler — o SDK dispara `hobots.signal` e o próximo ponto de parada lança **`RunCanceled`**:
 
-- `hobots.items.*`, `hobots.progress.total/advance/set`, `hobots.transaction.startChild()`, `hobots.sleep()` e cada tentativa de `hobots.retry()`.
+- `hobots.items.*`, `hobots.progress.total/advance/set`, `hobots.transaction.start()`, `hobots.sleep()` e cada tentativa de `hobots.retry()`.
 - **Nunca `hobots.log.*`** — um log dentro de um `finally` de limpeza não pode explodir.
 
 Num loop de itens, isso costuma bastar: registrar o item processado já é o ponto de parada. Para controle fino, `hobots.throwIfCanceled()` e `hobots.signal` continuam disponíveis. Quando o cancelamento veio do app, o `RunCanceled` é **suprimido** — a execução já está `cancelada` no servidor e nada é reportado por cima. Limpeza (fechar navegador, desfazer estado) vai em `try/finally`.
@@ -165,6 +206,7 @@ hobots.start(handler, options?: StartOptions);
 | `timeoutMs` | — (infinito) | Timeout por tentativa; terminal (`TaskTimeout`). O handler não é morto: o signal dispara e o slot é liberado |
 | `concurrency` (register) | `1` | Execuções simultâneas do agente (1..5) |
 | `pollIntervalMs` (register) | `2_000` | Intervalo entre polls sem trabalho (mín. 1_000) |
+| `runId` (register) | env `HOBOTS_RUN_ID` | Avançado: executa só esta run (já reivindicada, ex.: pelo Studio) sem poll e encerra o SDK |
 | avançadas: `installExitHandlers`, `logFlushIntervalMs`, `cancelCheckIntervalMs`, `cancelGraceMs` | `true`, `2_000`, `5_000`, `10_000` | Ver [Referência de API](./docs/api-reference.md) |
 
 Como só há uma chamada por processo, todas as opções são as **do agente** — não existe "opção de processo" separada da "opção da task".
@@ -189,6 +231,8 @@ Sem handler próprio de sinal, um `SIGINT`/`SIGTERM` (ou erro fatal) com execuç
 
 ## Changelog resumido
 
+- **4.3.0** — `register()` com env `HOBOTS_RUN_ID` (ou opção `runId`) executa só essa run: `POST /v1/runs/{id}/start` no lugar do poll, handler uma vez e `close()`; tipos `RunStartRequest`/`RunStartResponse` em `hobots/protocol`; itens recusados por armazenamento cheio (`402 storage_limit`) viram um aviso só por episódio, sem parar os envios.
+- **4.2.0** — **arquivos do formulário**: `hobots.files` (`list`, `get`, `download`, `downloadAll`, `read`) e `isFileRef`; tipos `FileRef`, `FileStorage`, `FileDownloadResponse` em `hobots/protocol`.
 - **4.0.0** — **o agente é a própria tarefa** (breaking): `register(handler, options?)`/`start(handler, options?)` **sem slug**; **uma chamada por processo** (a segunda lança); `hobots.task`/`ctx.task` removidos; tipos `TaskHandler`→`RunHandler`, `TaskOptions`→`RunOptions`, `TaskItemsOptions`→`ItemsOptions`; wire: `InstanceInfo.mode` (`on_demand` \| `always_on`) e `InstanceInfo.items` no lugar de `tasks`/`task_items`, endpoints em `/v1/runs/*`; eco no terminal `[hobots] INFO …`. Guia de migração no [CHANGELOG](./CHANGELOG.md).
 - **3.4.0** — `hobots.attach()` removido; o print vai junto do evento: `hobots.image(...)` no último argumento de `log.*`, `{ image }` em itens e steps.
 - **3.1.0** — `hobots.log.*` aceita vários argumentos (como `console.log`); `retries` inválido (`NaN`) cai no default em vez de tentar para sempre; 429 de itens e 429/501/503 de anexo são definitivos (sem esperar a ladder — `quota`/`unsupported` passam a funcionar de fato); timeout **por requisição** nos anexos; truncamento nos limites do servidor (tag 512, fingerprint 10×255, nome de transaction 500, 200 steps, `exception.value` 8192, `filename` 1024); PNG acima de 20 000 px não declara dimensões; PATCH terminal nunca passa de 100 logs.