hobots 3.2.2 → 3.4.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { RunLogLevel, RunAttachmentContentType, EventType, EnvironmentInput, MachineSnapshot, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, StepData, RunItemStatus, RunProgress } from './protocol.cjs';
+import { RunAttachmentContentType, EventType, EnvironmentInput, MachineSnapshot, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, RunLogLevel, StepData, RunItemStatus, RunProgress } 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). */
@@ -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;
@@ -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 {
@@ -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;
@@ -292,6 +309,8 @@ 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, 
@@ -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,14 +358,67 @@ 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;
 }
+/**
+ * O item em processamento dentro de `items.each`: o desfecho (`succeeded`/`failed`/
+ * `occurrence`) com o `id` e o payload base já resolvidos, e a step da etapa para quem
+ * quiser medir sub-etapas (`item.step.startChild(...)`). Sem chamada explícita, o SDK
+ * decide: retornou → `succeeded`; lançou → `failed` com a mensagem do erro.
+ */
+interface RunItemHandle {
+    /** Posição do elemento na lista (0-based). */
+    readonly index: number;
+    /** Identidade de negócio resolvida por `options.id` (undefined = o SDK gera uma). */
+    readonly id: string | undefined;
+    /** Step desta etapa no waterfall de performance; undefined fora de uma execução. */
+    readonly step: Step | undefined;
+    /** 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>, 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. */
+    id?: (element: T, index: number) => string | number | null | undefined;
+    /** Atributos base do item (viram colunas no app) — presentes em qualquer desfecho, inclusive falha. */
+    payload?: (element: T, index: number) => Record<string, unknown> | undefined;
+    /** `op` da step de cada item no waterfall. Default: 'item'. */
+    op?: string;
+    /** Descrição da step de cada item. Default: o `id`, senão `#<posição>`. */
+    description?: (element: T, index: number) => string;
+    /**
+     * Progresso automático: declara o total (tamanho da lista, se o bot ainda não declarou um)
+     * e avança a cada elemento. `false` deixa o progresso por conta do bot. Default: true.
+     */
+    progress?: boolean;
+}
+/** Totalizadores do `items.each`, pelo desfecho final de cada elemento. */
+interface RunItemsEachResult {
+    total: number;
+    succeeded: number;
+    failed: number;
+    occurrence: number;
+}
+type RunItemsEachHandler<T> = (element: T, item: RunItemHandle, index: number) => unknown;
 /**
  * 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
@@ -352,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;
@@ -359,6 +440,15 @@ interface RunItems {
     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;
+    /**
+     * Processa uma lista item a item com o contrato da plataforma garantido pelo SDK: cada
+     * elemento vira uma step e um item; uma exceção no handler registra o item como `failed`
+     * (com a mensagem do erro), marca a step com `setError` e **segue para o próximo** — a
+     * lista inteira é processada, e o progresso avança a cada elemento. Só cancelamento,
+     * timeout e shutdown interrompem o loop (o erro sobe como em qualquer ponto de parada).
+     * Resolve com os totalizadores por desfecho.
+     */
+    each<T>(list: Iterable<T> | AsyncIterable<T>, handler: RunItemsEachHandler<T>, options?: RunItemsEachOptions<T>): Promise<RunItemsEachResult>;
 }
 /**
  * Progresso da execução (itens processados / total) — opcional e independente de
@@ -409,11 +499,6 @@ 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>;
 }
@@ -434,6 +519,12 @@ interface Hobots extends RunContext {
     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;
@@ -444,5 +535,6 @@ declare const start: (task: string, handler: TaskHandler, options?: StartOptions
 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 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 };
+export { type AttachInput, type CaptureAttachment, type CaptureHint, EnvironmentInput, EventPayload, EventType, HeartbeatPayload, type Hobots, type HobotsOptions, ImageAttachment, type ImageInput, type ImageOptions, type ItemColumnInput, MachineSnapshot, type RegisterOptions, type RetryDelay, type RetryOptions, RunAttachmentContentType, type RunContext, type RunItemHandle, type RunItemImageOptions, type RunItemOptions, RunItemStatus, type RunItems, type RunItemsEachHandler, type RunItemsEachOptions, type RunItemsEachResult, RunLogLevel, type RunLogger, RunProgress, type RunProgressReporter, type StartOptions, Step, StepData, type StepOutcomeOptions, StepStatus, type TaskHandler, type TaskItemsOptions, type TaskOptions, Transaction, TransactionPayload, captureException, close, hobots as default, hobots, image, register, retry, start };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { RunLogLevel, RunAttachmentContentType, EventType, EnvironmentInput, MachineSnapshot, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, StepData, RunItemStatus, RunProgress } 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, 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). */
@@ -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;
@@ -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 {
@@ -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;
@@ -292,6 +309,8 @@ 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, 
@@ -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,14 +358,67 @@ 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;
 }
+/**
+ * O item em processamento dentro de `items.each`: o desfecho (`succeeded`/`failed`/
+ * `occurrence`) com o `id` e o payload base já resolvidos, e a step da etapa para quem
+ * quiser medir sub-etapas (`item.step.startChild(...)`). Sem chamada explícita, o SDK
+ * decide: retornou → `succeeded`; lançou → `failed` com a mensagem do erro.
+ */
+interface RunItemHandle {
+    /** Posição do elemento na lista (0-based). */
+    readonly index: number;
+    /** Identidade de negócio resolvida por `options.id` (undefined = o SDK gera uma). */
+    readonly id: string | undefined;
+    /** Step desta etapa no waterfall de performance; undefined fora de uma execução. */
+    readonly step: Step | undefined;
+    /** 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>, 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. */
+    id?: (element: T, index: number) => string | number | null | undefined;
+    /** Atributos base do item (viram colunas no app) — presentes em qualquer desfecho, inclusive falha. */
+    payload?: (element: T, index: number) => Record<string, unknown> | undefined;
+    /** `op` da step de cada item no waterfall. Default: 'item'. */
+    op?: string;
+    /** Descrição da step de cada item. Default: o `id`, senão `#<posição>`. */
+    description?: (element: T, index: number) => string;
+    /**
+     * Progresso automático: declara o total (tamanho da lista, se o bot ainda não declarou um)
+     * e avança a cada elemento. `false` deixa o progresso por conta do bot. Default: true.
+     */
+    progress?: boolean;
+}
+/** Totalizadores do `items.each`, pelo desfecho final de cada elemento. */
+interface RunItemsEachResult {
+    total: number;
+    succeeded: number;
+    failed: number;
+    occurrence: number;
+}
+type RunItemsEachHandler<T> = (element: T, item: RunItemHandle, index: number) => unknown;
 /**
  * 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
@@ -352,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;
@@ -359,6 +440,15 @@ interface RunItems {
     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;
+    /**
+     * Processa uma lista item a item com o contrato da plataforma garantido pelo SDK: cada
+     * elemento vira uma step e um item; uma exceção no handler registra o item como `failed`
+     * (com a mensagem do erro), marca a step com `setError` e **segue para o próximo** — a
+     * lista inteira é processada, e o progresso avança a cada elemento. Só cancelamento,
+     * timeout e shutdown interrompem o loop (o erro sobe como em qualquer ponto de parada).
+     * Resolve com os totalizadores por desfecho.
+     */
+    each<T>(list: Iterable<T> | AsyncIterable<T>, handler: RunItemsEachHandler<T>, options?: RunItemsEachOptions<T>): Promise<RunItemsEachResult>;
 }
 /**
  * Progresso da execução (itens processados / total) — opcional e independente de
@@ -409,11 +499,6 @@ 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>;
 }
@@ -434,6 +519,12 @@ interface Hobots extends RunContext {
     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;
@@ -444,5 +535,6 @@ declare const start: (task: string, handler: TaskHandler, options?: StartOptions
 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 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 };
+export { type AttachInput, type CaptureAttachment, type CaptureHint, EnvironmentInput, EventPayload, EventType, HeartbeatPayload, type Hobots, type HobotsOptions, ImageAttachment, type ImageInput, type ImageOptions, type ItemColumnInput, MachineSnapshot, type RegisterOptions, type RetryDelay, type RetryOptions, RunAttachmentContentType, type RunContext, type RunItemHandle, type RunItemImageOptions, type RunItemOptions, RunItemStatus, type RunItems, type RunItemsEachHandler, type RunItemsEachOptions, type RunItemsEachResult, RunLogLevel, type RunLogger, RunProgress, type RunProgressReporter, type StartOptions, Step, StepData, type StepOutcomeOptions, StepStatus, type TaskHandler, type TaskItemsOptions, type TaskOptions, Transaction, TransactionPayload, captureException, close, hobots as default, hobots, image, register, retry, start };