hobots 1.9.2 → 1.10.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { Breadcrumb, EventUser, Severity, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, RunLogLevel, StepData, RunAttachmentContentType } from './protocol.cjs';
-export { AgentInfo, Envelope, EnvelopeItem, ExceptionData, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunDescriptor, RunError, RunLogEntry, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame } from './protocol.cjs';
+import { Breadcrumb, EventUser, Severity, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, RunLogLevel, StepData, RunItemStatus, RunAttachmentContentType } from './protocol.cjs';
+export { AgentInfo, Envelope, EnvelopeItem, ExceptionData, 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). */
 type AttachInput = Uint8Array | ArrayBuffer | string;
@@ -167,11 +167,41 @@ interface RunLogger {
     error(message: string): void;
     success(message: string): void;
 }
+interface RunItemOptions {
+    /**
+     * Identidade de negócio do item na run (ex.: nº da nota fiscal). Repetido na
+     * mesma run = ignorado pelo servidor (registro único, retry idempotente).
+     * Omitido: o SDK gera um id único e cada chamada vira um item novo.
+     */
+    id?: string;
+}
+/**
+ * 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
+ * bufferizados e enviados em lotes; o agente drena o buffer antes do reporte final.
+ */
+interface RunItems {
+    /** Forma genérica — os atalhos succeeded/failed/occurrence cobrem o dia a dia. */
+    add(item: {
+        status: RunItemStatus;
+        id?: string;
+        message?: string;
+        payload?: Record<string, unknown>;
+    }): void;
+    /** Item processado com sucesso. `payload` = atributos do item (viram colunas na plataforma). */
+    succeeded(payload?: Record<string, unknown>, options?: RunItemOptions): void;
+    /** Falha técnica ao processar o item — `message` é o motivo exibido na plataforma. */
+    failed(message: string, payload?: Record<string, unknown>, options?: RunItemOptions): void;
+    /** 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;
+}
 interface RunContext {
     runId: string;
     task: string;
     /** Log bufferizado — enviado ao servidor em PATCHes incrementais com throttle */
     log: RunLogger;
+    /** Itens processados/gerados pela execução — a entrega do bot, com status e atributos */
+    items: RunItems;
     /**
      * Transaction de performance desta execução — já correlacionada à run e finalizada
      * automaticamente ao fim do handler. Use `ctx.tx.startChild(op, description)` pra medir
@@ -303,4 +333,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, EventUser, type HeartbeatOptions, HeartbeatPayload, type InitOptions, RunAttachmentContentType, type RunContext, RunLogLevel, Scope, Severity, 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, EventUser, type HeartbeatOptions, HeartbeatPayload, type InitOptions, RunAttachmentContentType, type RunContext, type RunItemOptions, RunItemStatus, type RunItems, RunLogLevel, Scope, Severity, 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,5 +1,5 @@
-import { Breadcrumb, EventUser, Severity, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, RunLogLevel, StepData, RunAttachmentContentType } from './protocol.js';
-export { AgentInfo, Envelope, EnvelopeItem, ExceptionData, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunDescriptor, RunError, RunLogEntry, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame } from './protocol.js';
+import { Breadcrumb, EventUser, Severity, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, RunLogLevel, StepData, RunItemStatus, RunAttachmentContentType } from './protocol.js';
+export { AgentInfo, Envelope, EnvelopeItem, ExceptionData, 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). */
 type AttachInput = Uint8Array | ArrayBuffer | string;
@@ -167,11 +167,41 @@ interface RunLogger {
     error(message: string): void;
     success(message: string): void;
 }
+interface RunItemOptions {
+    /**
+     * Identidade de negócio do item na run (ex.: nº da nota fiscal). Repetido na
+     * mesma run = ignorado pelo servidor (registro único, retry idempotente).
+     * Omitido: o SDK gera um id único e cada chamada vira um item novo.
+     */
+    id?: string;
+}
+/**
+ * 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
+ * bufferizados e enviados em lotes; o agente drena o buffer antes do reporte final.
+ */
+interface RunItems {
+    /** Forma genérica — os atalhos succeeded/failed/occurrence cobrem o dia a dia. */
+    add(item: {
+        status: RunItemStatus;
+        id?: string;
+        message?: string;
+        payload?: Record<string, unknown>;
+    }): void;
+    /** Item processado com sucesso. `payload` = atributos do item (viram colunas na plataforma). */
+    succeeded(payload?: Record<string, unknown>, options?: RunItemOptions): void;
+    /** Falha técnica ao processar o item — `message` é o motivo exibido na plataforma. */
+    failed(message: string, payload?: Record<string, unknown>, options?: RunItemOptions): void;
+    /** 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;
+}
 interface RunContext {
     runId: string;
     task: string;
     /** Log bufferizado — enviado ao servidor em PATCHes incrementais com throttle */
     log: RunLogger;
+    /** Itens processados/gerados pela execução — a entrega do bot, com status e atributos */
+    items: RunItems;
     /**
      * Transaction de performance desta execução — já correlacionada à run e finalizada
      * automaticamente ao fim do handler. Use `ctx.tx.startChild(op, description)` pra medir
@@ -303,4 +333,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, EventUser, type HeartbeatOptions, HeartbeatPayload, type InitOptions, RunAttachmentContentType, type RunContext, RunLogLevel, Scope, Severity, 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, EventUser, type HeartbeatOptions, HeartbeatPayload, type InitOptions, RunAttachmentContentType, type RunContext, type RunItemOptions, RunItemStatus, type RunItems, RunLogLevel, Scope, Severity, 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 ? "1.9.1" : "0.0.0-dev";
+var SDK_VERSION = true ? "1.10.0" : "0.0.0-dev";
 function isNode() {
   return typeof process !== "undefined" && typeof process.versions?.node === "string";
 }
@@ -929,6 +929,38 @@ var TasksApi = class {
       signal: AbortSignal.timeout(timeoutMs)
     });
   }
+  /**
+   * Envia um lote de itens de execução. Retry em falha de rede/5xx/429-transporte;
+   * 4xx é definitivo (404 = servidor sem o recurso, 429 = cap de itens por run) —
+   * o RunReporter trata por status.
+   */
+  async createItems(runId, request) {
+    let response;
+    try {
+      response = await fetchWithRetry(
+        () => fetch(`${this.baseUrl}/runs/${encodeURIComponent(runId)}/items`, {
+          method: "POST",
+          headers: this.headers(),
+          body: JSON.stringify(request),
+          signal: AbortSignal.timeout(UPDATE_TIMEOUT_MS)
+        }),
+        { logger: this.logger, label: `itens da run ${runId}` }
+      );
+    } catch (error) {
+      if (error instanceof Error && error.message === "HTTP 429") {
+        throw new TasksApiError("envio de itens rejeitado (HTTP 429)", 429);
+      }
+      throw new Error(`envio de itens da run ${runId} descartado ap\xF3s retries: ${String(error)}`);
+    }
+    if (!response.ok) {
+      throw new TasksApiError(`envio de itens rejeitado (HTTP ${response.status})`, response.status);
+    }
+    const body = await response.json().catch(() => null);
+    return {
+      accepted: typeof body?.accepted === "number" ? body.accepted : request.items.length,
+      duplicates: typeof body?.duplicates === "number" ? body.duplicates : 0
+    };
+  }
   /**
    * Registra o anexo e obtém a URL presignada de upload. 404/501/503 significam
    * "esta instalação não tem anexos" — o RunReporter degrada em silêncio a partir daí.
@@ -1086,6 +1118,22 @@ var MAX_CANCEL_CHECK_INTERVAL_MS = 15e3;
 var MAX_LOG_MESSAGE_CHARS = 1e4;
 var MAX_LOGS_PER_PATCH = 100;
 var FLUSH_AT_BUFFERED = 20;
+var MAX_ITEMS_PER_RUN = 1e4;
+var MAX_ITEMS_PER_REQUEST = 500;
+var MAX_ITEM_MESSAGE_CHARS = 2e3;
+var MAX_ITEM_PAYLOAD_BYTES = 16384;
+var ITEMS_FLUSH_AT_BUFFERED = 100;
+var ITEMS_DRAIN_MS = 15e3;
+function scrubPayloadValue(value, depth) {
+  if (typeof value === "string") return scrubSecrets(value);
+  if (depth >= 4 || value === null || typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map((entry) => scrubPayloadValue(entry, depth + 1));
+  const out = {};
+  for (const [key, entry] of Object.entries(value)) {
+    out[key] = scrubPayloadValue(entry, depth + 1);
+  }
+  return out;
+}
 var RunReporter = class {
   constructor(api, runId, task, logger, tx, flushIntervalMs, cancelCheckIntervalMs) {
     this.api = api;
@@ -1104,11 +1152,18 @@ var RunReporter = class {
       success: (message) => this.log("success", message)
     };
     tx.setLifecycleSink((level, message) => this.push(level, message));
+    const items = {
+      add: (item) => this.addItem(item.status, item.message, item.payload, item.id),
+      succeeded: (payload, options) => this.addItem("succeeded", void 0, payload, options?.id),
+      failed: (message, payload, options) => this.addItem("failed", message, payload, options?.id),
+      occurrence: (message, payload, options) => this.addItem("occurrence", message, payload, options?.id)
+    };
     const signal = this.abortController.signal;
     this.context = {
       runId,
       task,
       log,
+      items,
       tx,
       signal,
       throwIfCanceled: () => {
@@ -1127,6 +1182,23 @@ var RunReporter = class {
   abortController = new AbortController();
   flushIntervalMs;
   cancelCheckIntervalMs;
+  // Itens de execução vivem FORA de `this.chain` (status/liveness não pode ficar
+  // atrás de milhares de itens), mas têm cadeia própria serializada — ordem de
+  // envio preservada e sem lotes sobrepostos.
+  itemsBuffer = [];
+  itemsChain = Promise.resolve();
+  itemsTimer;
+  itemSeq = 0;
+  itemCount = 0;
+  /** Servidor sem o recurso (404) — para de tentar (e de avisar) nesta run. */
+  itemsUnsupported = false;
+  /** Cap de itens por run atingido (client-side ou 429) — degrada com um aviso só. */
+  itemsQuotaExceeded = false;
+  /**
+   * Só o kill() do exit path fecha os itens — `dead` (run cancelada/finalizada no
+   * servidor) NÃO fecha: o servidor aceita itens de run terminal (trabalho já feito).
+   */
+  itemsClosed = false;
   // Uploads de anexo vivem FORA de `this.chain`: a cadeia é um FIFO puro de
   // status/logs e não pode ficar bloqueada esperando um binário subir.
   pendingAttachments = /* @__PURE__ */ new Set();
@@ -1153,6 +1225,12 @@ var RunReporter = class {
     this.dead = true;
     this.clearFlushTimer();
     this.buffer = [];
+    this.itemsClosed = true;
+    this.clearItemsTimer();
+    if (this.itemsBuffer.length > 0) {
+      this.logger.warn(`${this.itemsBuffer.length} item(ns) de execu\xE7\xE3o descartados (processo encerrando)`);
+      this.itemsBuffer = [];
+    }
     const waiting = this.uploadQueue.splice(0, this.uploadQueue.length);
     for (const resume of waiting) resume();
   }
@@ -1255,6 +1333,120 @@ var RunReporter = class {
   finalize() {
     return this.chain;
   }
+  // ── Itens de execução ────────────────────────────────────────────────────────
+  /**
+   * Bufferiza um item (síncrono — a chamada nunca espera rede). Diferente do PATCH
+   * de status, o servidor aceita itens mesmo com a run cancelada (trabalho já feito),
+   * então um reporter morto não descarta: só um kill() de exit path descarta.
+   */
+  addItem(status, message, payload, id) {
+    if (this.itemsClosed || this.itemsUnsupported) return;
+    if (this.itemCount >= MAX_ITEMS_PER_RUN) {
+      if (!this.itemsQuotaExceeded) {
+        this.itemsQuotaExceeded = true;
+        this.log("warning", `itens descartados: limite de ${MAX_ITEMS_PER_RUN} por execu\xE7\xE3o atingido`);
+      }
+      return;
+    }
+    this.itemCount++;
+    let scrubbedPayload;
+    if (payload) {
+      scrubbedPayload = scrubPayloadValue(payload, 0);
+      let serializedLength;
+      try {
+        serializedLength = JSON.stringify(scrubbedPayload).length;
+      } catch {
+      }
+      if (serializedLength === void 0 || serializedLength > MAX_ITEM_PAYLOAD_BYTES) {
+        this.logger.warn(
+          `payload do item descartado (${serializedLength === void 0 ? "n\xE3o serializ\xE1vel" : `${serializedLength} bytes > ${MAX_ITEM_PAYLOAD_BYTES}`}) \u2014 o item foi mantido`
+        );
+        scrubbedPayload = void 0;
+      }
+    }
+    this.itemsBuffer.push({
+      id: id ? truncate(String(id), 255) : uuid4(),
+      seq: this.itemSeq++,
+      status,
+      ...message ? { message: truncate(scrubSecrets(message), MAX_ITEM_MESSAGE_CHARS) } : {},
+      ...scrubbedPayload ? { payload: scrubbedPayload } : {},
+      ts: nowISO()
+    });
+    if (this.itemsBuffer.length >= ITEMS_FLUSH_AT_BUFFERED) {
+      this.flushItems();
+    } else {
+      this.scheduleItemsFlush();
+    }
+  }
+  scheduleItemsFlush() {
+    if (this.itemsTimer) return;
+    this.itemsTimer = setTimeout(() => {
+      this.itemsTimer = void 0;
+      this.flushItems();
+    }, this.flushIntervalMs);
+    unrefTimer(this.itemsTimer);
+  }
+  clearItemsTimer() {
+    if (this.itemsTimer) {
+      clearTimeout(this.itemsTimer);
+      this.itemsTimer = void 0;
+    }
+  }
+  /** Envia o buffer de itens em lotes serializados na cadeia própria. */
+  flushItems() {
+    this.clearItemsTimer();
+    if (this.itemsBuffer.length === 0 || this.itemsUnsupported) return;
+    const items = this.itemsBuffer.splice(0, this.itemsBuffer.length);
+    for (let i = 0; i < items.length; i += MAX_ITEMS_PER_REQUEST) {
+      const batch = items.slice(i, i + MAX_ITEMS_PER_REQUEST);
+      this.itemsChain = this.itemsChain.then(() => this.sendItems(batch));
+    }
+  }
+  async sendItems(batch) {
+    if (this.itemsUnsupported) return;
+    try {
+      await this.api.createItems(this.runId, { items: batch });
+    } catch (error) {
+      if (error instanceof TasksApiError && error.status === 404) {
+        this.itemsUnsupported = true;
+        this.logger.warn("itens de execu\xE7\xE3o n\xE3o s\xE3o suportados por este servidor Hobots \u2014 descartados");
+        return;
+      }
+      if (error instanceof TasksApiError && error.status === 429) {
+        if (!this.itemsQuotaExceeded) {
+          this.itemsQuotaExceeded = true;
+          this.log("warning", "itens descartados: limite de itens por execu\xE7\xE3o atingido no servidor");
+        }
+        return;
+      }
+      if (error instanceof TasksApiError) {
+        this.logger.error(`lote de ${batch.length} item(ns) rejeitado pelo servidor:`, error);
+        return;
+      }
+      this.itemsBuffer.unshift(...batch);
+      this.scheduleItemsFlush();
+      this.logger.error(`lote de ${batch.length} item(ns) n\xE3o enviado (devolvido ao buffer):`, error);
+    }
+  }
+  /**
+   * Dreno final de itens antes do PATCH terminal (com teto): garante que os
+   * totalizadores estejam completos quando a run vira succeeded/failed. Como o
+   * servidor aceita itens tardios, perder a corrida aqui não perde dados.
+   */
+  async finalizeItems(timeoutMs = ITEMS_DRAIN_MS) {
+    this.flushItems();
+    await Promise.race([
+      this.itemsChain,
+      new Promise((resolve) => unrefTimer(setTimeout(resolve, timeoutMs)))
+    ]);
+    if (this.itemsBuffer.length > 0 && !this.itemsUnsupported && !this.itemsQuotaExceeded) {
+      this.flushItems();
+      await Promise.race([
+        this.itemsChain,
+        new Promise((resolve) => unrefTimer(setTimeout(resolve, timeoutMs)))
+      ]);
+    }
+  }
   // ── Anexos ───────────────────────────────────────────────────────────────────
   /**
    * Registra a linha de log com o id do anexo (síncrono, na ordem certa) e dispara
@@ -1699,12 +1891,14 @@ var TaskAgent = class {
           () => this.invokeWithTimeout(handler, run, reporter)
         );
         await reporter.finalizeAttachments();
+        await reporter.finalizeItems();
         tx.setStatus("ok");
         tx.finish();
         reporter.reportSuccess();
         this.logger.debug(`run ${run.id} conclu\xEDda`);
       } catch (error) {
         await reporter.finalizeAttachments();
+        await reporter.finalizeItems();
         tx.setStatus("error");
         tx.finish();
         reporter.reportFailure(toRunError(error));