hobots 5.0.0 → 5.2.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { RunAttachmentContentType, EnvironmentInput, EventType, FileRef, RunItemStatus, RunProgress } from './protocol.cjs';
-export { Breadcrumb, BreadcrumbLevel, Envelope, EnvelopeItem, Environment, EventPayload, EventUser, ExceptionData, FileDownloadResponse, FileStorage, HeartbeatPayload, InstanceInfo, InstanceMode, ItemColumn, ItemsDeclaration, MachineProcess, MachineSnapshot, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunCreateRequest, RunCreateResponse, RunDescriptor, RunError, RunItemInput, RunItemsCreateRequest, RunItemsCreateResponse, RunLogEntry, RunLogLevel, RunStartRequest, RunStartResponse, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame, StepData, StepStatus, TransactionPayload } from './protocol.cjs';
+export { Breadcrumb, BreadcrumbLevel, Envelope, EnvelopeItem, Environment, EventPayload, EventUser, ExceptionData, FileDownloadResponse, FileStorage, HeartbeatPayload, InstanceInfo, InstanceMode, ItemColumn, ItemsDeclaration, MachineProcess, MachineSnapshot, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunCreateRequest, RunCreateResponse, RunDescriptor, RunError, RunItemInput, RunItemsCreateRequest, RunItemsCreateResponse, RunItemsDoneRequest, RunItemsDoneResponse, RunLogEntry, RunLogLevel, RunStartRequest, RunStartResponse, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame, StepData, StepStatus, TransactionPayload } 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);
@@ -272,20 +272,32 @@ interface RunItemOptions extends RunItemImageOptions {
 /**
  * O item em processamento dentro de `items.each`: o desfecho (`succeeded`/`failed`/
  * `occurrence`) com o `id` e o payload base já resolvidos, e o handle `step` da etapa do
- * item (`warning`/`image`/`data`). Sub-etapas: `hobots.step(...)` dentro do handler já
+ * item (`warning`/`image`/`data`), e `data(...)` para ir guardando o payload do item sem
+ * decidir o desfecho. Sub-etapas: `hobots.step(...)` dentro do handler já
  * aninha na etapa do item. 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;
+    /** Identidade do item: a resolvida por `options.id` ou, sem ela, uma gerada pelo SDK — a mesma em todas as tentativas. */
+    readonly id: string;
     /** Handle da etapa deste item no waterfall de performance; undefined fora de uma execução. */
     readonly step: StepHandle | 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`. */
+    /** Desfecho registrado até agora (undefined = nenhum). */
+    readonly status: RunItemStatus | undefined;
+    /** Tentativa em curso (1-based) — o handler pode ler para logar. */
+    readonly attempt: number;
+    /**
+     * Guarda atributos do item sem registrar desfecho — vai mesclando a cada chamada (chave repetida:
+     * a última vence). Entra em qualquer desfecho, inclusive nos implícitos (handler retornou →
+     * `succeeded`; lançou → `failed`), entre o payload base de `options.payload` e o payload da
+     * chamada de desfecho. Uma nova tentativa começa do zero. Depois do desfecho só acumula: nada é reenviado.
+     */
+    data(payload: Record<string, unknown>): void;
+    /** Item processado com sucesso. `payload` é mesclado sobre o payload base e o de `item.data`. */
     succeeded(payload?: Record<string, unknown>, options?: RunItemImageOptions): void;
     /** Falha sem lançar — o loop segue igual; a etapa vira `error` com o motivo. A imagem vai no item. */
     failed(message: string, payload?: Record<string, unknown>, options?: RunItemImageOptions): void;
@@ -293,8 +305,14 @@ interface RunItemHandle {
     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;
+    /**
+     * Identidade de negócio do item: nome do campo do elemento (`'numero'`), chave composta
+     * (`['cnpj', 'competencia']`, juntada com `|`) ou função `(elemento, índice) => id`.
+     * Omitido: o campo `id` do elemento, se existir. `null`, ou elemento sem o campo padrão:
+     * o SDK gera um id único (e o item nunca é pulado na reexecução). Campo explícito ausente
+     * no elemento é erro do bot (lança e interrompe o loop).
+     */
+    id?: string | readonly string[] | ((element: T, index: number) => string | number | null | undefined) | null;
     /** 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 etapa de cada item no waterfall. Default: 'item'. */
@@ -311,6 +329,18 @@ interface RunItemsEachOptions<T> {
      * Central na hora. `false` desliga (tudo sai no envio periódico ou no fim da run). Default: true.
      */
     flush?: boolean;
+    /**
+     * Tentativas extras quando o handler lança (falha técnica). Uma etapa só por elemento,
+     * com `data.attempts`. `0` desliga. `Occurrence` nunca é retentada. Default: 1.
+     */
+    retries?: number;
+    /** Espera entre as tentativas: ms fixo ou função da tentativa que falhou (1-based). Default: 5_000. */
+    retryDelayMs?: RetryDelay;
+    /**
+     * Na reexecução do mesmo trabalho (Central/Studio → executar novamente), pula o item cujo `id`
+     * já deu `succeeded`/`occurrence` — só `failed` roda de novo. `false` processa tudo. Default: true.
+     */
+    skipDone?: boolean;
 }
 /** Totalizadores do `items.each`, pelo desfecho final de cada elemento. */
 interface RunItemsEachResult {
@@ -318,6 +348,8 @@ interface RunItemsEachResult {
     succeeded: number;
     failed: number;
     occurrence: number;
+    /** Já concluídos neste trabalho (reexecução): não rodaram, mas contam no `total`. */
+    skipped: number;
 }
 type RunItemsEachHandler<T> = (element: T, item: RunItemHandle, index: number) => unknown;
 /**
@@ -462,4 +494,26 @@ declare const retry: <T>(fn: (attempt: number) => T | Promise<T>, options?: Retr
 declare const image: (input: AttachInput, options?: ImageOptions) => ImageAttachment;
 declare const isFileRef: (value: unknown) => value is FileRef;
 
-export { type AttachInput, type CaptureAttachment, type CaptureHint, EnvironmentInput, EventType, type FileDownloadOptions, FileRef, type Hobots, type HobotsOptions, ImageAttachment, type ImageInput, type ImageOptions, type ItemColumnInput, type ItemsOptions, type RegisterOptions, type RetryDelay, type RetryOptions, RunAttachmentContentType, type RunContext, type RunFiles, type RunHandler, type RunItemHandle, type RunItemImageOptions, type RunItemOptions, RunItemStatus, type RunItems, type RunItemsEachHandler, type RunItemsEachOptions, type RunItemsEachResult, type RunLogger, type RunOptions, RunProgress, type RunProgressReporter, type StartOptions, type StepFn, type StepHandle, type StepOptions, captureException, close, hobots as default, hobots, image, isFileRef, register, retry, start };
+/** Erros de controle do ciclo de vida de uma run — identificados pelo `name`, nunca pela classe. */
+/**
+ * Ocorrência de negócio lançada de dentro do handler de `hobots.items.each`: o item vira
+ * `occurrence` com esta mensagem (e `payload`/`image`, se vierem), a etapa do item vira
+ * `warning` e o loop segue — **sem nova tentativa**: o retry do `each` é só para falha
+ * técnica (qualquer outro erro). Use para regra de negócio: "nota já cadastrada",
+ * "cliente sem pendência", "produto fora do cardápio".
+ *
+ *     throw new Occurrence('nota já cadastrada', { situacao: 'já cadastrada' });
+ *
+ * Fora do `each` (handler de `register()`/`start()` sem loop) é um erro comum: a run falha
+ * com ele como com qualquer outro.
+ */
+declare class Occurrence extends Error {
+    readonly payload: Record<string, unknown> | undefined;
+    /** Print do item (bytes/caminho ou `hobots.image(...)`) — o `each` pendura no item. */
+    readonly image: ImageInput | undefined;
+    constructor(message: string, payload?: Record<string, unknown>, options?: {
+        image?: ImageInput;
+    });
+}
+
+export { type AttachInput, type CaptureAttachment, type CaptureHint, EnvironmentInput, EventType, type FileDownloadOptions, FileRef, type Hobots, type HobotsOptions, ImageAttachment, type ImageInput, type ImageOptions, type ItemColumnInput, type ItemsOptions, Occurrence, type RegisterOptions, type RetryDelay, type RetryOptions, RunAttachmentContentType, type RunContext, type RunFiles, type RunHandler, type RunItemHandle, type RunItemImageOptions, type RunItemOptions, RunItemStatus, type RunItems, type RunItemsEachHandler, type RunItemsEachOptions, type RunItemsEachResult, type RunLogger, type RunOptions, RunProgress, type RunProgressReporter, type StartOptions, type StepFn, type StepHandle, type StepOptions, captureException, close, hobots as default, hobots, image, isFileRef, register, retry, start };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { RunAttachmentContentType, EnvironmentInput, EventType, FileRef, RunItemStatus, RunProgress } from './protocol.js';
-export { Breadcrumb, BreadcrumbLevel, Envelope, EnvelopeItem, Environment, EventPayload, EventUser, ExceptionData, FileDownloadResponse, FileStorage, HeartbeatPayload, InstanceInfo, InstanceMode, ItemColumn, ItemsDeclaration, MachineProcess, MachineSnapshot, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunCreateRequest, RunCreateResponse, RunDescriptor, RunError, RunItemInput, RunItemsCreateRequest, RunItemsCreateResponse, RunLogEntry, RunLogLevel, RunStartRequest, RunStartResponse, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame, StepData, StepStatus, TransactionPayload } from './protocol.js';
+export { Breadcrumb, BreadcrumbLevel, Envelope, EnvelopeItem, Environment, EventPayload, EventUser, ExceptionData, FileDownloadResponse, FileStorage, HeartbeatPayload, InstanceInfo, InstanceMode, ItemColumn, ItemsDeclaration, MachineProcess, MachineSnapshot, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunCreateRequest, RunCreateResponse, RunDescriptor, RunError, RunItemInput, RunItemsCreateRequest, RunItemsCreateResponse, RunItemsDoneRequest, RunItemsDoneResponse, RunLogEntry, RunLogLevel, RunStartRequest, RunStartResponse, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame, StepData, StepStatus, TransactionPayload } 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);
@@ -272,20 +272,32 @@ interface RunItemOptions extends RunItemImageOptions {
 /**
  * O item em processamento dentro de `items.each`: o desfecho (`succeeded`/`failed`/
  * `occurrence`) com o `id` e o payload base já resolvidos, e o handle `step` da etapa do
- * item (`warning`/`image`/`data`). Sub-etapas: `hobots.step(...)` dentro do handler já
+ * item (`warning`/`image`/`data`), e `data(...)` para ir guardando o payload do item sem
+ * decidir o desfecho. Sub-etapas: `hobots.step(...)` dentro do handler já
  * aninha na etapa do item. 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;
+    /** Identidade do item: a resolvida por `options.id` ou, sem ela, uma gerada pelo SDK — a mesma em todas as tentativas. */
+    readonly id: string;
     /** Handle da etapa deste item no waterfall de performance; undefined fora de uma execução. */
     readonly step: StepHandle | 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`. */
+    /** Desfecho registrado até agora (undefined = nenhum). */
+    readonly status: RunItemStatus | undefined;
+    /** Tentativa em curso (1-based) — o handler pode ler para logar. */
+    readonly attempt: number;
+    /**
+     * Guarda atributos do item sem registrar desfecho — vai mesclando a cada chamada (chave repetida:
+     * a última vence). Entra em qualquer desfecho, inclusive nos implícitos (handler retornou →
+     * `succeeded`; lançou → `failed`), entre o payload base de `options.payload` e o payload da
+     * chamada de desfecho. Uma nova tentativa começa do zero. Depois do desfecho só acumula: nada é reenviado.
+     */
+    data(payload: Record<string, unknown>): void;
+    /** Item processado com sucesso. `payload` é mesclado sobre o payload base e o de `item.data`. */
     succeeded(payload?: Record<string, unknown>, options?: RunItemImageOptions): void;
     /** Falha sem lançar — o loop segue igual; a etapa vira `error` com o motivo. A imagem vai no item. */
     failed(message: string, payload?: Record<string, unknown>, options?: RunItemImageOptions): void;
@@ -293,8 +305,14 @@ interface RunItemHandle {
     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;
+    /**
+     * Identidade de negócio do item: nome do campo do elemento (`'numero'`), chave composta
+     * (`['cnpj', 'competencia']`, juntada com `|`) ou função `(elemento, índice) => id`.
+     * Omitido: o campo `id` do elemento, se existir. `null`, ou elemento sem o campo padrão:
+     * o SDK gera um id único (e o item nunca é pulado na reexecução). Campo explícito ausente
+     * no elemento é erro do bot (lança e interrompe o loop).
+     */
+    id?: string | readonly string[] | ((element: T, index: number) => string | number | null | undefined) | null;
     /** 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 etapa de cada item no waterfall. Default: 'item'. */
@@ -311,6 +329,18 @@ interface RunItemsEachOptions<T> {
      * Central na hora. `false` desliga (tudo sai no envio periódico ou no fim da run). Default: true.
      */
     flush?: boolean;
+    /**
+     * Tentativas extras quando o handler lança (falha técnica). Uma etapa só por elemento,
+     * com `data.attempts`. `0` desliga. `Occurrence` nunca é retentada. Default: 1.
+     */
+    retries?: number;
+    /** Espera entre as tentativas: ms fixo ou função da tentativa que falhou (1-based). Default: 5_000. */
+    retryDelayMs?: RetryDelay;
+    /**
+     * Na reexecução do mesmo trabalho (Central/Studio → executar novamente), pula o item cujo `id`
+     * já deu `succeeded`/`occurrence` — só `failed` roda de novo. `false` processa tudo. Default: true.
+     */
+    skipDone?: boolean;
 }
 /** Totalizadores do `items.each`, pelo desfecho final de cada elemento. */
 interface RunItemsEachResult {
@@ -318,6 +348,8 @@ interface RunItemsEachResult {
     succeeded: number;
     failed: number;
     occurrence: number;
+    /** Já concluídos neste trabalho (reexecução): não rodaram, mas contam no `total`. */
+    skipped: number;
 }
 type RunItemsEachHandler<T> = (element: T, item: RunItemHandle, index: number) => unknown;
 /**
@@ -462,4 +494,26 @@ declare const retry: <T>(fn: (attempt: number) => T | Promise<T>, options?: Retr
 declare const image: (input: AttachInput, options?: ImageOptions) => ImageAttachment;
 declare const isFileRef: (value: unknown) => value is FileRef;
 
-export { type AttachInput, type CaptureAttachment, type CaptureHint, EnvironmentInput, EventType, type FileDownloadOptions, FileRef, type Hobots, type HobotsOptions, ImageAttachment, type ImageInput, type ImageOptions, type ItemColumnInput, type ItemsOptions, type RegisterOptions, type RetryDelay, type RetryOptions, RunAttachmentContentType, type RunContext, type RunFiles, type RunHandler, type RunItemHandle, type RunItemImageOptions, type RunItemOptions, RunItemStatus, type RunItems, type RunItemsEachHandler, type RunItemsEachOptions, type RunItemsEachResult, type RunLogger, type RunOptions, RunProgress, type RunProgressReporter, type StartOptions, type StepFn, type StepHandle, type StepOptions, captureException, close, hobots as default, hobots, image, isFileRef, register, retry, start };
+/** Erros de controle do ciclo de vida de uma run — identificados pelo `name`, nunca pela classe. */
+/**
+ * Ocorrência de negócio lançada de dentro do handler de `hobots.items.each`: o item vira
+ * `occurrence` com esta mensagem (e `payload`/`image`, se vierem), a etapa do item vira
+ * `warning` e o loop segue — **sem nova tentativa**: o retry do `each` é só para falha
+ * técnica (qualquer outro erro). Use para regra de negócio: "nota já cadastrada",
+ * "cliente sem pendência", "produto fora do cardápio".
+ *
+ *     throw new Occurrence('nota já cadastrada', { situacao: 'já cadastrada' });
+ *
+ * Fora do `each` (handler de `register()`/`start()` sem loop) é um erro comum: a run falha
+ * com ele como com qualquer outro.
+ */
+declare class Occurrence extends Error {
+    readonly payload: Record<string, unknown> | undefined;
+    /** Print do item (bytes/caminho ou `hobots.image(...)`) — o `each` pendura no item. */
+    readonly image: ImageInput | undefined;
+    constructor(message: string, payload?: Record<string, unknown>, options?: {
+        image?: ImageInput;
+    });
+}
+
+export { type AttachInput, type CaptureAttachment, type CaptureHint, EnvironmentInput, EventType, type FileDownloadOptions, FileRef, type Hobots, type HobotsOptions, ImageAttachment, type ImageInput, type ImageOptions, type ItemColumnInput, type ItemsOptions, Occurrence, type RegisterOptions, type RetryDelay, type RetryOptions, RunAttachmentContentType, type RunContext, type RunFiles, type RunHandler, type RunItemHandle, type RunItemImageOptions, type RunItemOptions, RunItemStatus, type RunItems, type RunItemsEachHandler, type RunItemsEachOptions, type RunItemsEachResult, type RunLogger, type RunOptions, RunProgress, type RunProgressReporter, type StartOptions, type StepFn, type StepHandle, type StepOptions, captureException, close, hobots as default, hobots, image, isFileRef, register, retry, start };