hobots 5.2.0 → 6.1.0

package/docs/api-reference.md

@@ -30,7 +30,7 @@ ESM e CommonJS (`const { hobots } = require('hobots')`), com `.d.ts`. Depois do
 | `runId` | `string` | Identidade da execução (`''` fora de uma execução) |
 | `params` | `Record<string, unknown>` | Params da solicitação (formulário do agente); `{}` no modo start |
 | `log` | `RunLogger` — `debug/info/warn/error/success(message, ...rest)` | Nunca lança. Vários argumentos viram texto unidos por espaço (como `console.log`); um `hobots.image(...)` no **último** argumento vira o print da linha. Eco no terminal: `[hobots] INFO …` |
-| `items` | `RunItems` — `add(item)`, `succeeded(payload?, opts?)`, `failed(message, payload?, opts?)`, `occurrence(message, payload?, opts?)`; `opts.id` = identidade de negócio, `opts.image` = print do item. `each(list, (element, item, index) => …, { id?, payload?, op?, description?, progress? }) => Promise<{ total, succeeded, failed, occurrence }>` processa a lista inteira: exceção no handler vira item `failed` + etapa em erro e o loop segue; `item: RunItemHandle` = `succeeded(payload?, { image }?)/failed(msg, payload?, { image }?)/occurrence(…)`, `id`, `index`, `step` (`StepHandle` da etapa do item), `reported` | Ponto de parada cooperativo (o `each` para só em cancelamento/timeout) |
+| `items` | `RunItems` — `add(item)`, `succeeded(payload?, opts?)`, `failed(message, payload?, opts?)`, `occurrence(message, payload?, opts?)`; `opts.id` = identidade de negócio, `opts.image` = print do item. `each(list, (item, index?) => …, { id?, payload?, op?, description?, progress? }) => Promise<{ total, succeeded, failed, occurrence }>` processa a lista inteira (sem `payload`, os campos do elemento — objeto simples, cópia rasa — viram o payload base; `payload: false` desliga): exceção no handler vira item `failed` + etapa em erro e o loop segue; `item: RunItemHandle` = `value` (o elemento da lista), `succeeded(payload?, { image }?)/failed(msg, payload?, { image }?)/occurrence(…)`, `id`, `index`, `step` (`StepHandle` da etapa do item), `reported` | Ponto de parada cooperativo (o `each` para só em cancelamento/timeout) |
 | `progress` | `RunProgressReporter` — `total(n)`, `advance(count = 1)`, `set(current, total?)`, `current`, `snapshot` | `total/advance/set` são pontos de parada |
 | `files` | `RunFiles` — `list(): FileRef[]`, `get(field): FileRef \| FileRef[] \| undefined`, `download(refOrField: FileRef \| string, { dest? }?): Promise<string>`, `downloadAll(field, { dest? }?): Promise<string[]>`, `read(refOrField): Promise<Buffer>` | Arquivos do formulário; o download consome a origem (S3 confirmado/apagado, pasta do Studio removida). Cópias sem `dest` são apagadas no fim da execução. Respeita o `signal`. Ver [Execuções](./runs.md#arquivos-do-formulário-hobotsfiles) |
 | `step(name, fn, options?)` | `<T>(name: string, fn: StepFn<T>, options?: { retries?: number; retryDelayMs?: RetryDelay }) => Promise<T>` — uma etapa no waterfall: abre, roda `fn(etapa)`, tenta de novo se lançar (`retries` default 1; 0 desliga), fecha. `warning` + `data.message` + `data.attempts` quando a nova tentativa deu certo; `error` + `data.error = { type, message }` quando esgotou (a exceção sobe); `cancelled` em cancelamento/timeout. `StepHandle` = `warning(message, { image }?)`, `image(png)`, `data(key, value)` (`attachments` reservada). Aninha automaticamente na etapa corrente. | Ponto de parada (lança `RunCanceled`) |

package/docs/runs.md

@@ -81,7 +81,8 @@ O contrato da plataforma — **todo item previsto termina com um desfecho regist
 ```js
 const resultado = await hobots.items.each(
   contas,
-  async (conta, item) => {
+  async (item) => {
+    const conta = item.value;                 // o elemento da lista; a posição é item.index
     await login(conta);                       // lançou → item `failed` com a mensagem, etapa em erro, segue
     const fatura = await baixar(conta);
     if (!fatura) return item.occurrence('sem fatura no mês');   // ocorrência de negócio
@@ -93,6 +94,8 @@ const resultado = await hobots.items.each(
 // resultado = { total, succeeded, failed, occurrence }
 ```
 
+- O handler recebe o handle do item e, se declarar, o índice: `(item, index) => …`. O elemento da lista é `item.value`; `index` é o mesmo valor de `item.index`.
+- **`payload`**: sem a opção, os campos do próprio elemento viram o payload base (as colunas na Central), em cópia rasa — quando o elemento é um objeto simples (protótipo `Object.prototype` ou `null`). Instância de classe (um `Locator`, por exemplo), array e primitivo ficam sem payload base. Uma função `(element, index) => objeto` substitui o padrão (para escolher ou renomear colunas, como no exemplo acima); `payload: false` desliga. Ordem de mescla: payload base < `item.data(...)` < payload do desfecho.
 - Cada elemento vira uma **etapa** no waterfall (`op` 'item', descrição = `id`; `hobots.step(...)` dentro do handler vira sub-etapa dela, e `item.step` é o handle `warning`/`image`/`data`) e um **item** com o `id` e o payload base.
 - **Exceção no handler** = item `failed` com a mensagem do erro, etapa em `error`, linha de erro no log da run — e o loop **segue para o próximo**. Nada do que o handler já registrou (`item.failed/occurrence`) é sobrescrito. O `each` não repete o item: para tentar de novo um trecho, use `hobots.step` dentro do handler.
 - **Progresso automático**: declara o total pelo tamanho da lista (se o bot ainda não declarou um) e avança a cada elemento, inclusive nos que falharam. `progress: false` deixa o progresso por conta do bot.
@@ -272,7 +275,8 @@ hobots.log.error('login falhou', hobots.image(await page.screenshot(), { caption
 
 // no item
 hobots.items.failed('nota rejeitada', { numero }, { image: await page.screenshot() });
-await hobots.items.each(notas, async (nota, item) => {
+await hobots.items.each(notas, async (item) => {
+  const nota = item.value;
   …
   item.occurrence('sem fatura no mês', undefined, { image: await page.screenshot() });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hobots",
-  "version": "5.2.0",
+  "version": "6.1.0",
   "description": "SDK JavaScript da Hobots — o agente é a própria tarefa: register() atende solicitações da plataforma (sob demanda), start() roda sempre ligado e reporta logs, itens e progresso. Credenciais por env, heartbeat sempre ligado, objeto global `hobots`.",
   "type": "module",
   "sideEffects": false,