hobots 3.3.0 → 4.0.0

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, 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';
+import { RunAttachmentContentType, EventType, EnvironmentInput, MachineSnapshot, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, RunLogLevel, StepData, RunItemStatus, RunProgress } from './protocol.js';
+export { Breadcrumb, BreadcrumbLevel, Envelope, EnvelopeItem, Environment, EventUser, ExceptionData, InstanceInfo, InstanceMode, ItemColumn, ItemsDeclaration, MachineProcess, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunCreateRequest, RunCreateResponse, RunDescriptor, RunError, RunItemInput, RunItemsCreateRequest, RunItemsCreateResponse, RunLogEntry, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame } 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);
@@ -12,30 +12,29 @@ interface RetryOptions {
     shouldRetry?: (error: unknown) => boolean;
 }
 
-interface AttachOptions {
-    /** Legenda curta, exibida sob a miniatura no app. Passa pelo scrub de segredos. */
+/** Aceita tudo que o handler pode ter em mãos: bytes ou um caminho de arquivo (só Node). */
+type AttachInput = Uint8Array | ArrayBuffer | string;
+interface ImageOptions {
+    /** Legenda curta, exibida junto da imagem no app. Passa pelo scrub de segredos. */
     caption?: string;
-    /** Nível da linha de log que carrega o anexo. Default: 'info' */
-    level?: RunLogLevel;
-    /** Texto da linha de log. Default: a legenda, ou 'captura de tela' */
-    message?: string;
     /** Informe quando os magic bytes não bastarem (o SDK sempre prefere o que detectar). */
     contentType?: RunAttachmentContentType;
 }
-type AttachFailureReason = 
-/** A instalação do Hobots não tem anexos habilitados (ou a API é anterior ao recurso) */
-'unsupported' | 'too-large' | 'quota' | 'read-failed'
-/** Formato não reconhecido ou fora de PNG/JPEG/WEBP */
- | 'unsupported-format' | 'upload-failed' | 'canceled';
-interface AttachResult {
-    /** Id do anexo, o mesmo referenciado na linha de log */
-    id: string;
-    ok: boolean;
-    /** Motivo do insucesso — para diagnóstico; `attach` nunca lança */
-    reason?: AttachFailureReason;
+declare const IMAGE_BRAND: unique symbol;
+/**
+ * Uma imagem pronta para ser pendurada num evento da run — o retorno de `hobots.image()`.
+ * É só um envelope (bytes/caminho + legenda); nenhum I/O acontece até o evento ser
+ * registrado por `hobots.log.*`, `hobots.items.*` ou `step.setStatus/setError`.
+ */
+declare class ImageAttachment {
+    readonly input: AttachInput;
+    readonly caption?: string | undefined;
+    readonly contentType?: RunAttachmentContentType | undefined;
+    readonly [IMAGE_BRAND] = true;
+    constructor(input: AttachInput, caption?: string | undefined, contentType?: RunAttachmentContentType | undefined);
 }
-/** Aceita tudo que o handler pode ter em mãos: bytes ou um caminho de arquivo (só Node). */
-type AttachInput = Uint8Array | ArrayBuffer | string;
+/** O que os métodos com imagem aceitam: bytes/caminho crus ou o envelope de `hobots.image()`. */
+type ImageInput = AttachInput | ImageAttachment;
 
 interface Logger {
     debug: (...args: unknown[]) => void;
@@ -58,7 +57,7 @@ interface HobotsOptions {
     clientSecret?: string;
     /**
      * Identificador único e estável desta instância — a identidade do agente no painel
-     * (heartbeat e tasks convergem nele). Default: env HOBOTS_INSTANCE_ID; sem ela, o hostname.
+     * (heartbeat e execuções convergem nele). Default: env HOBOTS_INSTANCE_ID; sem ela, o hostname.
      */
     instanceId?: string;
     /**
@@ -89,11 +88,11 @@ interface HobotsOptions {
     installExitHandlers?: boolean;
 }
 /** Colunas de itens declaradas no código (até 12; chave: letras, números, `.`, `-`, `_`). */
-interface TaskItemsOptions {
+interface ItemsOptions {
     columns: ItemColumnInput[];
 }
-/** Opções de uma task (register ou start). */
-interface TaskOptions extends HobotsOptions {
+/** Opções da execução do agente (register ou start). */
+interface RunOptions 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
@@ -101,7 +100,7 @@ interface TaskOptions extends HobotsOptions {
      * (Configurações → agente) sobrepõe o que for declarado aqui.
      * Ex.: `{ columns: ['numero_nota', { key: 'valor', label: 'valor (R$)' }] }`
      */
-    items?: TaskItemsOptions;
+    items?: ItemsOptions;
     /**
      * Tentativas extras do handler quando ele lança, na mesma run (itens e progresso já
      * enviados permanecem — escreva handlers idempotentes). Cancelamento e timeout nunca
@@ -129,15 +128,15 @@ interface TaskOptions extends HobotsOptions {
      */
     cancelGraceMs?: number;
 }
-/** Opções de `register()` — task executada sob demanda, a partir das solicitações do app. */
-interface RegisterOptions extends TaskOptions {
-    /** Runs simultâneas desta task (1..5). Default: 1 (sequencial) */
+/** Opções de `register()` — agente sob demanda, executado a partir das solicitações do app. */
+interface RegisterOptions extends RunOptions {
+    /** Runs simultâneas do agente (1..5). Default: 1 (sequencial) */
     concurrency?: number;
-    /** Intervalo entre polls sem trabalho (mínimo 1_000). Vale o do primeiro register(). Default: 2_000 */
+    /** Intervalo entre polls sem trabalho (mínimo 1_000). Default: 2_000 */
     pollIntervalMs?: number;
 }
-/** Opções de `start()` — task que roda sempre, aberta pelo próprio bot. */
-type StartOptions = TaskOptions;
+/** Opções de `start()` — agente sempre ligado, que abre a própria run. */
+type StartOptions = RunOptions;
 /** Imagem enviada junto de um captureException — com legenda e content-type opcionais. */
 interface CaptureAttachment {
     /** Bytes (`Uint8Array`/`ArrayBuffer`/`Buffer`) ou um caminho de arquivo (só em Node) */
@@ -162,7 +161,7 @@ interface CaptureHint {
      * hobots.captureException(error, { attachment: { image: await page.screenshot(), caption: 'tela no momento do erro' } });
      * ```
      */
-    attachment?: AttachInput | CaptureAttachment;
+    attachment?: ImageInput | CaptureAttachment;
 }
 
 interface ResolvedConfig {
@@ -171,8 +170,8 @@ interface ResolvedConfig {
     baseUrl: string;
     /** Ingestão de telemetria: <baseUrl>/v1/ingest */
     ingestEndpoint: string;
-    /** API de tasks (execução sob demanda): <baseUrl>/v1/tasks */
-    tasksBaseUrl: string;
+    /** API de execuções (poll, runs, itens, anexos): <baseUrl>/v1/runs */
+    runsBaseUrl: string;
 }
 
 /**
@@ -245,6 +244,16 @@ declare class Client {
 
 /** Recebe os eventos de lifecycle da transaction para espelhá-los nos logs da run. */
 type LifecycleSink = (level: RunLogLevel, message: string) => void;
+/**
+ * Recebe a imagem de uma step e dispara o upload pela run; devolve o id do anexo
+ * (já referenciável em `data.attachments`) ou undefined quando descartada.
+ */
+type AttachmentSink = (image: ImageInput, ts: string) => string | undefined;
+/** Opções dos desfechos de step que aceitam um print do estado da tela. */
+interface StepOutcomeOptions {
+    /** Print da step (bytes/caminho ou `hobots.image(bytes, { caption })`) — botão de imagem no app. */
+    image?: ImageInput;
+}
 declare class Step {
     private readonly transaction;
     readonly parentStepId: string;
@@ -259,13 +268,21 @@ declare class Step {
     /**
      * Desfecho da step. `message` (opcional) é o motivo legível — vai em `data.message`
      * e aparece na Central (performance e banner da execução) e no log de FINISH.
+     * `options.image` pendura um print do estado da tela em `data.attachments`.
      */
-    setStatus(status: StepStatus, message?: string): this;
+    setStatus(status: StepStatus, message?: string, options?: StepOutcomeOptions): this;
     /**
      * Marca a step como `error` guardando o motivo em `data.error` ({ type, message }).
      * Aceita qualquer valor lançado; `message` sobrescreve a mensagem do erro.
+     * `options.image` pendura um print do estado da tela em `data.attachments`.
+     */
+    setError(error: unknown, message?: string, options?: StepOutcomeOptions): this;
+    /**
+     * Dispara o upload pela run (sink do RunReporter) e referencia o anexo em
+     * `data.attachments` (chave reservada; teto igual ao das linhas de log). Fora de uma
+     * run não há onde pendurar a imagem — descarta com aviso único.
      */
-    setError(error: unknown, message?: string): this;
+    private attachImage;
     /** Motivo registrado via setStatus(…, message) ou setError — usado no log de FINISH. */
     private reason;
     setData(key: string, value: unknown): this;
@@ -282,7 +299,7 @@ declare class Transaction {
     private readonly client;
     name: string;
     readonly op?: string | undefined;
-    /** Correlaciona a uma execução de task — preenchido automaticamente em hobots.transaction */
+    /** Correlaciona a uma execução do agente — preenchido automaticamente em hobots.transaction */
     private readonly runId?;
     readonly eventId: string;
     readonly stepId: string;
@@ -292,10 +309,12 @@ declare class Transaction {
     private readonly tags;
     private finished;
     private lifecycleSink?;
+    private attachmentSink?;
+    private warnedNoAttachmentSink;
     private stepGuard?;
     private lifecycleBacklog;
     constructor(client: Client | undefined, name: string, op?: string | undefined, 
-    /** Correlaciona a uma execução de task — preenchido automaticamente em hobots.transaction */
+    /** Correlaciona a uma execução do agente — preenchido automaticamente em hobots.transaction */
     runId?: string | undefined);
     /**
      * Registra o início/fim de uma step ou transaction: espelha a linha no sink de
@@ -306,6 +325,10 @@ declare class Transaction {
     emit(kind: 'transaction' | 'step', phase: 'start' | 'finish', label: string, startTs?: string, endTs?: string, status?: StepStatus | string, reason?: string): void;
     /** Conecta o espelho de lifecycle (RunReporter) e faz replay do backlog em ordem. */
     setLifecycleSink(sink: LifecycleSink): void;
+    /** Conecta o pipeline de anexos da run — é o que dá imagem às steps. */
+    setAttachmentSink(sink: AttachmentSink): void;
+    /** Imagem de uma step → id do anexo pela run; sem run, descarta com aviso único. */
+    attachImage(image: ImageInput): string | undefined;
     /**
      * Conecta a checagem de cancelamento chamada antes de cada step nova — é assim que
      * `hobots.transaction.startChild()` (e `step.startChild()`) param uma run cancelada.
@@ -323,6 +346,10 @@ declare class Transaction {
 /**
  * `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.
+ *
+ * Um `hobots.image(...)` como **último** argumento não entra no texto: vira o print da
+ * linha (botão de imagem no app). O upload roda em segundo plano e nunca bloqueia:
+ * `hobots.log.error('login falhou', hobots.image(await page.screenshot()))`.
  */
 interface RunLogger {
     debug(message: unknown, ...rest: unknown[]): void;
@@ -331,10 +358,18 @@ interface RunLogger {
     error(message: unknown, ...rest: unknown[]): void;
     success(message: unknown, ...rest: unknown[]): void;
 }
-interface RunItemOptions {
+interface RunItemImageOptions {
+    /**
+     * Print do item (bytes/caminho ou `hobots.image(bytes, { caption })`) — o estado da tela
+     * no momento do desfecho, com botão de imagem na tabela de itens do app. O upload roda
+     * em segundo plano e nunca bloqueia. PNG/JPEG/WEBP, até 5 MB, 20 por execução.
+     */
+    image?: ImageInput;
+}
+interface RunItemOptions extends RunItemImageOptions {
     /**
      * Identidade de negócio do item na run (ex.: nº da nota fiscal). Repetido na
-     * mesma run = ignorado pelo servidor (registro único, retry idempotente).
+     * mesma run = o servidor atualiza o item (vale o último reporte, retry idempotente).
      * Omitido: o SDK gera um id único e cada chamada vira um item novo.
      */
     id?: string;
@@ -355,11 +390,11 @@ interface RunItemHandle {
     /** true depois do primeiro desfecho registrado (o SDK não sobrescreve o que o handler decidiu). */
     readonly reported: boolean;
     /** Item processado com sucesso. `payload` é mesclado sobre o payload base de `options.payload`. */
-    succeeded(payload?: Record<string, unknown>): void;
-    /** Falha sem lançar — o loop segue igual; a step vira `error` com o motivo. */
-    failed(message: string, payload?: Record<string, unknown>): void;
-    /** Ocorrência de negócio — a step vira `warning` com o motivo. */
-    occurrence(message: string, payload?: Record<string, unknown>): void;
+    succeeded(payload?: Record<string, unknown>, options?: RunItemImageOptions): void;
+    /** Falha sem lançar — o loop segue igual; a step vira `error` com o motivo. A imagem vai no item. */
+    failed(message: string, payload?: Record<string, unknown>, options?: RunItemImageOptions): void;
+    /** Ocorrência de negócio — a step vira `warning` com o motivo. A imagem vai no item. */
+    occurrence(message: string, payload?: Record<string, unknown>, options?: RunItemImageOptions): void;
 }
 interface RunItemsEachOptions<T> {
     /** Identidade de negócio do item (ex.: nº do cliente). Omitido/null: o SDK gera um id único. */
@@ -397,6 +432,7 @@ interface RunItems {
         id?: string;
         message?: string;
         payload?: Record<string, unknown>;
+        image?: ImageInput;
     }): void;
     /** Item processado com sucesso. `payload` = atributos do item (viram colunas na plataforma). */
     succeeded(payload?: Record<string, unknown>, options?: RunItemOptions): void;
@@ -439,7 +475,6 @@ interface RunProgressReporter {
  */
 interface RunContext {
     readonly runId: string;
-    readonly task: string;
     /** Params da solicitação (formulário do app); `{}` no modo start */
     readonly params: Record<string, unknown>;
     /** Log bufferizado — enviado ao servidor em PATCHes incrementais com throttle. Nunca lança. */
@@ -463,16 +498,11 @@ interface RunContext {
     throwIfCanceled(): void;
     /** Sleep cancelável: rejeita com `RunCanceled` se o signal disparar antes de ms. */
     sleep(ms: number): Promise<void>;
-    /**
-     * Anexa uma imagem (print) a uma linha de log da run — miniatura no app. Nunca lança nem
-     * bloqueia: o upload roda em segundo plano. PNG/JPEG/WEBP, até 5 MB, 20 por execução.
-     */
-    attach(image: AttachInput, options?: AttachOptions): Promise<AttachResult>;
     /** async-retry ciente do cancelamento desta run (ver `RetryOptions`). */
     retry<T>(fn: (attempt: number) => T | Promise<T>, options?: RetryOptions): Promise<T>;
 }
 /** O retorno do handler é ignorado — nada além de status/logs/erro é enviado ao servidor. */
-type TaskHandler<P = Record<string, unknown>> = (params: P, ctx: RunContext) => void | Promise<void>;
+type RunHandler<P = Record<string, unknown>> = (params: P, ctx: RunContext) => void | Promise<void>;
 
 /**
  * O objeto global do SDK: as funções do processo (register/start/close/captureException/
@@ -480,23 +510,33 @@ type TaskHandler<P = Record<string, unknown>> = (params: P, ctx: RunContext) =>
  * resolvido a cada acesso — funciona de qualquer módulo, sem passar `ctx` de mão em mão.
  */
 interface Hobots extends RunContext {
-    /** Task sob demanda: executada a cada solicitação do app (formulário/agendamento) via polling. */
-    register<P = Record<string, unknown>>(task: string, handler: TaskHandler<P>, options?: RegisterOptions): void;
-    /** Task sempre-ligada: o bot abre a própria run e roda o handler; a plataforma recebe logs, itens e progresso. */
-    start(task: string, handler: TaskHandler, options?: StartOptions): void;
+    /**
+     * Agente sob demanda: o handler roda a cada solicitação do app (formulário/agendamento), via polling.
+     * O agente é a própria tarefa: uma chamada por processo (register OU start).
+     */
+    register<P = Record<string, unknown>>(handler: RunHandler<P>, options?: RegisterOptions): void;
+    /** Agente sempre ligado: abre a própria run e roda o handler; a plataforma recebe logs, itens e progresso. */
+    start(handler: RunHandler, options?: StartOptions): void;
     /** Encerra tudo (polling, runs em voo, heartbeat, flush final). Chame antes do processo terminar. */
     close(timeoutMs?: number): Promise<boolean>;
     /** Captura uma exceção como issue (módulo Issues). Retorna o event_id. */
     captureException(error: unknown, hint?: CaptureHint): string | undefined;
+    /**
+     * Embrulha um print para ir junto de um log, item ou step — `hobots.log.error('x', hobots.image(png))`,
+     * `hobots.items.failed('x', payload, { image: hobots.image(png, { caption }) })`,
+     * `step.setError(err, undefined, { image: png })`. Puro: nenhum I/O até o evento ser registrado.
+     */
+    image(input: AttachInput, options?: ImageOptions): ImageAttachment;
 }
 declare global {
     var hobots: Hobots;
 }
 declare const hobots: Hobots;
-declare const register: <P = Record<string, unknown>>(task: string, handler: TaskHandler<P>, options?: RegisterOptions) => void;
-declare const start: (task: string, handler: TaskHandler, options?: StartOptions) => void;
+declare const register: <P = Record<string, unknown>>(handler: RunHandler<P>, options?: RegisterOptions) => void;
+declare const start: (handler: RunHandler, options?: StartOptions) => void;
 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>;
+declare const image: (input: AttachInput, options?: ImageOptions) => ImageAttachment;
 
-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 RunItemHandle, type RunItemOptions, RunItemStatus, type RunItems, type RunItemsEachHandler, type RunItemsEachOptions, type RunItemsEachResult, 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 };
+export { type AttachInput, type CaptureAttachment, type CaptureHint, EnvironmentInput, EventPayload, EventType, HeartbeatPayload, type Hobots, type HobotsOptions, ImageAttachment, type ImageInput, type ImageOptions, type ItemColumnInput, type ItemsOptions, MachineSnapshot, type RegisterOptions, type RetryDelay, type RetryOptions, RunAttachmentContentType, type RunContext, type RunHandler, type RunItemHandle, type RunItemImageOptions, type RunItemOptions, RunItemStatus, type RunItems, type RunItemsEachHandler, type RunItemsEachOptions, type RunItemsEachResult, RunLogLevel, type RunLogger, type RunOptions, RunProgress, type RunProgressReporter, type StartOptions, Step, StepData, type StepOutcomeOptions, StepStatus, Transaction, TransactionPayload, captureException, close, hobots as default, hobots, image, register, retry, start };