hobots 2.0.0 → 2.2.0

package/README.md

@@ -113,7 +113,7 @@ try {
   await processarNota(nota);
 } catch (error) {
   Hobots.captureException(error, {
-    level: 'error',
+    type: 'error',
     tags: { cliente: 'acme' },
     fingerprint: ['sefaz-timeout'], // agrupa manualmente; sem isso o servidor agrupa pelo stack
   });
@@ -123,9 +123,9 @@ try {
 Hobots.captureMessage('Lote processado com sucesso', 'success');
 ```
 
-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`. Os eventos aparecem agrupados em issues no módulo **Issues** do app.
+Ambas retornam o `event_id` (ou `undefined` se não inicializado). O hint aceita `type`, `tags`, `extra` e `fingerprint`. Erros **não tratados** são capturados e flushados automaticamente antes do processo sair — desligue com `captureUnhandled: false`. Os eventos aparecem agrupados em issues no módulo **Issues** do app.
 
-`Severity = 'fatal' | 'error' | 'warning' | 'info' | 'debug' | 'success'`. Use `'success'` para reportar itens concluídos com êxito — contam como eventos, mas **não** viram issue nem disparam alertas.
+`EventType = 'fatal' | 'error' | 'warning' | 'success'`. Não há `'info'`/`'debug'`: narração não abre issue — para isso existem o log da execução e as breadcrumbs. Use `'success'` para reportar itens concluídos com êxito — contam como eventos, mas **não** viram issue nem disparam alertas.
 
 ### Breadcrumbs
 
@@ -261,6 +261,7 @@ interface RunContext {
   task: string;
   log: RunLogger; // ctx.log.debug/info/warn/error/success(message)
   items: RunItems; // ctx.items.succeeded/failed/occurrence — a entrega do bot
+  progress: RunProgressReporter; // ctx.progress.total/advance/set — barra + tempo restante no app
   tx: Transaction; // transaction desta run — correlacionada e finalizada pelo SDK
   signal: AbortSignal;
   throwIfCanceled(): void; // lança RunCanceled se o signal já disparou
@@ -271,6 +272,7 @@ interface RunContext {
 - **`params`** — os dados do formulário configurado no app (JSON validado). Tipável: `Hobots.register<{ lote: number }>(...)`.
 - **`ctx.log.<level>(message)`** — níveis `debug`, `info`, `warn`, `error` e `success`; logs enviados **incrementalmente** ao app (PATCHes com throttle), visíveis na solicitação quase em tempo real; também impressos no terminal local, coloridos por nível.
 - **`ctx.items`** — registra os **itens que a execução processou/gerou** (a entrega do bot: notas fiscais baixadas, boletos emitidos…), cada um com status `succeeded`, `failed` (falha técnica) ou `occurrence` (ocorrência de negócio, ex.: "nota nº 10 não encontrada") e um `payload` de atributos livres. Aparecem na aba **itens** da solicitação, com totalizadores; as colunas exibidas são configuradas por formulário no app. Guia: [Itens de execução](./docs/tasks.md#itens-de-execução-ctxitems).
+- **`ctx.progress`** — **opcional**: declare quantos itens a run vai processar (`ctx.progress.total(n)`) e avance a cada item (`ctx.progress.advance()`); o app mostra barra, percentual e tempo restante estimado na solicitação. Independente de `ctx.items`. Guia: [Progresso](./docs/tasks.md#progresso-da-execução-ctxprogress).
 - **`ctx.tx`** — a transaction de performance desta run, já correlacionada e finalizada pelo SDK. Use `ctx.tx.startChild(op, description)` para medir as etapas — elas viram o waterfall da execução no app. `startTransaction()` chamado dentro do handler retorna essa mesma transaction. Conceito: [ctx.tx](./docs/concepts.md#transaction-de-run-ctxtx).
 - **`ctx.signal`** — `AbortSignal` que dispara quando a run é **cancelada no app**, em **timeout** ou no **shutdown**.
 - **`ctx.throwIfCanceled()`** — o ponto de parada de uma linha; lança `RunCanceled` se o `signal` já disparou.
@@ -299,6 +301,23 @@ Hobots.register('baixar-notas', async (params, ctx) => {
 
 Chamadas síncronas e bufferizadas (lotes de até 500; dreno antes do reporte final). O `id` opcional é a identidade de negócio do item na run — repetido, é ignorado pelo servidor (registro único, retry idempotente). Limites: 10.000 itens/run, payload 16 KB, mensagem 2.000 caracteres. Detalhes em [Itens de execução](./docs/tasks.md#itens-de-execução-ctxitems).
 
+### Progresso (`ctx.progress`)
+
+Quando a run percorre uma lista conhecida, declare o total e avance a cada item — a solicitação no app ganha barra de progresso, percentual (`10/100 · 10%`) e **tempo restante estimado**:
+
+```js
+Hobots.register('baixar-notas', async (params, ctx) => {
+  const notas = await listarNotas(params);
+  ctx.progress.total(notas.length);
+  for (const nota of notas) {
+    await baixar(nota);
+    ctx.progress.advance();
+  }
+});
+```
+
+Opcional e independente de `ctx.items` (use um, outro ou ambos). Sem `total()` nada é enviado. Chamadas síncronas e baratas: o snapshot pega carona nos PATCHes de log e, no pior caso, sai 1 vez por segundo; o PATCH terminal sempre leva o valor final. `ctx.progress.set(current, total?)` define um valor absoluto; `ctx.progress.current` e `ctx.progress.snapshot` leem o estado. Detalhes em [Progresso da execução](./docs/tasks.md#progresso-da-execução-ctxprogress).
+
 ### Anexos (screenshots)
 
 Texto de log conta o que o robô fez; um print conta **como estava a tela**. Os métodos de captura (`Hobots.captureException` e `Hobots.captureMessage`) aceitam um `attachment` no hint: dentro de uma execução de task, a imagem vira anexo da linha de log da run que espelha a captura — no app ela aparece como miniatura logo abaixo dessa linha, clicável para ampliar.

package/dist/index.cjs

@@ -161,7 +161,7 @@ function scrubSecrets(text) {
 
 // src/utils.ts
 var SDK_NAME = "hobots";
-var SDK_VERSION = true ? "2.0.0" : "0.0.0-dev";
+var SDK_VERSION = true ? "2.2.0" : "0.0.0-dev";
 function isNode() {
   return typeof process !== "undefined" && typeof process.versions?.node === "string";
 }
@@ -291,34 +291,34 @@ function safeString(value) {
   }
   return String(value);
 }
-function eventFromException(error, level = "error") {
-  let type;
+function eventFromException(error, type = "error") {
+  let exceptionType;
   let value;
   let frames = [];
   if (error instanceof Error) {
-    type = error.name || "Error";
+    exceptionType = error.name || "Error";
     value = scrubSecrets(error.message);
     frames = parseStacktrace(error.stack);
   } else {
-    type = "NonError";
+    exceptionType = "NonError";
     value = scrubSecrets(safeString(error));
   }
   return {
     event_id: uuid4(),
     timestamp: nowISO(),
-    level,
+    type,
     exception: {
-      type,
+      type: exceptionType,
       value,
       ...frames.length > 0 ? { stacktrace: { frames } } : {}
     }
   };
 }
-function eventFromMessage(message, level = "info") {
+function eventFromMessage(message, type = "warning") {
   return {
     event_id: uuid4(),
     timestamp: nowISO(),
-    level,
+    type,
     message: scrubSecrets(message)
   };
 }
@@ -481,10 +481,10 @@ var Client = class {
     return `Client { baseUrl: '${this.#config.baseUrl}' }`;
   }
   captureException(error, hint, scope2) {
-    return this.captureEvent(eventFromException(error, hint?.level ?? "error"), hint, scope2);
+    return this.captureEvent(eventFromException(error, hint?.type ?? "error"), hint, scope2);
   }
-  captureMessage(message, level, hint, scope2) {
-    return this.captureEvent(eventFromMessage(message, level), hint, scope2);
+  captureMessage(message, type, hint, scope2) {
+    return this.captureEvent(eventFromMessage(message, type), hint, scope2);
   }
   captureEvent(event, hint, scope2) {
     const sampleRate = this.options.sampleRate ?? 1;
@@ -506,7 +506,7 @@ var Client = class {
     const extra = { ...scope2.extra, ...event.extra, ...hint?.extra };
     return {
       ...event,
-      level: hint?.level ?? event.level ?? scope2.level ?? "error",
+      type: hint?.type ?? event.type ?? scope2.type ?? "error",
       release: event.release ?? this.options.release,
       environment: event.environment ?? this.options.environment ?? "production",
       tags: Object.keys(tags).length > 0 ? tags : void 0,
@@ -624,7 +624,7 @@ function installGlobalHandlers(client2, getScope) {
     process.on(
       "uncaughtException",
       markInternal((error) => {
-        client2.captureException(error, { level: "fatal", tags: { mechanism: "uncaughtException" } }, getScope());
+        client2.captureException(error, { type: "fatal", tags: { mechanism: "uncaughtException" } }, getScope());
         void client2.flush(2e3).then(async () => {
           if (externalListenerCount("uncaughtException") === 0) {
             await awaitEmergencyTasks(EMERGENCY_REPORT_CAP_MS);
@@ -637,7 +637,7 @@ function installGlobalHandlers(client2, getScope) {
     process.on(
       "unhandledRejection",
       markInternal((reason) => {
-        client2.captureException(reason, { level: "error", tags: { mechanism: "unhandledRejection" } }, getScope());
+        client2.captureException(reason, { type: "error", tags: { mechanism: "unhandledRejection" } }, getScope());
         void client2.flush(2e3);
       })
     );
@@ -668,7 +668,7 @@ var Scope = class _Scope {
   user;
   contexts = {};
   extra = {};
-  level;
+  type;
   fingerprint;
   breadcrumbs = [];
   setTag(key, value) {
@@ -699,8 +699,8 @@ var Scope = class _Scope {
     Object.assign(this.extra, extras);
     return this;
   }
-  setLevel(level) {
-    this.level = level;
+  setType(type) {
+    this.type = type;
     return this;
   }
   setFingerprint(fingerprint) {
@@ -724,7 +724,7 @@ var Scope = class _Scope {
     next.user = this.user ? { ...this.user } : void 0;
     next.contexts = Object.fromEntries(Object.entries(this.contexts).map(([k, v]) => [k, { ...v }]));
     next.extra = { ...this.extra };
-    next.level = this.level;
+    next.type = this.type;
     next.fingerprint = this.fingerprint ? [...this.fingerprint] : void 0;
     next.breadcrumbs = [...this.breadcrumbs];
     return next;
@@ -1201,6 +1201,7 @@ var MAX_ITEM_MESSAGE_CHARS = 2e3;
 var MAX_ITEM_PAYLOAD_BYTES = 16384;
 var ITEMS_FLUSH_AT_BUFFERED = 100;
 var ITEMS_DRAIN_MS = 15e3;
+var PROGRESS_FLUSH_MS = 1e3;
 function scrubPayloadValue(value, depth) {
   if (typeof value === "string") return scrubSecrets(value);
   if (depth >= 4 || value === null || typeof value !== "object") return value;
@@ -1235,12 +1236,28 @@ var RunReporter = class {
       failed: (message, payload, options) => this.addItem("failed", message, payload, options?.id),
       occurrence: (message, payload, options) => this.addItem("occurrence", message, payload, options?.id)
     };
+    const progress = Object.defineProperties(
+      {
+        total: (total) => this.setProgress(this.progressCurrent, total),
+        advance: (count = 1) => this.setProgress(this.progressCurrent + count, this.progressTotal),
+        set: (current, total) => this.setProgress(current, total ?? this.progressTotal)
+      },
+      {
+        current: { enumerable: true, get: () => this.progressCurrent },
+        snapshot: {
+          enumerable: true,
+          get: () => this.progressTotal == null ? null : { current: this.progressCurrent, total: this.progressTotal }
+        }
+      }
+      // defineProperties não tipa os getters adicionados — a interface é a fonte de verdade
+    );
     const signal = this.abortController.signal;
     this.context = {
       runId,
       task,
       log,
       items,
+      progress,
       tx,
       signal,
       throwIfCanceled: () => {
@@ -1284,6 +1301,14 @@ var RunReporter = class {
   uploadQueue = [];
   /** Uma vez que a instalação recusa anexos, para de tentar (e de avisar) nesta run. */
   attachmentsUnsupported = false;
+  // Progresso (ctx.progress): snapshot absoluto, enviado com throttle via piggyback
+  // em `enqueue()` — nunca gera tráfego próprio enquanto logs/heartbeat já fluem.
+  progressCurrent = 0;
+  progressTotal = null;
+  /** Snapshot ainda não entregue ao servidor. */
+  progressDirty = false;
+  progressTimer;
+  progressWarned = false;
   get isDead() {
     return this.dead;
   }
@@ -1301,6 +1326,7 @@ var RunReporter = class {
     this.abort();
     this.dead = true;
     this.clearFlushTimer();
+    this.clearProgressTimer();
     this.buffer = [];
     this.itemsClosed = true;
     this.clearItemsTimer();
@@ -1380,13 +1406,63 @@ var RunReporter = class {
   reportSuccess() {
     this.stopCancelWatch();
     this.clearFlushTimer();
+    this.forceFinalProgress();
     this.enqueue({ status: "succeeded", logs: this.takeLogs() });
   }
   reportFailure(error) {
     this.stopCancelWatch();
     this.clearFlushTimer();
+    this.forceFinalProgress();
     this.enqueue({ status: "failed", error, logs: this.takeLogs() });
   }
+  // ── Progresso ────────────────────────────────────────────────────────────────
+  /** Valida, clampa e marca o snapshot como pendente; agenda flush só se nada mais vai sair. */
+  setProgress(current, total) {
+    if (this.dead) return;
+    if (total != null && (!Number.isInteger(total) || total < 1)) {
+      if (!this.progressWarned) {
+        this.progressWarned = true;
+        this.logger.warn(`ctx.progress: total inv\xE1lido (${String(total)}) \u2014 precisa ser inteiro >= 1; ignorado`);
+      }
+      return;
+    }
+    const safeCurrent = Number.isFinite(current) ? Math.max(0, Math.floor(current)) : this.progressCurrent;
+    const next = total == null ? safeCurrent : Math.min(safeCurrent, total);
+    if (next === this.progressCurrent && total === this.progressTotal) return;
+    this.progressCurrent = next;
+    this.progressTotal = total;
+    if (total == null) return;
+    this.progressDirty = true;
+    if (this.progressTimer) return;
+    this.progressTimer = setTimeout(() => {
+      this.progressTimer = void 0;
+      this.flushProgress();
+    }, PROGRESS_FLUSH_MS);
+    unrefTimer(this.progressTimer);
+  }
+  flushProgress() {
+    this.clearProgressTimer();
+    if (this.dead || !this.progressDirty) return;
+    if (this.buffer.length > 0) this.flushLogs();
+    else this.enqueue({ status: "running" });
+  }
+  clearProgressTimer() {
+    if (this.progressTimer) {
+      clearTimeout(this.progressTimer);
+      this.progressTimer = void 0;
+    }
+  }
+  /** O PATCH terminal sempre leva o snapshot final (o app mostra "87/100" numa run que falhou). */
+  forceFinalProgress() {
+    this.clearProgressTimer();
+    this.progressDirty = this.progressTotal != null;
+  }
+  /** Consome o snapshot pendente para pegar carona no próximo PATCH. */
+  takeProgress() {
+    if (!this.progressDirty || this.progressTotal == null) return void 0;
+    this.progressDirty = false;
+    return { current: this.progressCurrent, total: this.progressTotal };
+  }
   /**
    * Heartbeat de cancelamento: enquanto o handler roda, um PATCH 'running' vazio
    * periódico faz o servidor responder 409 se a run foi cancelada no app — o que
@@ -1649,11 +1725,14 @@ var RunReporter = class {
       new Promise((resolve) => unrefTimer(setTimeout(resolve, timeoutMs)))
     ]);
   }
-  enqueue(update) {
+  enqueue(updateIn) {
     if (this.dead) {
-      this.salvageLogs(update.logs);
+      this.salvageLogs(updateIn.logs);
       return;
     }
+    this.clearProgressTimer();
+    const progress = this.takeProgress();
+    const update = progress ? { ...updateIn, progress } : updateIn;
     this.pendingUpdates++;
     this.chain = this.chain.then(async () => {
       if (this.dead) {
@@ -1679,6 +1758,7 @@ var RunReporter = class {
           this.buffer.unshift(...update.logs);
           this.scheduleFlush();
         }
+        if (update.progress && this.progressTotal != null) this.progressDirty = true;
         this.logger.error(`update da run ${this.runId} perdido:`, error);
       }
     }).finally(() => {
@@ -2084,10 +2164,10 @@ function init(options) {
 function getClient() {
   return client;
 }
-function toRunLogLevel(level) {
-  return level === "fatal" ? "error" : level;
+function toRunLogLevel(type) {
+  return type === "fatal" ? "error" : type;
 }
-function forwardAttachment(attachment, message, level) {
+function forwardAttachment(attachment, message, type) {
   const attach = currentRunAttach();
   if (!attach) {
     client?.logger.warn("attachment descartado \u2014 s\xF3 \xE9 suportado dentro de uma execu\xE7\xE3o de task (register/start)");
@@ -2096,7 +2176,7 @@ function forwardAttachment(attachment, message, level) {
   const withMeta = typeof attachment === "object" && "image" in attachment ? attachment : { image: attachment };
   void attach(withMeta.image, {
     message,
-    level: toRunLogLevel(level),
+    level: toRunLogLevel(type),
     caption: withMeta.caption,
     contentType: withMeta.contentType
   });
@@ -2104,15 +2184,15 @@ function forwardAttachment(attachment, message, level) {
 function captureException(error, hint) {
   if (hint?.attachment) {
     const message = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
-    forwardAttachment(hint.attachment, message, hint.level ?? "error");
+    forwardAttachment(hint.attachment, message, hint.type ?? "error");
   }
   return client?.captureException(error, hint, scope);
 }
-function captureMessage(message, level = "info", hint) {
+function captureMessage(message, type = "warning", hint) {
   if (hint?.attachment) {
-    forwardAttachment(hint.attachment, message, hint.level ?? level);
+    forwardAttachment(hint.attachment, message, hint.type ?? type);
   }
-  return client?.captureMessage(message, level, hint, scope);
+  return client?.captureMessage(message, type, hint, scope);
 }
 function addBreadcrumb(crumb) {
   scope.addBreadcrumb(crumb, client?.options.maxBreadcrumbs ?? DEFAULT_MAX_BREADCRUMBS);