hobots 5.0.0 → 5.2.0

package/README.md

@@ -112,7 +112,7 @@ A opção passada em `register()`/`start()` tem precedência sobre a env — út
 | --- | --- |
 | `hobots.log.debug/info/warn/error/success(msg, ...rest)` | Log da execução, enviado incrementalmente ao app (e ecoado no terminal como `[hobots] INFO …`). Aceita vários argumentos como `console.log` — `hobots.log.info('nota', numero, 'ok')` — cada um vira texto, unidos por espaço. Um `hobots.image(...)` como **último** argumento pendura um print na linha. **Nunca lança** — pode ir em `finally`. |
 | `hobots.items.succeeded(payload?, { id, image }?)` · `.failed(msg, payload?, …)` · `.occurrence(msg, payload?, …)` · `.add({...})` | **A entrega do robô**: cada item processado, com status e atributos (viram colunas no app — declare-as com a opção `items: { columns: [...] }` do `register`/`start`). `image` pendura um print no item. Bufferizado, em lotes. |
-| `hobots.items.each(lista, async (el, item) => …, { id, payload }?)` | **Loop com o contrato garantido**: cada elemento vira etapa + item; exceção no handler = item `failed` com a mensagem e o loop **segue** até o fim; progresso automático; `hobots.flush()` ao fim de cada ciclo (`flush: false` desliga). Só cancelamento/timeout interrompem. |
+| `hobots.items.each(lista, async (el, item) => …, { id: 'campo', payload, retries: 1, retryDelayMs: 5000, skipDone: true }?)` | **Loop com o contrato garantido**: cada elemento vira etapa + item; exceção no handler = nova tentativa e, esgotada, item `failed` com a mensagem e o loop **segue** até o fim; `throw new Occurrence(msg)` = item `occurrence`, sem repetir; na reexecução do mesmo trabalho pula o que já deu `succeeded`/`occurrence`; progresso automático; `hobots.flush()` ao fim de cada ciclo (`flush: false` desliga). Só cancelamento/timeout interrompem. No handler, `item.data({ nf: 123 })` vai guardando os atributos do item sem decidir o desfecho — entram no `succeeded`/`failed`/`occurrence`, inclusive nos implícitos. |
 | `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 etapas raiz finalizadas viram transactions parciais (waterfall na Central sem esperar a run terminar) e itens, logs e progresso pendentes saem sem esperar o throttle. `step` (raiz) e cada ciclo do `items.each` já chamam sozinhos; à mão, para o resto da rodada de um agente `start()`. Aguarda com teto (15 s) e nunca lança. |
 | `hobots.step(nome, async etapa => …, { retries = 1, retryDelayMs = 5_000, flush = true }?)` | Uma **etapa** no waterfall de performance da execução: roda a função, **tenta de novo** se ela lançar (`retries: 0` desliga — use em etapas não idempotentes) e fecha a etapa. Resolve com o retorno da função. `hobots.step` dentro de outra vira sub-etapa. A etapa raiz faz `flush()` ao terminar (`flush: false` desliga). O handle `etapa` tem `warning(motivo, { image }?)`, `image(png)` e `data(chave, valor)`. |
@@ -231,6 +231,8 @@ Sem handler próprio de sinal, um `SIGINT`/`SIGTERM` (ou erro fatal) com execuç
 
 ## Changelog resumido
 
+- **5.2.0** — **`item.data(payload)`** no handle do `items.each`: guarda atributos do item sem registrar desfecho; mescla a cada chamada e entra em qualquer desfecho (inclusive nos implícitos), entre o `options.payload` do `each` e o payload da chamada de desfecho; zera na nova tentativa. Detalhes no [CHANGELOG](./CHANGELOG.md).
+- **5.1.0** — `items.each` com **nova tentativa por item** (`retries: 1`, `retryDelayMs: 5000`; uma etapa só por elemento, `warning` quando a repetição deu certo, `error` + item `failed` quando esgotou), **`Occurrence`** exportada (`throw new Occurrence(msg, payload?, { image }?)` no handler = item `occurrence`, sem repetir), `id` por campo (`'numero'`), chave composta (`['cnpj', 'competencia']`) ou função — padrão: o campo `id` do elemento — e **reexecução sem repetir**: ao executar novamente o trabalho, pula os ids já `succeeded`/`occurrence` (`skipDone: true`; `POST /v1/runs/{id}/items/done`); resultado com `skipped`; `item.id` sempre `string`, `item.attempt`. Detalhes no [CHANGELOG](./CHANGELOG.md).
 - **5.0.0** — **uma API só de etapas** (breaking): `hobots.step(nome, fn, { retries, retryDelayMs }?)` abre a etapa, tenta de novo quando `fn` lança (default 1 tentativa extra) e fecha; `fn` recebe o handle `etapa` (`warning`/`image`/`data`); `hobots.step` dentro de outra (ou do handler do `items.each`) vira sub-etapa. `hobots.transaction`, `ctx.transaction` e os tipos `Transaction`/`Step`/`StepOutcomeOptions` foram removidos; `item.step` é o handle novo. Modo local ecoa `[hobots:step] FINISH …`. Nomes de etapa são recortados em 2048 no cliente. Flush automático ao fim da etapa raiz e de cada ciclo do `items.each` (`flush: false` desliga). Antes/depois no [CHANGELOG](./CHANGELOG.md).
 - **4.6.0** — **modo local** (`HOBOTS_LOCAL_RUN=1`): `register()`/`start()` rodam o handler uma vez sem Central, sem secret e sem rede, com params de `HOBOTS_RUN_PARAMS`; itens viram linhas `[hobots:item]` + `[hobots:summary]` no stdout, exit code 0/1/130; CLI `npx hobots run <entry.js> [--params] [--param] [--file] [--reset-ledger]`; `FileRef` local aceita `path` no modo local; eco `[hobots:progress] c/t` no stdout (paridade com o SDK Python).
 

package/dist/{chunk-HKCDMUA3.js → chunk-6YTOYIZM.js}

@@ -14,6 +14,7 @@ var protocol_limits_default = {
   MAX_ITEM_PAYLOAD_BYTES: 16384,
   MAX_ITEM_COLUMNS: 12,
   MAX_ITEM_COLUMN_LABEL_CHARS: 60,
+  MAX_ITEMS_DONE_PER_PAGE: 1e3,
   MAX_ATTACHMENT_BYTES: 5242880,
   MAX_ATTACHMENTS_PER_RUN: 20,
   MAX_ATTACHMENTS_PER_LOG_ENTRY: 4,
@@ -27,4 +28,4 @@ var WIRE_LIMITS = protocol_limits_default;
 export {
   WIRE_LIMITS
 };
-//# sourceMappingURL=chunk-HKCDMUA3.js.map
+//# sourceMappingURL=chunk-6YTOYIZM.js.map

package/dist/chunk-6YTOYIZM.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../protocol-limits.json","../src/wire-limits.ts"],"sourcesContent":["{\n  \"MAX_ITEMS_PER_ENVELOPE\": 50,\n  \"HEARTBEAT_DEFAULT_INTERVAL_MS\": 30000,\n  \"HEARTBEAT_MIN_INTERVAL_MS\": 1000,\n  \"HEARTBEAT_MAX_INTERVAL_MS\": 900000,\n  \"MAX_CLAIM_PER_POLL\": 5,\n  \"MAX_LOG_MESSAGE_CHARS\": 10000,\n  \"MAX_LOGS_PER_PATCH\": 100,\n  \"MAX_ERROR_MESSAGE_CHARS\": 10000,\n  \"MAX_ERROR_STACK_CHARS\": 20000,\n  \"MAX_ITEMS_PER_REQUEST\": 500,\n  \"MAX_ITEM_MESSAGE_CHARS\": 2000,\n  \"MAX_ITEM_PAYLOAD_BYTES\": 16384,\n  \"MAX_ITEM_COLUMNS\": 12,\n  \"MAX_ITEM_COLUMN_LABEL_CHARS\": 60,\n  \"MAX_ITEMS_DONE_PER_PAGE\": 1000,\n  \"MAX_ATTACHMENT_BYTES\": 5242880,\n  \"MAX_ATTACHMENTS_PER_RUN\": 20,\n  \"MAX_ATTACHMENTS_PER_LOG_ENTRY\": 4,\n  \"MAX_CAPTION_CHARS\": 200,\n  \"MAX_IMAGE_DIMENSION_PX\": 20000\n}\n","import limits from '../protocol-limits.json';\n\n/**\n * Limites do wire SDK ↔ servidor — fonte ÚNICA (protocol-limits.json): o SDK\n * Node lê daqui, a @hobots/api importa de `hobots/protocol` e o SDK Python\n * confere a paridade num teste que lê o mesmo JSON. Mudar um limite = mudar o\n * JSON (e, no Python, a constante espelhada — o teste acusa).\n */\nexport const WIRE_LIMITS = limits as Readonly<typeof limits>;\nexport type WireLimits = typeof WIRE_LIMITS;\n"],"mappings":";AAAA;AAAA,EACE,wBAA0B;AAAA,EAC1B,+BAAiC;AAAA,EACjC,2BAA6B;AAAA,EAC7B,2BAA6B;AAAA,EAC7B,oBAAsB;AAAA,EACtB,uBAAyB;AAAA,EACzB,oBAAsB;AAAA,EACtB,yBAA2B;AAAA,EAC3B,uBAAyB;AAAA,EACzB,uBAAyB;AAAA,EACzB,wBAA0B;AAAA,EAC1B,wBAA0B;AAAA,EAC1B,kBAAoB;AAAA,EACpB,6BAA+B;AAAA,EAC/B,yBAA2B;AAAA,EAC3B,sBAAwB;AAAA,EACxB,yBAA2B;AAAA,EAC3B,+BAAiC;AAAA,EACjC,mBAAqB;AAAA,EACrB,wBAA0B;AAC5B;;;ACbO,IAAM,cAAc;","names":[]}