hobots 4.0.0 → 4.2.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-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, 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.cjs';
+import { RunAttachmentContentType, EventType, EnvironmentInput, MachineSnapshot, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, RunLogLevel, StepData, FileRef, RunItemStatus, RunProgress } from './protocol.cjs';
+export { Breadcrumb, BreadcrumbLevel, Envelope, EnvelopeItem, Environment, EventUser, ExceptionData, FileDownloadResponse, FileStorage, 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.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);
@@ -340,9 +340,53 @@ declare class Transaction {
     setTag(key: string, value: string): this;
     setStatus(status: string): this;
     setName(name: string): this;
+    /**
+     * Envia já as steps raiz finalizadas (e todas as descendentes, fechando as que
+     * ficaram abertas) como transactions parciais da mesma run (`op` hobots.run.flush,
+     * `event_id` novo, até 200 steps cada) e as tira da memória. Steps raiz ainda abertas
+     * ficam para o próximo flush ou para o `finish()`. É assim que um agente sempre
+     * ligado (`start()`), cuja run não termina, entrega as etapas enquanto processa.
+     * Devolve quantas steps foram enviadas.
+     */
+    flush(): number;
+    /** Entrega já (com teto) o que está na fila do transport — as transactions parciais inclusive. */
+    drain(timeoutMs: number): Promise<void>;
+    private payload;
     finish(): void;
 }
 
+interface FileDownloadOptions {
+    /**
+     * Destino da cópia: uma pasta existente (ou terminada em `/`) recebe o arquivo com o nome
+     * original; qualquer outro caminho é o arquivo final. Omitido: pasta temporária da
+     * execução, apagada quando ela termina.
+     */
+    dest?: string;
+}
+/**
+ * Arquivos dos campos de upload do formulário (`hobots.files`). O valor do campo nos
+ * params é um `FileRef` (ou uma lista deles); `download` traz o arquivo para o disco
+ * desta máquina — do S3 (enviado pela Central) ou da pasta do Studio (mesmo computador)
+ * — e o consome na origem: cada arquivo é baixado uma vez.
+ */
+interface RunFiles {
+    /** Todos os arquivos dos params (campos de topo, valor único ou lista), na ordem dos campos. */
+    list(): FileRef[];
+    /** O arquivo do campo (campo único), a lista (campo "vários arquivos") ou undefined. */
+    get(field: string): FileRef | FileRef[] | undefined;
+    /**
+     * Baixa um arquivo e resolve com o caminho local. Aceita o `FileRef` ou o nome de um
+     * campo de arquivo único (para campo com vários arquivos, use `downloadAll`). Só depois
+     * da cópia completa e conferida o arquivo é consumido na origem — uma falha não perde
+     * nada e pode ser tentada de novo. Respeita o cancelamento da execução.
+     */
+    download(refOrField: FileRef | string, options?: FileDownloadOptions): Promise<string>;
+    /** Baixa todos os arquivos do campo (único ou lista), em ordem. `dest` aqui é uma pasta. */
+    downloadAll(field: string, options?: FileDownloadOptions): Promise<string[]>;
+    /** Conteúdo do arquivo em memória — baixa, lê e apaga a cópia temporária. */
+    read(refOrField: FileRef | string): Promise<Buffer>;
+}
+
 /**
  * `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.
@@ -483,12 +527,26 @@ interface RunContext {
     readonly items: RunItems;
     /** Progresso declarado (barra + ETA no app) — opcional, independente de `items` */
     readonly progress: RunProgressReporter;
+    /**
+     * Arquivos dos campos de upload do formulário: `list()`, `get(campo)`, `download(refOuCampo)`
+     * (caminho local), `downloadAll(campo)` e `read(refOuCampo)` (conteúdo em memória).
+     * Cada arquivo é consumido na origem ao ser baixado — baixe uma vez e reaproveite a cópia.
+     */
+    readonly files: RunFiles;
     /**
      * Transaction de performance desta execução — já correlacionada à run e finalizada
      * automaticamente ao fim do handler. Use `transaction.startChild(op, description)` para
      * medir as etapas (steps); elas aparecem como waterfall na aba de performance da execução.
      */
     readonly transaction: Transaction;
+    /**
+     * Entrega já o que a execução fez: as steps raiz finalizadas viram transactions parciais
+     * (waterfall da Central sem esperar a run terminar) e itens, logs e progresso pendentes
+     * saem sem esperar o throttle. Quem decide quando chamar é o bot — num agente sempre
+     * ligado (`start()`), ao fim de cada rodada que processou itens. Aguarda a entrega com
+     * teto (`timeoutMs`, default 15s) e nunca lança.
+     */
+    flush(timeoutMs?: number): Promise<void>;
     /** Dispara em cancelamento (run cancelada no app), timeout ou shutdown — cancelamento cooperativo */
     readonly signal: AbortSignal;
     /**
@@ -527,6 +585,8 @@ interface Hobots extends RunContext {
      * `step.setError(err, undefined, { image: png })`. Puro: nenhum I/O até o evento ser registrado.
      */
     image(input: AttachInput, options?: ImageOptions): ImageAttachment;
+    /** O valor tem a forma de um arquivo de campo de upload (`FileRef`) — puro, sem I/O. */
+    isFileRef(value: unknown): value is FileRef;
 }
 declare global {
     var hobots: Hobots;
@@ -538,5 +598,6 @@ 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;
+declare const isFileRef: (value: unknown) => value is FileRef;
 
-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 };
+export { type AttachInput, type CaptureAttachment, type CaptureHint, EnvironmentInput, EventPayload, EventType, type FileDownloadOptions, FileRef, 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 RunFiles, 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, isFileRef, register, retry, start };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-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';
+import { RunAttachmentContentType, EventType, EnvironmentInput, MachineSnapshot, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, RunLogLevel, StepData, FileRef, RunItemStatus, RunProgress } from './protocol.js';
+export { Breadcrumb, BreadcrumbLevel, Envelope, EnvelopeItem, Environment, EventUser, ExceptionData, FileDownloadResponse, FileStorage, 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);
@@ -340,9 +340,53 @@ declare class Transaction {
     setTag(key: string, value: string): this;
     setStatus(status: string): this;
     setName(name: string): this;
+    /**
+     * Envia já as steps raiz finalizadas (e todas as descendentes, fechando as que
+     * ficaram abertas) como transactions parciais da mesma run (`op` hobots.run.flush,
+     * `event_id` novo, até 200 steps cada) e as tira da memória. Steps raiz ainda abertas
+     * ficam para o próximo flush ou para o `finish()`. É assim que um agente sempre
+     * ligado (`start()`), cuja run não termina, entrega as etapas enquanto processa.
+     * Devolve quantas steps foram enviadas.
+     */
+    flush(): number;
+    /** Entrega já (com teto) o que está na fila do transport — as transactions parciais inclusive. */
+    drain(timeoutMs: number): Promise<void>;
+    private payload;
     finish(): void;
 }
 
+interface FileDownloadOptions {
+    /**
+     * Destino da cópia: uma pasta existente (ou terminada em `/`) recebe o arquivo com o nome
+     * original; qualquer outro caminho é o arquivo final. Omitido: pasta temporária da
+     * execução, apagada quando ela termina.
+     */
+    dest?: string;
+}
+/**
+ * Arquivos dos campos de upload do formulário (`hobots.files`). O valor do campo nos
+ * params é um `FileRef` (ou uma lista deles); `download` traz o arquivo para o disco
+ * desta máquina — do S3 (enviado pela Central) ou da pasta do Studio (mesmo computador)
+ * — e o consome na origem: cada arquivo é baixado uma vez.
+ */
+interface RunFiles {
+    /** Todos os arquivos dos params (campos de topo, valor único ou lista), na ordem dos campos. */
+    list(): FileRef[];
+    /** O arquivo do campo (campo único), a lista (campo "vários arquivos") ou undefined. */
+    get(field: string): FileRef | FileRef[] | undefined;
+    /**
+     * Baixa um arquivo e resolve com o caminho local. Aceita o `FileRef` ou o nome de um
+     * campo de arquivo único (para campo com vários arquivos, use `downloadAll`). Só depois
+     * da cópia completa e conferida o arquivo é consumido na origem — uma falha não perde
+     * nada e pode ser tentada de novo. Respeita o cancelamento da execução.
+     */
+    download(refOrField: FileRef | string, options?: FileDownloadOptions): Promise<string>;
+    /** Baixa todos os arquivos do campo (único ou lista), em ordem. `dest` aqui é uma pasta. */
+    downloadAll(field: string, options?: FileDownloadOptions): Promise<string[]>;
+    /** Conteúdo do arquivo em memória — baixa, lê e apaga a cópia temporária. */
+    read(refOrField: FileRef | string): Promise<Buffer>;
+}
+
 /**
  * `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.
@@ -483,12 +527,26 @@ interface RunContext {
     readonly items: RunItems;
     /** Progresso declarado (barra + ETA no app) — opcional, independente de `items` */
     readonly progress: RunProgressReporter;
+    /**
+     * Arquivos dos campos de upload do formulário: `list()`, `get(campo)`, `download(refOuCampo)`
+     * (caminho local), `downloadAll(campo)` e `read(refOuCampo)` (conteúdo em memória).
+     * Cada arquivo é consumido na origem ao ser baixado — baixe uma vez e reaproveite a cópia.
+     */
+    readonly files: RunFiles;
     /**
      * Transaction de performance desta execução — já correlacionada à run e finalizada
      * automaticamente ao fim do handler. Use `transaction.startChild(op, description)` para
      * medir as etapas (steps); elas aparecem como waterfall na aba de performance da execução.
      */
     readonly transaction: Transaction;
+    /**
+     * Entrega já o que a execução fez: as steps raiz finalizadas viram transactions parciais
+     * (waterfall da Central sem esperar a run terminar) e itens, logs e progresso pendentes
+     * saem sem esperar o throttle. Quem decide quando chamar é o bot — num agente sempre
+     * ligado (`start()`), ao fim de cada rodada que processou itens. Aguarda a entrega com
+     * teto (`timeoutMs`, default 15s) e nunca lança.
+     */
+    flush(timeoutMs?: number): Promise<void>;
     /** Dispara em cancelamento (run cancelada no app), timeout ou shutdown — cancelamento cooperativo */
     readonly signal: AbortSignal;
     /**
@@ -527,6 +585,8 @@ interface Hobots extends RunContext {
      * `step.setError(err, undefined, { image: png })`. Puro: nenhum I/O até o evento ser registrado.
      */
     image(input: AttachInput, options?: ImageOptions): ImageAttachment;
+    /** O valor tem a forma de um arquivo de campo de upload (`FileRef`) — puro, sem I/O. */
+    isFileRef(value: unknown): value is FileRef;
 }
 declare global {
     var hobots: Hobots;
@@ -538,5 +598,6 @@ 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;
+declare const isFileRef: (value: unknown) => value is FileRef;
 
-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 };
+export { type AttachInput, type CaptureAttachment, type CaptureHint, EnvironmentInput, EventPayload, EventType, type FileDownloadOptions, FileRef, 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 RunFiles, 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, isFileRef, register, retry, start };