hobots 5.2.0 → 6.1.0

package/dist/index.d.cts

@@ -270,14 +270,17 @@ interface RunItemOptions extends RunItemImageOptions {
     id?: string;
 }
 /**
- * O item em processamento dentro de `items.each`: o desfecho (`succeeded`/`failed`/
+ * O item em processamento dentro de `items.each` — o único argumento do handler: o elemento
+ * em `value`, a posição em `index`, o desfecho (`succeeded`/`failed`/
  * `occurrence`) com o `id` e o payload base já resolvidos, e o handle `step` da etapa do
  * item (`warning`/`image`/`data`), e `data(...)` para ir guardando o payload do item sem
  * decidir o desfecho. Sub-etapas: `hobots.step(...)` dentro do handler já
  * aninha na etapa do item. Sem chamada explícita, o SDK decide: retornou → `succeeded`;
  * lançou → `failed` com a mensagem do erro.
  */
-interface RunItemHandle {
+interface RunItemHandle<T = unknown> {
+    /** O elemento da lista — o mesmo em todas as tentativas. */
+    readonly value: T;
     /** Posição do elemento na lista (0-based). */
     readonly index: number;
     /** Identidade do item: a resolvida por `options.id` ou, sem ela, uma gerada pelo SDK — a mesma em todas as tentativas. */
@@ -288,6 +291,8 @@ interface RunItemHandle {
     readonly reported: boolean;
     /** Desfecho registrado até agora (undefined = nenhum). */
     readonly status: RunItemStatus | undefined;
+    /** Motivo do desfecho (`failed`/`occurrence`) — vai na linha `[item] FINISH` do log. */
+    readonly message: string | undefined;
     /** Tentativa em curso (1-based) — o handler pode ler para logar. */
     readonly attempt: number;
     /**
@@ -313,8 +318,13 @@ interface RunItemsEachOptions<T> {
      * no elemento é erro do bot (lança e interrompe o loop).
      */
     id?: string | readonly string[] | ((element: T, index: number) => string | number | null | undefined) | null;
-    /** Atributos base do item (viram colunas no app) — presentes em qualquer desfecho, inclusive falha. */
-    payload?: (element: T, index: number) => Record<string, unknown> | undefined;
+    /**
+     * Atributos base do item (viram colunas no app) — presentes em qualquer desfecho, inclusive falha.
+     * Omitido: os campos do próprio elemento quando ele é um objeto simples (`{ id, cliente, … }`,
+     * cópia rasa); instância de classe, array e primitivo ficam sem payload base. Uma função substitui
+     * esse padrão (escolhe/renomeia as colunas); `false` desliga.
+     */
+    payload?: ((element: T, index: number) => Record<string, unknown> | undefined) | false;
     /** `op` da etapa de cada item no waterfall. Default: 'item'. */
     op?: string;
     /** Descrição da etapa de cada item. Default: o `id`, senão `#<posição>`. */
@@ -351,7 +361,11 @@ interface RunItemsEachResult {
     /** Já concluídos neste trabalho (reexecução): não rodaram, mas contam no `total`. */
     skipped: number;
 }
-type RunItemsEachHandler<T> = (element: T, item: RunItemHandle, index: number) => unknown;
+/**
+ * Handler do `items.each` (6.0.0): `(item, index)` — o elemento em `item.value`; `index` (0-based,
+ * o mesmo que `item.index`) é opcional, declare só se usar.
+ */
+type RunItemsEachHandler<T> = (item: RunItemHandle<T>, index: number) => unknown;
 /**
  * Registro dos itens que a execução processou/gerou (a entrega do bot: notas
  * fiscais baixadas, boletos emitidos...). Chamadas são síncronas — os itens são

package/dist/index.d.ts

@@ -270,14 +270,17 @@ interface RunItemOptions extends RunItemImageOptions {
     id?: string;
 }
 /**
- * O item em processamento dentro de `items.each`: o desfecho (`succeeded`/`failed`/
+ * O item em processamento dentro de `items.each` — o único argumento do handler: o elemento
+ * em `value`, a posição em `index`, o desfecho (`succeeded`/`failed`/
  * `occurrence`) com o `id` e o payload base já resolvidos, e o handle `step` da etapa do
  * item (`warning`/`image`/`data`), e `data(...)` para ir guardando o payload do item sem
  * decidir o desfecho. Sub-etapas: `hobots.step(...)` dentro do handler já
  * aninha na etapa do item. Sem chamada explícita, o SDK decide: retornou → `succeeded`;
  * lançou → `failed` com a mensagem do erro.
  */
-interface RunItemHandle {
+interface RunItemHandle<T = unknown> {
+    /** O elemento da lista — o mesmo em todas as tentativas. */
+    readonly value: T;
     /** Posição do elemento na lista (0-based). */
     readonly index: number;
     /** Identidade do item: a resolvida por `options.id` ou, sem ela, uma gerada pelo SDK — a mesma em todas as tentativas. */
@@ -288,6 +291,8 @@ interface RunItemHandle {
     readonly reported: boolean;
     /** Desfecho registrado até agora (undefined = nenhum). */
     readonly status: RunItemStatus | undefined;
+    /** Motivo do desfecho (`failed`/`occurrence`) — vai na linha `[item] FINISH` do log. */
+    readonly message: string | undefined;
     /** Tentativa em curso (1-based) — o handler pode ler para logar. */
     readonly attempt: number;
     /**
@@ -313,8 +318,13 @@ interface RunItemsEachOptions<T> {
      * no elemento é erro do bot (lança e interrompe o loop).
      */
     id?: string | readonly string[] | ((element: T, index: number) => string | number | null | undefined) | null;
-    /** Atributos base do item (viram colunas no app) — presentes em qualquer desfecho, inclusive falha. */
-    payload?: (element: T, index: number) => Record<string, unknown> | undefined;
+    /**
+     * Atributos base do item (viram colunas no app) — presentes em qualquer desfecho, inclusive falha.
+     * Omitido: os campos do próprio elemento quando ele é um objeto simples (`{ id, cliente, … }`,
+     * cópia rasa); instância de classe, array e primitivo ficam sem payload base. Uma função substitui
+     * esse padrão (escolhe/renomeia as colunas); `false` desliga.
+     */
+    payload?: ((element: T, index: number) => Record<string, unknown> | undefined) | false;
     /** `op` da etapa de cada item no waterfall. Default: 'item'. */
     op?: string;
     /** Descrição da etapa de cada item. Default: o `id`, senão `#<posição>`. */
@@ -351,7 +361,11 @@ interface RunItemsEachResult {
     /** Já concluídos neste trabalho (reexecução): não rodaram, mas contam no `total`. */
     skipped: number;
 }
-type RunItemsEachHandler<T> = (element: T, item: RunItemHandle, index: number) => unknown;
+/**
+ * Handler do `items.each` (6.0.0): `(item, index)` — o elemento em `item.value`; `index` (0-based,
+ * o mesmo que `item.index`) é opcional, declare só se usar.
+ */
+type RunItemsEachHandler<T> = (item: RunItemHandle<T>, index: number) => unknown;
 /**
  * Registro dos itens que a execução processou/gerou (a entrega do bot: notas
  * fiscais baixadas, boletos emitidos...). Chamadas são síncronas — os itens são

package/dist/index.js

@@ -4,7 +4,7 @@ import {
 
 // src/utils.ts
 var SDK_NAME = "hobots";
-var SDK_VERSION = true ? "5.2.0" : "0.0.0-dev";
+var SDK_VERSION = true ? "6.1.0" : "0.0.0-dev";
 function isNode() {
   return typeof process !== "undefined" && typeof process.versions?.node === "string";
 }
@@ -1479,6 +1479,10 @@ function stepId() {
 function stepLabel(op, description) {
   return [op, description].filter(Boolean).join(" \u2014 ") || "(sem nome)";
 }
+var ITEM_OP = "item";
+function lifecycleLabel(kind, op, description) {
+  return stepLabel(kind === "item" && op === ITEM_OP ? void 0 : op, description);
+}
 function errorText(error) {
   if (error instanceof Error) return error.message || error.name;
   return safeString(error);
@@ -1511,21 +1515,25 @@ function colorForStatus(status) {
   }
 }
 var Step = class {
-  constructor(transaction, parentStepId, op, description) {
+  constructor(transaction, parentStepId, op, description, kind = "step") {
     this.transaction = transaction;
     this.parentStepId = parentStepId;
     this.op = op;
     this.description = description;
+    this.kind = kind;
   }
   transaction;
   parentStepId;
   op;
   description;
+  kind;
   stepId = stepId();
   startTimestamp = nowISO();
   status = "ok";
   endTimestamp;
   _data;
+  // desfecho que a linha de FINISH reporta no lugar do status da etapa (item do `each`)
+  outcome;
   // ── API do bot ────────────────────────────────────────────────────────────
   warning(message, options) {
     if (this.status !== "error") this._setStatus("warning", message);
@@ -1564,6 +1572,13 @@ var Step = class {
     this._close();
     return this;
   }
+  /**
+   * Faz a linha de FINISH reportar `status`/`reason` em vez do status da etapa — o
+   * `items.each` usa para o log do item seguir o desfecho dele (sucesso/falha/ocorrência).
+   */
+  _setOutcome(status, reason) {
+    this.outcome = { status, reason };
+  }
   _setData(key, value) {
     this._data = { ...this._data, [key]: value };
   }
@@ -1595,14 +1610,15 @@ var Step = class {
   _close() {
     if (this.endTimestamp) return;
     this.endTimestamp = nowISO();
+    const { status, reason } = this.outcome ?? { status: this.status, reason: this.reason() };
     this.transaction.emit(
-      "step",
+      this.kind,
       "finish",
-      stepLabel(this.op, this.description),
+      lifecycleLabel(this.kind, this.op, this.description),
       this.startTimestamp,
       this.endTimestamp,
-      this.status,
-      this.reason()
+      status,
+      reason
     );
   }
   toJSON() {
@@ -1657,7 +1673,7 @@ var Transaction = class {
   emit(kind, phase, label, startTs, endTs, status, reason) {
     const durationMs = startTs && endTs ? new Date(endTs).getTime() - new Date(startTs).getTime() : void 0;
     const suffix = (durationMs != null ? ` (${durationMs}ms)` : "") + (reason ? `: ${reason}` : "");
-    const localFinish = this.echo && kind === "step" && phase === "finish";
+    const localFinish = this.echo && kind !== "transaction" && phase === "finish";
     if (this.client?.debug || localFinish) {
       const tag = colorize(`[hobots:${kind}] ${phase.toUpperCase()}`, phase === "finish" ? colorForStatus(status ?? "ok") : "cyan");
       console.log(`${tag} ${label}${suffix}`);
@@ -1704,13 +1720,16 @@ var Transaction = class {
     if (!step) return fn();
     return runWithStepScope({ transaction: this, step }, fn);
   }
-  /** Abre uma etapa sob a corrente (ou direta da transaction). Interno: o bot usa `step()`. */
-  start(op, description) {
+  /**
+   * Abre uma etapa sob a corrente (ou direta da transaction). Interno: o bot usa `step()`; o
+   * `items.each` abre com `kind: 'item'` (linhas `[item] START/FINISH`).
+   */
+  start(op, description, kind = "step") {
     this.stepGuard?.();
     const parent = this.currentStep();
-    const step = new Step(this, parent ? parent.stepId : this.stepId, op, description);
+    const step = new Step(this, parent ? parent.stepId : this.stepId, op, description, kind);
     this.steps.push(step);
-    this.emit("step", "start", stepLabel(op, description));
+    this.emit(kind, "start", lifecycleLabel(kind, op, description));
     return step;
   }
   /**
@@ -1857,13 +1876,15 @@ function thrownMessage(error) {
   return safeString(error);
 }
 var ItemHandle = class {
-  constructor(index, id, step, basePayload, sink) {
+  constructor(value, index, id, step, basePayload2, sink) {
+    this.value = value;
     this.index = index;
     this.step = step;
-    this.basePayload = basePayload;
+    this.basePayload = basePayload2;
     this.sink = sink;
     this.id = id ?? uuid4();
   }
+  value;
   index;
   step;
   basePayload;
@@ -1872,6 +1893,7 @@ var ItemHandle = class {
   id;
   reported = false;
   status;
+  message;
   attempt = 1;
   accumulated = {};
   data(payload) {
@@ -1893,6 +1915,7 @@ var ItemHandle = class {
     this.attempt = attempt;
     this.reported = false;
     this.status = void 0;
+    this.message = void 0;
     this.accumulated = {};
     if (this.step && (this.step.status === "error" || this.step.status === "warning")) {
       this.step._setStatus("ok");
@@ -1902,10 +1925,23 @@ var ItemHandle = class {
   record(status, message, payload, image3) {
     this.reported = true;
     this.status = status;
+    this.message = message;
     const merged = { ...this.basePayload ?? {}, ...this.accumulated, ...payload ?? {} };
     this.sink.report(status, message, Object.keys(merged).length > 0 ? merged : void 0, this.id, image3);
   }
 };
+function defaultPayload(element) {
+  if (typeof element !== "object" || element === null) return void 0;
+  const proto = Object.getPrototypeOf(element);
+  if (proto !== Object.prototype && proto !== null) return void 0;
+  const copy = { ...element };
+  return Object.keys(copy).length > 0 ? copy : void 0;
+}
+function basePayload(spec, element, index) {
+  if (spec === false) return void 0;
+  if (spec === void 0) return defaultPayload(element);
+  return spec(element, index);
+}
 function field(element, name) {
   if (typeof element !== "object" || element === null) return { present: false, value: void 0 };
   const record = element;
@@ -1941,6 +1977,10 @@ function knownLength(list) {
   const length = list?.length;
   return typeof length === "number" && Number.isInteger(length) && length >= 1 ? length : void 0;
 }
+var ITEM_LOG_STATUS = { succeeded: "ok", occurrence: "warning", failed: "error" };
+function setItemOutcome(step, status, message) {
+  step._setOutcome(ITEM_LOG_STATUS[status], status === "succeeded" ? void 0 : message);
+}
 function skippedMessage(count) {
   if (count === 1) return "1 item pulado: j\xE1 conclu\xEDdo neste trabalho numa execu\xE7\xE3o anterior";
   return `${count} itens pulados: j\xE1 conclu\xEDdos neste trabalho numa execu\xE7\xE3o anterior`;
@@ -1950,23 +1990,34 @@ async function eachItem(list, handler, options, sink) {
   const requested = options.retries ?? DEFAULT_EACH_RETRIES;
   const totalRetries = Number.isFinite(requested) ? Math.max(0, Math.floor(requested)) : DEFAULT_EACH_RETRIES;
   const explicitId = options.id !== void 0;
-  const length = options.progress === false ? void 0 : knownLength(list);
-  if (length !== void 0) sink.declareTotal(length);
   const done = options.skipDone === false ? void 0 : await sink.doneItemIds();
-  let index = 0;
-  for await (const element of list) {
+  const isDone = (id) => id !== void 0 && done !== void 0 && done.has(id);
+  const length = knownLength(list);
+  let entries;
+  if (length !== void 0 && done !== void 0 && done.size > 0) {
+    const pending = [];
+    let position = 0;
+    for await (const element of list) {
+      const id = resolveId(options.id, element, position, explicitId);
+      if (isDone(id)) result.skipped += 1;
+      else pending.push({ element, index: position, id });
+      position += 1;
+    }
+    if (options.progress !== false && pending.length > 0) sink.declareTotal(pending.length);
+    entries = pending;
+  } else {
+    if (options.progress !== false && length !== void 0) sink.declareTotal(length);
+    entries = lazyEntries(list, options.id, explicitId);
+  }
+  for await (const { element, index, id } of entries) {
     sink.checkCanceled();
-    const id = resolveId(options.id, element, index, explicitId);
-    if (done?.size && id !== void 0 && done.has(id)) {
-      result.total += 1;
+    if (isDone(id)) {
       result.skipped += 1;
-      if (options.progress !== false) sink.advance();
-      index += 1;
       continue;
     }
     const description = options.description?.(element, index) ?? id ?? `#${index + 1}`;
     const step = sink.startStep(options.op ?? "item", description);
-    const handle = new ItemHandle(index, id, step, options.payload?.(element, index), sink);
+    const handle = new ItemHandle(element, index, id, step, basePayload(options.payload, element, index), sink);
     const current = index;
     let attempts = 0;
     let lastFailure;
@@ -1975,7 +2026,7 @@ async function eachItem(list, handler, options, sink) {
         (attempt) => {
           attempts = attempt;
           if (attempt > 1) handle._nextAttempt(attempt);
-          return sink.stepScope(step, async () => handler(element, handle, current));
+          return sink.stepScope(step, async () => handler(handle, current));
         },
         {
           retries: totalRetries,
@@ -2011,20 +2062,34 @@ async function eachItem(list, handler, options, sink) {
       } else {
         const message = thrownMessage(error);
         if (!handle.reported) handle.failed(message);
-        step?._failed(error);
+        if (step) {
+          setItemOutcome(step, handle.status ?? "failed", handle.message);
+          step._failed(error);
+        }
         sink.logError(`item ${description} falhou: ${message}`);
       }
     }
-    step?._close();
+    const final = handle.status ?? "succeeded";
+    if (step) {
+      setItemOutcome(step, final, handle.message);
+      step._close();
+    }
     if (options.progress !== false) sink.advance();
     result.total += 1;
-    result[handle.status ?? "succeeded"] += 1;
-    index += 1;
+    result[final] += 1;
     if (options.flush !== false) await sink.flush();
   }
+  result.total += result.skipped;
   if (result.skipped > 0) sink.logInfo(skippedMessage(result.skipped));
   return result;
 }
+async function* lazyEntries(list, spec, explicit) {
+  let index = 0;
+  for await (const element of list) {
+    yield { element, index, id: resolveId(spec, element, index, explicit) };
+    index += 1;
+  }
+}
 function noteAttempts(step, attempts) {
   if (attempts > 1) step._setData("attempts", attempts);
 }
@@ -2410,7 +2475,7 @@ var RunReporter = class {
     tx.setStepGuard(checkCanceled);
     const eachSink = {
       report: (status, message, payload, id, image3) => this.addItem(status, message, payload, id, image3),
-      startStep: (op, description) => tx.start(op, description),
+      startStep: (op, description) => tx.start(op, description, "item"),
       stepScope: (step, fn) => tx.scope(step, fn),
       declareTotal: (total) => {
         if (this.progressTotal == null) this.setProgress(this.progressCurrent, total);