hobots 2.0.1 → 2.2.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { Breadcrumb, EventUser, EventType, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, RunLogLevel, StepData, RunItemStatus, RunAttachmentContentType } from './protocol.cjs';
+import { Breadcrumb, EventUser, EventType, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, RunLogLevel, StepData, RunItemStatus, RunProgress, RunAttachmentContentType } from './protocol.cjs';
 export { BreadcrumbLevel, Envelope, EnvelopeItem, ExceptionData, InstanceInfo, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunDescriptor, RunError, RunItemInput, RunItemsCreateRequest, RunItemsCreateResponse, RunLogEntry, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame } from './protocol.cjs';
 
 /** Aceita tudo que o handler pode ter em mãos: bytes ou um caminho de arquivo (só Node). */
@@ -198,6 +198,24 @@ interface RunItems {
     /** Ocorrência de negócio (ex.: "nota nº 10 não encontrada") — não é falha do bot. */
     occurrence(message: string, payload?: Record<string, unknown>, options?: RunItemOptions): void;
 }
+/**
+ * Progresso da execução (itens processados / total) — opcional e independente de
+ * `ctx.items`. Declare o total antes do loop e avance a cada item: a plataforma e o
+ * Studio mostram barra, percentual e tempo restante estimado. Sem `total()` nada é
+ * enviado. Chamadas são síncronas e baratas (≤ 1 PATCH/s, pegando carona nos logs).
+ */
+interface RunProgressReporter {
+    /** Declara (ou ajusta) o total de itens previsto — inteiro >= 1. Idempotente. */
+    total(total: number): void;
+    /** Incrementa os processados (padrão 1). Clampa em `total`. */
+    advance(count?: number): void;
+    /** Define o valor absoluto de processados e, opcionalmente, o total. */
+    set(current: number, total?: number): void;
+    /** Processados até agora (0 antes de qualquer chamada). */
+    readonly current: number;
+    /** `{ current, total }` quando há total declarado; null caso contrário. */
+    readonly snapshot: RunProgress | null;
+}
 interface RunContext {
     runId: string;
     task: string;
@@ -205,6 +223,8 @@ interface RunContext {
     log: RunLogger;
     /** Itens processados/gerados pela execução — a entrega do bot, com status e atributos */
     items: RunItems;
+    /** Progresso declarado (barra + ETA no app) — opcional, independente de `ctx.items` */
+    progress: RunProgressReporter;
     /**
      * Transaction de performance desta execução — já correlacionada à run e finalizada
      * automaticamente ao fim do handler. Use `ctx.tx.startChild(op, description)` pra medir
@@ -336,4 +356,4 @@ declare function close(timeoutMs?: number): Promise<boolean>;
 
 declare function scrubSecrets(text: string): string;
 
-export { type AttachInput, Breadcrumb, type BreadcrumbInput, type CaptureAttachment, type CaptureHint, Client, DEFAULT_BASE_URL, EventPayload, EventType, EventUser, type HeartbeatOptions, HeartbeatPayload, type InitOptions, RunAttachmentContentType, type RunContext, type RunItemOptions, RunItemStatus, type RunItems, RunLogLevel, Scope, Step, StepData, type TaskHandler, type TasksOptions, Transaction, TransactionPayload, addBreadcrumb, captureException, captureMessage, close, flush, getClient, init, register, scrubSecrets, setContext, setExtra, setTag, setTags, setUser, start, startTransaction, stop, withScope };
+export { type AttachInput, Breadcrumb, type BreadcrumbInput, type CaptureAttachment, type CaptureHint, Client, DEFAULT_BASE_URL, EventPayload, EventType, EventUser, type HeartbeatOptions, HeartbeatPayload, type InitOptions, RunAttachmentContentType, type RunContext, type RunItemOptions, RunItemStatus, type RunItems, RunLogLevel, RunProgress, type RunProgressReporter, Scope, Step, StepData, type TaskHandler, type TasksOptions, Transaction, TransactionPayload, addBreadcrumb, captureException, captureMessage, close, flush, getClient, init, register, scrubSecrets, setContext, setExtra, setTag, setTags, setUser, start, startTransaction, stop, withScope };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Breadcrumb, EventUser, EventType, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, RunLogLevel, StepData, RunItemStatus, RunAttachmentContentType } from './protocol.js';
+import { Breadcrumb, EventUser, EventType, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, RunLogLevel, StepData, RunItemStatus, RunProgress, RunAttachmentContentType } from './protocol.js';
 export { BreadcrumbLevel, Envelope, EnvelopeItem, ExceptionData, InstanceInfo, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunDescriptor, RunError, RunItemInput, RunItemsCreateRequest, RunItemsCreateResponse, RunLogEntry, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame } from './protocol.js';
 
 /** Aceita tudo que o handler pode ter em mãos: bytes ou um caminho de arquivo (só Node). */
@@ -198,6 +198,24 @@ interface RunItems {
     /** Ocorrência de negócio (ex.: "nota nº 10 não encontrada") — não é falha do bot. */
     occurrence(message: string, payload?: Record<string, unknown>, options?: RunItemOptions): void;
 }
+/**
+ * Progresso da execução (itens processados / total) — opcional e independente de
+ * `ctx.items`. Declare o total antes do loop e avance a cada item: a plataforma e o
+ * Studio mostram barra, percentual e tempo restante estimado. Sem `total()` nada é
+ * enviado. Chamadas são síncronas e baratas (≤ 1 PATCH/s, pegando carona nos logs).
+ */
+interface RunProgressReporter {
+    /** Declara (ou ajusta) o total de itens previsto — inteiro >= 1. Idempotente. */
+    total(total: number): void;
+    /** Incrementa os processados (padrão 1). Clampa em `total`. */
+    advance(count?: number): void;
+    /** Define o valor absoluto de processados e, opcionalmente, o total. */
+    set(current: number, total?: number): void;
+    /** Processados até agora (0 antes de qualquer chamada). */
+    readonly current: number;
+    /** `{ current, total }` quando há total declarado; null caso contrário. */
+    readonly snapshot: RunProgress | null;
+}
 interface RunContext {
     runId: string;
     task: string;
@@ -205,6 +223,8 @@ interface RunContext {
     log: RunLogger;
     /** Itens processados/gerados pela execução — a entrega do bot, com status e atributos */
     items: RunItems;
+    /** Progresso declarado (barra + ETA no app) — opcional, independente de `ctx.items` */
+    progress: RunProgressReporter;
     /**
      * Transaction de performance desta execução — já correlacionada à run e finalizada
      * automaticamente ao fim do handler. Use `ctx.tx.startChild(op, description)` pra medir
@@ -336,4 +356,4 @@ declare function close(timeoutMs?: number): Promise<boolean>;
 
 declare function scrubSecrets(text: string): string;
 
-export { type AttachInput, Breadcrumb, type BreadcrumbInput, type CaptureAttachment, type CaptureHint, Client, DEFAULT_BASE_URL, EventPayload, EventType, EventUser, type HeartbeatOptions, HeartbeatPayload, type InitOptions, RunAttachmentContentType, type RunContext, type RunItemOptions, RunItemStatus, type RunItems, RunLogLevel, Scope, Step, StepData, type TaskHandler, type TasksOptions, Transaction, TransactionPayload, addBreadcrumb, captureException, captureMessage, close, flush, getClient, init, register, scrubSecrets, setContext, setExtra, setTag, setTags, setUser, start, startTransaction, stop, withScope };
+export { type AttachInput, Breadcrumb, type BreadcrumbInput, type CaptureAttachment, type CaptureHint, Client, DEFAULT_BASE_URL, EventPayload, EventType, EventUser, type HeartbeatOptions, HeartbeatPayload, type InitOptions, RunAttachmentContentType, type RunContext, type RunItemOptions, RunItemStatus, type RunItems, RunLogLevel, RunProgress, type RunProgressReporter, Scope, Step, StepData, type TaskHandler, type TasksOptions, Transaction, TransactionPayload, addBreadcrumb, captureException, captureMessage, close, flush, getClient, init, register, scrubSecrets, setContext, setExtra, setTag, setTags, setUser, start, startTransaction, stop, withScope };

package/dist/index.js

@@ -103,7 +103,7 @@ function scrubSecrets(text) {
 
 // src/utils.ts
 var SDK_NAME = "hobots";
-var SDK_VERSION = true ? "2.0.1" : "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";
 }
@@ -1143,6 +1143,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;
@@ -1177,12 +1178,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: () => {
@@ -1226,6 +1243,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;
   }
@@ -1243,6 +1268,7 @@ var RunReporter = class {
     this.abort();
     this.dead = true;
     this.clearFlushTimer();
+    this.clearProgressTimer();
     this.buffer = [];
     this.itemsClosed = true;
     this.clearItemsTimer();
@@ -1322,13 +1348,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
@@ -1591,11 +1667,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) {
@@ -1621,6 +1700,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(() => {