hobots 3.0.0 → 3.2.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { RunLogLevel, RunAttachmentContentType, EventType, EnvironmentInput, MachineSnapshot, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, StepData, RunItemStatus, RunProgress } from './protocol.cjs';
-export { Breadcrumb, BreadcrumbLevel, Envelope, EnvelopeItem, Environment, EventUser, ExceptionData, InstanceInfo, MachineProcess, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunCreateRequest, RunCreateResponse, RunDescriptor, RunError, RunItemInput, RunItemsCreateRequest, RunItemsCreateResponse, RunLogEntry, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame } from './protocol.cjs';
+export { Breadcrumb, BreadcrumbLevel, Envelope, EnvelopeItem, Environment, EventUser, ExceptionData, InstanceInfo, ItemColumn, MachineProcess, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunCreateRequest, RunCreateResponse, RunDescriptor, RunError, RunItemInput, RunItemsCreateRequest, RunItemsCreateResponse, RunLogEntry, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame, TaskItemsDeclaration } from './protocol.cjs';
 
 /** Espera entre tentativas: ms fixo ou função do número da tentativa que acabou de falhar (1-based). */
 type RetryDelay = number | ((attempt: number) => number);
@@ -37,6 +37,18 @@ interface AttachResult {
 /** Aceita tudo que o handler pode ter em mãos: bytes ou um caminho de arquivo (só Node). */
 type AttachInput = Uint8Array | ArrayBuffer | string;
 
+interface Logger {
+    debug: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+}
+
+/** Coluna de itens como o dev declara: só a chave, ou chave + rótulo. */
+type ItemColumnInput = string | {
+    key: string;
+    label?: string;
+};
+
 /**
  * Opções do processo (telemetria, identidade, handlers globais). Valem as da PRIMEIRA
  * chamada a register()/start(); chamadas seguintes com valores diferentes avisam e são ignoradas.
@@ -52,7 +64,8 @@ interface HobotsOptions {
     /**
      * Ambiente lógico onde este robô roda: 'development', 'testing', 'staging' ou
      * 'production'. Vai em todo evento, transaction e na identidade da instância — é por
-     * ele que as regras de alerta decidem se notificam. Default: 'production'.
+     * ele que as regras de alerta decidem se notificam. Default: env HOBOTS_ENVIRONMENT;
+     * sem ela, 'production'.
      */
     environment?: EnvironmentInput;
     /** Versão do programa, ex.: 'robo-nfe@1.4.2' */
@@ -75,8 +88,20 @@ interface HobotsOptions {
      */
     installExitHandlers?: boolean;
 }
+/** Colunas de itens declaradas no código (até 12; chave: letras, números, `.`, `-`, `_`). */
+interface TaskItemsOptions {
+    columns: ItemColumnInput[];
+}
 /** Opções de uma task (register ou start). */
 interface TaskOptions extends HobotsOptions {
+    /**
+     * Colunas da aba "itens" da execução na plataforma: chaves do `payload` que cada
+     * item reportado (`ctx.items.*`) carrega, com rótulo opcional. Independe de
+     * formulário — vale para register e start. Personalizar na plataforma
+     * (Configurações → agente) sobrepõe o que for declarado aqui.
+     * Ex.: `{ columns: ['numero_nota', { key: 'valor', label: 'valor (R$)' }] }`
+     */
+    items?: TaskItemsOptions;
     /**
      * Tentativas extras do handler quando ele lança, na mesma run (itens e progresso já
      * enviados permanecem — escreva handlers idempotentes). Cancelamento e timeout nunca
@@ -150,12 +175,6 @@ interface ResolvedConfig {
     tasksBaseUrl: string;
 }
 
-interface Logger {
-    debug: (...args: unknown[]) => void;
-    warn: (...args: unknown[]) => void;
-    error: (...args: unknown[]) => void;
-}
-
 /**
  * Coleta CPU/memória/disco da máquina e do processo — só em Node (no browser é no-op).
  *
@@ -290,12 +309,16 @@ declare class Transaction {
     finish(): void;
 }
 
+/**
+ * `hobots.log`: cada método aceita vários argumentos, como `console.log` — cada um vira
+ * texto (`safeString`) e são unidos por espaço. Nunca lança, nem com a run cancelada.
+ */
 interface RunLogger {
-    debug(message: string): void;
-    info(message: string): void;
-    warn(message: string): void;
-    error(message: string): void;
-    success(message: string): void;
+    debug(message: unknown, ...rest: unknown[]): void;
+    info(message: unknown, ...rest: unknown[]): void;
+    warn(message: unknown, ...rest: unknown[]): void;
+    error(message: unknown, ...rest: unknown[]): void;
+    success(message: unknown, ...rest: unknown[]): void;
 }
 interface RunItemOptions {
     /**
@@ -411,4 +434,4 @@ declare const close: (timeoutMs?: number) => Promise<boolean>;
 declare const captureException: (error: unknown, hint?: CaptureHint) => string | undefined;
 declare const retry: <T>(fn: (attempt: number) => T | Promise<T>, options?: RetryOptions) => Promise<T>;
 
-export { type AttachFailureReason, type AttachInput, type AttachOptions, type AttachResult, type CaptureAttachment, type CaptureHint, EnvironmentInput, EventPayload, EventType, HeartbeatPayload, type Hobots, type HobotsOptions, MachineSnapshot, type RegisterOptions, type RetryDelay, type RetryOptions, RunAttachmentContentType, type RunContext, type RunItemOptions, RunItemStatus, type RunItems, RunLogLevel, type RunLogger, RunProgress, type RunProgressReporter, type StartOptions, Step, StepData, StepStatus, type TaskHandler, type TaskOptions, Transaction, TransactionPayload, captureException, close, hobots as default, hobots, register, retry, start };
+export { type AttachFailureReason, type AttachInput, type AttachOptions, type AttachResult, type CaptureAttachment, type CaptureHint, EnvironmentInput, EventPayload, EventType, HeartbeatPayload, type Hobots, type HobotsOptions, type ItemColumnInput, MachineSnapshot, type RegisterOptions, type RetryDelay, type RetryOptions, RunAttachmentContentType, type RunContext, type RunItemOptions, RunItemStatus, type RunItems, RunLogLevel, type RunLogger, RunProgress, type RunProgressReporter, type StartOptions, Step, StepData, StepStatus, type TaskHandler, type TaskItemsOptions, type TaskOptions, Transaction, TransactionPayload, captureException, close, hobots as default, hobots, register, retry, start };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { RunLogLevel, RunAttachmentContentType, EventType, EnvironmentInput, MachineSnapshot, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, StepData, RunItemStatus, RunProgress } from './protocol.js';
-export { Breadcrumb, BreadcrumbLevel, Envelope, EnvelopeItem, Environment, EventUser, ExceptionData, InstanceInfo, MachineProcess, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunCreateRequest, RunCreateResponse, RunDescriptor, RunError, RunItemInput, RunItemsCreateRequest, RunItemsCreateResponse, RunLogEntry, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame } from './protocol.js';
+export { Breadcrumb, BreadcrumbLevel, Envelope, EnvelopeItem, Environment, EventUser, ExceptionData, InstanceInfo, ItemColumn, MachineProcess, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunCreateRequest, RunCreateResponse, RunDescriptor, RunError, RunItemInput, RunItemsCreateRequest, RunItemsCreateResponse, RunLogEntry, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame, TaskItemsDeclaration } from './protocol.js';
 
 /** Espera entre tentativas: ms fixo ou função do número da tentativa que acabou de falhar (1-based). */
 type RetryDelay = number | ((attempt: number) => number);
@@ -37,6 +37,18 @@ interface AttachResult {
 /** Aceita tudo que o handler pode ter em mãos: bytes ou um caminho de arquivo (só Node). */
 type AttachInput = Uint8Array | ArrayBuffer | string;
 
+interface Logger {
+    debug: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+}
+
+/** Coluna de itens como o dev declara: só a chave, ou chave + rótulo. */
+type ItemColumnInput = string | {
+    key: string;
+    label?: string;
+};
+
 /**
  * Opções do processo (telemetria, identidade, handlers globais). Valem as da PRIMEIRA
  * chamada a register()/start(); chamadas seguintes com valores diferentes avisam e são ignoradas.
@@ -52,7 +64,8 @@ interface HobotsOptions {
     /**
      * Ambiente lógico onde este robô roda: 'development', 'testing', 'staging' ou
      * 'production'. Vai em todo evento, transaction e na identidade da instância — é por
-     * ele que as regras de alerta decidem se notificam. Default: 'production'.
+     * ele que as regras de alerta decidem se notificam. Default: env HOBOTS_ENVIRONMENT;
+     * sem ela, 'production'.
      */
     environment?: EnvironmentInput;
     /** Versão do programa, ex.: 'robo-nfe@1.4.2' */
@@ -75,8 +88,20 @@ interface HobotsOptions {
      */
     installExitHandlers?: boolean;
 }
+/** Colunas de itens declaradas no código (até 12; chave: letras, números, `.`, `-`, `_`). */
+interface TaskItemsOptions {
+    columns: ItemColumnInput[];
+}
 /** Opções de uma task (register ou start). */
 interface TaskOptions extends HobotsOptions {
+    /**
+     * Colunas da aba "itens" da execução na plataforma: chaves do `payload` que cada
+     * item reportado (`ctx.items.*`) carrega, com rótulo opcional. Independe de
+     * formulário — vale para register e start. Personalizar na plataforma
+     * (Configurações → agente) sobrepõe o que for declarado aqui.
+     * Ex.: `{ columns: ['numero_nota', { key: 'valor', label: 'valor (R$)' }] }`
+     */
+    items?: TaskItemsOptions;
     /**
      * Tentativas extras do handler quando ele lança, na mesma run (itens e progresso já
      * enviados permanecem — escreva handlers idempotentes). Cancelamento e timeout nunca
@@ -150,12 +175,6 @@ interface ResolvedConfig {
     tasksBaseUrl: string;
 }
 
-interface Logger {
-    debug: (...args: unknown[]) => void;
-    warn: (...args: unknown[]) => void;
-    error: (...args: unknown[]) => void;
-}
-
 /**
  * Coleta CPU/memória/disco da máquina e do processo — só em Node (no browser é no-op).
  *
@@ -290,12 +309,16 @@ declare class Transaction {
     finish(): void;
 }
 
+/**
+ * `hobots.log`: cada método aceita vários argumentos, como `console.log` — cada um vira
+ * texto (`safeString`) e são unidos por espaço. Nunca lança, nem com a run cancelada.
+ */
 interface RunLogger {
-    debug(message: string): void;
-    info(message: string): void;
-    warn(message: string): void;
-    error(message: string): void;
-    success(message: string): void;
+    debug(message: unknown, ...rest: unknown[]): void;
+    info(message: unknown, ...rest: unknown[]): void;
+    warn(message: unknown, ...rest: unknown[]): void;
+    error(message: unknown, ...rest: unknown[]): void;
+    success(message: unknown, ...rest: unknown[]): void;
 }
 interface RunItemOptions {
     /**
@@ -411,4 +434,4 @@ declare const close: (timeoutMs?: number) => Promise<boolean>;
 declare const captureException: (error: unknown, hint?: CaptureHint) => string | undefined;
 declare const retry: <T>(fn: (attempt: number) => T | Promise<T>, options?: RetryOptions) => Promise<T>;
 
-export { type AttachFailureReason, type AttachInput, type AttachOptions, type AttachResult, type CaptureAttachment, type CaptureHint, EnvironmentInput, EventPayload, EventType, HeartbeatPayload, type Hobots, type HobotsOptions, MachineSnapshot, type RegisterOptions, type RetryDelay, type RetryOptions, RunAttachmentContentType, type RunContext, type RunItemOptions, RunItemStatus, type RunItems, RunLogLevel, type RunLogger, RunProgress, type RunProgressReporter, type StartOptions, Step, StepData, StepStatus, type TaskHandler, type TaskOptions, Transaction, TransactionPayload, captureException, close, hobots as default, hobots, register, retry, start };
+export { type AttachFailureReason, type AttachInput, type AttachOptions, type AttachResult, type CaptureAttachment, type CaptureHint, EnvironmentInput, EventPayload, EventType, HeartbeatPayload, type Hobots, type HobotsOptions, type ItemColumnInput, MachineSnapshot, type RegisterOptions, type RetryDelay, type RetryOptions, RunAttachmentContentType, type RunContext, type RunItemOptions, RunItemStatus, type RunItems, RunLogLevel, type RunLogger, RunProgress, type RunProgressReporter, type StartOptions, Step, StepData, StepStatus, type TaskHandler, type TaskItemsOptions, type TaskOptions, Transaction, TransactionPayload, captureException, close, hobots as default, hobots, register, retry, start };