hobots 3.4.0 → 4.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +38 -28
- package/dist/{chunk-5WIIACWC.js → chunk-HKCDMUA3.js} +1 -2
- package/dist/chunk-HKCDMUA3.js.map +1 -0
- package/dist/index.cjs +179 -231
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +47 -25
- package/dist/index.d.ts +47 -25
- package/dist/index.js +180 -231
- package/dist/index.js.map +1 -1
- package/dist/protocol.cjs +0 -1
- package/dist/protocol.cjs.map +1 -1
- package/dist/protocol.d.cts +21 -23
- package/dist/protocol.d.ts +21 -23
- package/dist/protocol.js +1 -1
- package/docs/README.md +10 -8
- package/docs/api-reference.md +34 -20
- package/docs/concepts.md +19 -19
- package/docs/getting-started.md +14 -12
- package/docs/protocol.md +24 -25
- package/docs/{tasks.md → runs.md} +51 -23
- package/package.json +2 -2
- package/dist/chunk-5WIIACWC.js.map +0 -1
package/dist/index.d.cts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { RunAttachmentContentType, EventType, EnvironmentInput, MachineSnapshot, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, RunLogLevel, StepData, RunItemStatus, RunProgress } from './protocol.cjs';
|
|
2
|
-
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
|
|
2
|
+
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';
|
|
3
3
|
|
|
4
4
|
/** Espera entre tentativas: ms fixo ou função do número da tentativa que acabou de falhar (1-based). */
|
|
5
5
|
type RetryDelay = number | ((attempt: number) => number);
|
|
@@ -57,7 +57,7 @@ interface HobotsOptions {
|
|
|
57
57
|
clientSecret?: string;
|
|
58
58
|
/**
|
|
59
59
|
* Identificador único e estável desta instância — a identidade do agente no painel
|
|
60
|
-
* (heartbeat e
|
|
60
|
+
* (heartbeat e execuções convergem nele). Default: env HOBOTS_INSTANCE_ID; sem ela, o hostname.
|
|
61
61
|
*/
|
|
62
62
|
instanceId?: string;
|
|
63
63
|
/**
|
|
@@ -88,11 +88,11 @@ interface HobotsOptions {
|
|
|
88
88
|
installExitHandlers?: boolean;
|
|
89
89
|
}
|
|
90
90
|
/** Colunas de itens declaradas no código (até 12; chave: letras, números, `.`, `-`, `_`). */
|
|
91
|
-
interface
|
|
91
|
+
interface ItemsOptions {
|
|
92
92
|
columns: ItemColumnInput[];
|
|
93
93
|
}
|
|
94
|
-
/** Opções
|
|
95
|
-
interface
|
|
94
|
+
/** Opções da execução do agente (register ou start). */
|
|
95
|
+
interface RunOptions extends HobotsOptions {
|
|
96
96
|
/**
|
|
97
97
|
* Colunas da aba "itens" da execução na plataforma: chaves do `payload` que cada
|
|
98
98
|
* item reportado (`ctx.items.*`) carrega, com rótulo opcional. Independe de
|
|
@@ -100,7 +100,7 @@ interface TaskOptions extends HobotsOptions {
|
|
|
100
100
|
* (Configurações → agente) sobrepõe o que for declarado aqui.
|
|
101
101
|
* Ex.: `{ columns: ['numero_nota', { key: 'valor', label: 'valor (R$)' }] }`
|
|
102
102
|
*/
|
|
103
|
-
items?:
|
|
103
|
+
items?: ItemsOptions;
|
|
104
104
|
/**
|
|
105
105
|
* Tentativas extras do handler quando ele lança, na mesma run (itens e progresso já
|
|
106
106
|
* enviados permanecem — escreva handlers idempotentes). Cancelamento e timeout nunca
|
|
@@ -128,15 +128,15 @@ interface TaskOptions extends HobotsOptions {
|
|
|
128
128
|
*/
|
|
129
129
|
cancelGraceMs?: number;
|
|
130
130
|
}
|
|
131
|
-
/** Opções de `register()` —
|
|
132
|
-
interface RegisterOptions extends
|
|
133
|
-
/** Runs simultâneas
|
|
131
|
+
/** Opções de `register()` — agente sob demanda, executado a partir das solicitações do app. */
|
|
132
|
+
interface RegisterOptions extends RunOptions {
|
|
133
|
+
/** Runs simultâneas do agente (1..5). Default: 1 (sequencial) */
|
|
134
134
|
concurrency?: number;
|
|
135
|
-
/** Intervalo entre polls sem trabalho (mínimo 1_000).
|
|
135
|
+
/** Intervalo entre polls sem trabalho (mínimo 1_000). Default: 2_000 */
|
|
136
136
|
pollIntervalMs?: number;
|
|
137
137
|
}
|
|
138
|
-
/** Opções de `start()` —
|
|
139
|
-
type StartOptions =
|
|
138
|
+
/** Opções de `start()` — agente sempre ligado, que abre a própria run. */
|
|
139
|
+
type StartOptions = RunOptions;
|
|
140
140
|
/** Imagem enviada junto de um captureException — com legenda e content-type opcionais. */
|
|
141
141
|
interface CaptureAttachment {
|
|
142
142
|
/** Bytes (`Uint8Array`/`ArrayBuffer`/`Buffer`) ou um caminho de arquivo (só em Node) */
|
|
@@ -170,8 +170,8 @@ interface ResolvedConfig {
|
|
|
170
170
|
baseUrl: string;
|
|
171
171
|
/** Ingestão de telemetria: <baseUrl>/v1/ingest */
|
|
172
172
|
ingestEndpoint: string;
|
|
173
|
-
/** API de
|
|
174
|
-
|
|
173
|
+
/** API de execuções (poll, runs, itens, anexos): <baseUrl>/v1/runs */
|
|
174
|
+
runsBaseUrl: string;
|
|
175
175
|
}
|
|
176
176
|
|
|
177
177
|
/**
|
|
@@ -299,7 +299,7 @@ declare class Transaction {
|
|
|
299
299
|
private readonly client;
|
|
300
300
|
name: string;
|
|
301
301
|
readonly op?: string | undefined;
|
|
302
|
-
/** Correlaciona a uma execução
|
|
302
|
+
/** Correlaciona a uma execução do agente — preenchido automaticamente em hobots.transaction */
|
|
303
303
|
private readonly runId?;
|
|
304
304
|
readonly eventId: string;
|
|
305
305
|
readonly stepId: string;
|
|
@@ -314,7 +314,7 @@ declare class Transaction {
|
|
|
314
314
|
private stepGuard?;
|
|
315
315
|
private lifecycleBacklog;
|
|
316
316
|
constructor(client: Client | undefined, name: string, op?: string | undefined,
|
|
317
|
-
/** Correlaciona a uma execução
|
|
317
|
+
/** Correlaciona a uma execução do agente — preenchido automaticamente em hobots.transaction */
|
|
318
318
|
runId?: string | undefined);
|
|
319
319
|
/**
|
|
320
320
|
* Registra o início/fim de uma step ou transaction: espelha a linha no sink de
|
|
@@ -340,6 +340,18 @@ declare class Transaction {
|
|
|
340
340
|
setTag(key: string, value: string): this;
|
|
341
341
|
setStatus(status: string): this;
|
|
342
342
|
setName(name: string): this;
|
|
343
|
+
/**
|
|
344
|
+
* Envia já as steps raiz finalizadas (e todas as descendentes, fechando as que
|
|
345
|
+
* ficaram abertas) como transactions parciais da mesma run (`op` hobots.run.flush,
|
|
346
|
+
* `event_id` novo, até 200 steps cada) e as tira da memória. Steps raiz ainda abertas
|
|
347
|
+
* ficam para o próximo flush ou para o `finish()`. É assim que um agente sempre
|
|
348
|
+
* ligado (`start()`), cuja run não termina, entrega as etapas enquanto processa.
|
|
349
|
+
* Devolve quantas steps foram enviadas.
|
|
350
|
+
*/
|
|
351
|
+
flush(): number;
|
|
352
|
+
/** Entrega já (com teto) o que está na fila do transport — as transactions parciais inclusive. */
|
|
353
|
+
drain(timeoutMs: number): Promise<void>;
|
|
354
|
+
private payload;
|
|
343
355
|
finish(): void;
|
|
344
356
|
}
|
|
345
357
|
|
|
@@ -475,7 +487,6 @@ interface RunProgressReporter {
|
|
|
475
487
|
*/
|
|
476
488
|
interface RunContext {
|
|
477
489
|
readonly runId: string;
|
|
478
|
-
readonly task: string;
|
|
479
490
|
/** Params da solicitação (formulário do app); `{}` no modo start */
|
|
480
491
|
readonly params: Record<string, unknown>;
|
|
481
492
|
/** Log bufferizado — enviado ao servidor em PATCHes incrementais com throttle. Nunca lança. */
|
|
@@ -490,6 +501,14 @@ interface RunContext {
|
|
|
490
501
|
* medir as etapas (steps); elas aparecem como waterfall na aba de performance da execução.
|
|
491
502
|
*/
|
|
492
503
|
readonly transaction: Transaction;
|
|
504
|
+
/**
|
|
505
|
+
* Entrega já o que a execução fez: as steps raiz finalizadas viram transactions parciais
|
|
506
|
+
* (waterfall da Central sem esperar a run terminar) e itens, logs e progresso pendentes
|
|
507
|
+
* saem sem esperar o throttle. Quem decide quando chamar é o bot — num agente sempre
|
|
508
|
+
* ligado (`start()`), ao fim de cada rodada que processou itens. Aguarda a entrega com
|
|
509
|
+
* teto (`timeoutMs`, default 15s) e nunca lança.
|
|
510
|
+
*/
|
|
511
|
+
flush(timeoutMs?: number): Promise<void>;
|
|
493
512
|
/** Dispara em cancelamento (run cancelada no app), timeout ou shutdown — cancelamento cooperativo */
|
|
494
513
|
readonly signal: AbortSignal;
|
|
495
514
|
/**
|
|
@@ -503,7 +522,7 @@ interface RunContext {
|
|
|
503
522
|
retry<T>(fn: (attempt: number) => T | Promise<T>, options?: RetryOptions): Promise<T>;
|
|
504
523
|
}
|
|
505
524
|
/** O retorno do handler é ignorado — nada além de status/logs/erro é enviado ao servidor. */
|
|
506
|
-
type
|
|
525
|
+
type RunHandler<P = Record<string, unknown>> = (params: P, ctx: RunContext) => void | Promise<void>;
|
|
507
526
|
|
|
508
527
|
/**
|
|
509
528
|
* O objeto global do SDK: as funções do processo (register/start/close/captureException/
|
|
@@ -511,10 +530,13 @@ type TaskHandler<P = Record<string, unknown>> = (params: P, ctx: RunContext) =>
|
|
|
511
530
|
* resolvido a cada acesso — funciona de qualquer módulo, sem passar `ctx` de mão em mão.
|
|
512
531
|
*/
|
|
513
532
|
interface Hobots extends RunContext {
|
|
514
|
-
/**
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
533
|
+
/**
|
|
534
|
+
* Agente sob demanda: o handler roda a cada solicitação do app (formulário/agendamento), via polling.
|
|
535
|
+
* O agente é a própria tarefa: uma chamada por processo (register OU start).
|
|
536
|
+
*/
|
|
537
|
+
register<P = Record<string, unknown>>(handler: RunHandler<P>, options?: RegisterOptions): void;
|
|
538
|
+
/** Agente sempre ligado: abre a própria run e roda o handler; a plataforma recebe logs, itens e progresso. */
|
|
539
|
+
start(handler: RunHandler, options?: StartOptions): void;
|
|
518
540
|
/** Encerra tudo (polling, runs em voo, heartbeat, flush final). Chame antes do processo terminar. */
|
|
519
541
|
close(timeoutMs?: number): Promise<boolean>;
|
|
520
542
|
/** Captura uma exceção como issue (módulo Issues). Retorna o event_id. */
|
|
@@ -530,11 +552,11 @@ declare global {
|
|
|
530
552
|
var hobots: Hobots;
|
|
531
553
|
}
|
|
532
554
|
declare const hobots: Hobots;
|
|
533
|
-
declare const register: <P = Record<string, unknown>>(
|
|
534
|
-
declare const start: (
|
|
555
|
+
declare const register: <P = Record<string, unknown>>(handler: RunHandler<P>, options?: RegisterOptions) => void;
|
|
556
|
+
declare const start: (handler: RunHandler, options?: StartOptions) => void;
|
|
535
557
|
declare const close: (timeoutMs?: number) => Promise<boolean>;
|
|
536
558
|
declare const captureException: (error: unknown, hint?: CaptureHint) => string | undefined;
|
|
537
559
|
declare const retry: <T>(fn: (attempt: number) => T | Promise<T>, options?: RetryOptions) => Promise<T>;
|
|
538
560
|
declare const image: (input: AttachInput, options?: ImageOptions) => ImageAttachment;
|
|
539
561
|
|
|
540
|
-
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,
|
|
562
|
+
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 };
|
package/dist/index.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { RunAttachmentContentType, EventType, EnvironmentInput, MachineSnapshot, EventPayload, TransactionPayload, HeartbeatPayload, StepStatus, RunLogLevel, StepData, RunItemStatus, RunProgress } from './protocol.js';
|
|
2
|
-
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
|
|
2
|
+
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';
|
|
3
3
|
|
|
4
4
|
/** Espera entre tentativas: ms fixo ou função do número da tentativa que acabou de falhar (1-based). */
|
|
5
5
|
type RetryDelay = number | ((attempt: number) => number);
|
|
@@ -57,7 +57,7 @@ interface HobotsOptions {
|
|
|
57
57
|
clientSecret?: string;
|
|
58
58
|
/**
|
|
59
59
|
* Identificador único e estável desta instância — a identidade do agente no painel
|
|
60
|
-
* (heartbeat e
|
|
60
|
+
* (heartbeat e execuções convergem nele). Default: env HOBOTS_INSTANCE_ID; sem ela, o hostname.
|
|
61
61
|
*/
|
|
62
62
|
instanceId?: string;
|
|
63
63
|
/**
|
|
@@ -88,11 +88,11 @@ interface HobotsOptions {
|
|
|
88
88
|
installExitHandlers?: boolean;
|
|
89
89
|
}
|
|
90
90
|
/** Colunas de itens declaradas no código (até 12; chave: letras, números, `.`, `-`, `_`). */
|
|
91
|
-
interface
|
|
91
|
+
interface ItemsOptions {
|
|
92
92
|
columns: ItemColumnInput[];
|
|
93
93
|
}
|
|
94
|
-
/** Opções
|
|
95
|
-
interface
|
|
94
|
+
/** Opções da execução do agente (register ou start). */
|
|
95
|
+
interface RunOptions extends HobotsOptions {
|
|
96
96
|
/**
|
|
97
97
|
* Colunas da aba "itens" da execução na plataforma: chaves do `payload` que cada
|
|
98
98
|
* item reportado (`ctx.items.*`) carrega, com rótulo opcional. Independe de
|
|
@@ -100,7 +100,7 @@ interface TaskOptions extends HobotsOptions {
|
|
|
100
100
|
* (Configurações → agente) sobrepõe o que for declarado aqui.
|
|
101
101
|
* Ex.: `{ columns: ['numero_nota', { key: 'valor', label: 'valor (R$)' }] }`
|
|
102
102
|
*/
|
|
103
|
-
items?:
|
|
103
|
+
items?: ItemsOptions;
|
|
104
104
|
/**
|
|
105
105
|
* Tentativas extras do handler quando ele lança, na mesma run (itens e progresso já
|
|
106
106
|
* enviados permanecem — escreva handlers idempotentes). Cancelamento e timeout nunca
|
|
@@ -128,15 +128,15 @@ interface TaskOptions extends HobotsOptions {
|
|
|
128
128
|
*/
|
|
129
129
|
cancelGraceMs?: number;
|
|
130
130
|
}
|
|
131
|
-
/** Opções de `register()` —
|
|
132
|
-
interface RegisterOptions extends
|
|
133
|
-
/** Runs simultâneas
|
|
131
|
+
/** Opções de `register()` — agente sob demanda, executado a partir das solicitações do app. */
|
|
132
|
+
interface RegisterOptions extends RunOptions {
|
|
133
|
+
/** Runs simultâneas do agente (1..5). Default: 1 (sequencial) */
|
|
134
134
|
concurrency?: number;
|
|
135
|
-
/** Intervalo entre polls sem trabalho (mínimo 1_000).
|
|
135
|
+
/** Intervalo entre polls sem trabalho (mínimo 1_000). Default: 2_000 */
|
|
136
136
|
pollIntervalMs?: number;
|
|
137
137
|
}
|
|
138
|
-
/** Opções de `start()` —
|
|
139
|
-
type StartOptions =
|
|
138
|
+
/** Opções de `start()` — agente sempre ligado, que abre a própria run. */
|
|
139
|
+
type StartOptions = RunOptions;
|
|
140
140
|
/** Imagem enviada junto de um captureException — com legenda e content-type opcionais. */
|
|
141
141
|
interface CaptureAttachment {
|
|
142
142
|
/** Bytes (`Uint8Array`/`ArrayBuffer`/`Buffer`) ou um caminho de arquivo (só em Node) */
|
|
@@ -170,8 +170,8 @@ interface ResolvedConfig {
|
|
|
170
170
|
baseUrl: string;
|
|
171
171
|
/** Ingestão de telemetria: <baseUrl>/v1/ingest */
|
|
172
172
|
ingestEndpoint: string;
|
|
173
|
-
/** API de
|
|
174
|
-
|
|
173
|
+
/** API de execuções (poll, runs, itens, anexos): <baseUrl>/v1/runs */
|
|
174
|
+
runsBaseUrl: string;
|
|
175
175
|
}
|
|
176
176
|
|
|
177
177
|
/**
|
|
@@ -299,7 +299,7 @@ declare class Transaction {
|
|
|
299
299
|
private readonly client;
|
|
300
300
|
name: string;
|
|
301
301
|
readonly op?: string | undefined;
|
|
302
|
-
/** Correlaciona a uma execução
|
|
302
|
+
/** Correlaciona a uma execução do agente — preenchido automaticamente em hobots.transaction */
|
|
303
303
|
private readonly runId?;
|
|
304
304
|
readonly eventId: string;
|
|
305
305
|
readonly stepId: string;
|
|
@@ -314,7 +314,7 @@ declare class Transaction {
|
|
|
314
314
|
private stepGuard?;
|
|
315
315
|
private lifecycleBacklog;
|
|
316
316
|
constructor(client: Client | undefined, name: string, op?: string | undefined,
|
|
317
|
-
/** Correlaciona a uma execução
|
|
317
|
+
/** Correlaciona a uma execução do agente — preenchido automaticamente em hobots.transaction */
|
|
318
318
|
runId?: string | undefined);
|
|
319
319
|
/**
|
|
320
320
|
* Registra o início/fim de uma step ou transaction: espelha a linha no sink de
|
|
@@ -340,6 +340,18 @@ declare class Transaction {
|
|
|
340
340
|
setTag(key: string, value: string): this;
|
|
341
341
|
setStatus(status: string): this;
|
|
342
342
|
setName(name: string): this;
|
|
343
|
+
/**
|
|
344
|
+
* Envia já as steps raiz finalizadas (e todas as descendentes, fechando as que
|
|
345
|
+
* ficaram abertas) como transactions parciais da mesma run (`op` hobots.run.flush,
|
|
346
|
+
* `event_id` novo, até 200 steps cada) e as tira da memória. Steps raiz ainda abertas
|
|
347
|
+
* ficam para o próximo flush ou para o `finish()`. É assim que um agente sempre
|
|
348
|
+
* ligado (`start()`), cuja run não termina, entrega as etapas enquanto processa.
|
|
349
|
+
* Devolve quantas steps foram enviadas.
|
|
350
|
+
*/
|
|
351
|
+
flush(): number;
|
|
352
|
+
/** Entrega já (com teto) o que está na fila do transport — as transactions parciais inclusive. */
|
|
353
|
+
drain(timeoutMs: number): Promise<void>;
|
|
354
|
+
private payload;
|
|
343
355
|
finish(): void;
|
|
344
356
|
}
|
|
345
357
|
|
|
@@ -475,7 +487,6 @@ interface RunProgressReporter {
|
|
|
475
487
|
*/
|
|
476
488
|
interface RunContext {
|
|
477
489
|
readonly runId: string;
|
|
478
|
-
readonly task: string;
|
|
479
490
|
/** Params da solicitação (formulário do app); `{}` no modo start */
|
|
480
491
|
readonly params: Record<string, unknown>;
|
|
481
492
|
/** Log bufferizado — enviado ao servidor em PATCHes incrementais com throttle. Nunca lança. */
|
|
@@ -490,6 +501,14 @@ interface RunContext {
|
|
|
490
501
|
* medir as etapas (steps); elas aparecem como waterfall na aba de performance da execução.
|
|
491
502
|
*/
|
|
492
503
|
readonly transaction: Transaction;
|
|
504
|
+
/**
|
|
505
|
+
* Entrega já o que a execução fez: as steps raiz finalizadas viram transactions parciais
|
|
506
|
+
* (waterfall da Central sem esperar a run terminar) e itens, logs e progresso pendentes
|
|
507
|
+
* saem sem esperar o throttle. Quem decide quando chamar é o bot — num agente sempre
|
|
508
|
+
* ligado (`start()`), ao fim de cada rodada que processou itens. Aguarda a entrega com
|
|
509
|
+
* teto (`timeoutMs`, default 15s) e nunca lança.
|
|
510
|
+
*/
|
|
511
|
+
flush(timeoutMs?: number): Promise<void>;
|
|
493
512
|
/** Dispara em cancelamento (run cancelada no app), timeout ou shutdown — cancelamento cooperativo */
|
|
494
513
|
readonly signal: AbortSignal;
|
|
495
514
|
/**
|
|
@@ -503,7 +522,7 @@ interface RunContext {
|
|
|
503
522
|
retry<T>(fn: (attempt: number) => T | Promise<T>, options?: RetryOptions): Promise<T>;
|
|
504
523
|
}
|
|
505
524
|
/** O retorno do handler é ignorado — nada além de status/logs/erro é enviado ao servidor. */
|
|
506
|
-
type
|
|
525
|
+
type RunHandler<P = Record<string, unknown>> = (params: P, ctx: RunContext) => void | Promise<void>;
|
|
507
526
|
|
|
508
527
|
/**
|
|
509
528
|
* O objeto global do SDK: as funções do processo (register/start/close/captureException/
|
|
@@ -511,10 +530,13 @@ type TaskHandler<P = Record<string, unknown>> = (params: P, ctx: RunContext) =>
|
|
|
511
530
|
* resolvido a cada acesso — funciona de qualquer módulo, sem passar `ctx` de mão em mão.
|
|
512
531
|
*/
|
|
513
532
|
interface Hobots extends RunContext {
|
|
514
|
-
/**
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
533
|
+
/**
|
|
534
|
+
* Agente sob demanda: o handler roda a cada solicitação do app (formulário/agendamento), via polling.
|
|
535
|
+
* O agente é a própria tarefa: uma chamada por processo (register OU start).
|
|
536
|
+
*/
|
|
537
|
+
register<P = Record<string, unknown>>(handler: RunHandler<P>, options?: RegisterOptions): void;
|
|
538
|
+
/** Agente sempre ligado: abre a própria run e roda o handler; a plataforma recebe logs, itens e progresso. */
|
|
539
|
+
start(handler: RunHandler, options?: StartOptions): void;
|
|
518
540
|
/** Encerra tudo (polling, runs em voo, heartbeat, flush final). Chame antes do processo terminar. */
|
|
519
541
|
close(timeoutMs?: number): Promise<boolean>;
|
|
520
542
|
/** Captura uma exceção como issue (módulo Issues). Retorna o event_id. */
|
|
@@ -530,11 +552,11 @@ declare global {
|
|
|
530
552
|
var hobots: Hobots;
|
|
531
553
|
}
|
|
532
554
|
declare const hobots: Hobots;
|
|
533
|
-
declare const register: <P = Record<string, unknown>>(
|
|
534
|
-
declare const start: (
|
|
555
|
+
declare const register: <P = Record<string, unknown>>(handler: RunHandler<P>, options?: RegisterOptions) => void;
|
|
556
|
+
declare const start: (handler: RunHandler, options?: StartOptions) => void;
|
|
535
557
|
declare const close: (timeoutMs?: number) => Promise<boolean>;
|
|
536
558
|
declare const captureException: (error: unknown, hint?: CaptureHint) => string | undefined;
|
|
537
559
|
declare const retry: <T>(fn: (attempt: number) => T | Promise<T>, options?: RetryOptions) => Promise<T>;
|
|
538
560
|
declare const image: (input: AttachInput, options?: ImageOptions) => ImageAttachment;
|
|
539
561
|
|
|
540
|
-
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,
|
|
562
|
+
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 };
|