hobots 1.6.0 → 1.7.1
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 +47 -45
- package/dist/index.cjs +105 -121
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +25 -124
- package/dist/index.d.ts +25 -124
- package/dist/index.js +105 -121
- package/dist/index.js.map +1 -1
- package/dist/protocol.cjs.map +1 -1
- package/dist/protocol.d.cts +73 -4
- package/dist/protocol.d.ts +73 -4
- package/docs/README.md +10 -10
- package/docs/api-reference.md +41 -43
- package/docs/concepts.md +30 -15
- package/docs/getting-started.md +17 -17
- package/docs/monitor.md +8 -8
- package/docs/protocol.md +21 -23
- package/docs/{manager.md → tasks.md} +18 -18
- package/package.json +2 -7
- package/dist/manager/protocol.cjs +0 -19
- package/dist/manager/protocol.cjs.map +0 -1
- package/dist/manager/protocol.d.cts +0 -72
- package/dist/manager/protocol.d.ts +0 -72
- package/dist/manager/protocol.js +0 -1
- package/dist/manager/protocol.js.map +0 -1
package/dist/index.d.cts
CHANGED
|
@@ -1,7 +1,5 @@
|
|
|
1
1
|
import { Breadcrumb, EventUser, Severity, EventPayload, TransactionPayload, CheckInPayload, HeartbeatPayload, SpanStatus, SpanData, CheckInStatus } from './protocol.cjs';
|
|
2
|
-
export { Envelope, EnvelopeItem, ExceptionData, StackFrame } from './protocol.cjs';
|
|
3
|
-
import { ManagerPollRequest, ManagerPollResponse, ManagerRunUpdateRequest } from './manager/protocol.cjs';
|
|
4
|
-
export { ManagerAgentInfo, ManagerRunDescriptor, ManagerRunError, ManagerRunStatus, ManagerRunUpdateResponse, ManagerRunUpdateStatus, RunLogEntry, RunLogLevel } from './manager/protocol.cjs';
|
|
2
|
+
export { AgentInfo, Envelope, EnvelopeItem, ExceptionData, PollRequest, PollResponse, RunDescriptor, RunError, RunLogEntry, RunLogLevel, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame } from './protocol.cjs';
|
|
5
3
|
|
|
6
4
|
/** API oficial da Hobots — o SDK sempre fala com ela em produção. */
|
|
7
5
|
declare const DEFAULT_BASE_URL = "https://api2.hobots.app";
|
|
@@ -9,16 +7,11 @@ interface ResolvedConfig {
|
|
|
9
7
|
/** Client Secret do projeto (enviado como Authorization: Bearer, nunca na URL) */
|
|
10
8
|
key: string;
|
|
11
9
|
baseUrl: string;
|
|
12
|
-
/** Ingestão
|
|
10
|
+
/** Ingestão de telemetria: <baseUrl>/v1/ingest */
|
|
13
11
|
ingestEndpoint: string;
|
|
14
|
-
/** API
|
|
15
|
-
|
|
12
|
+
/** API de tasks (execução sob demanda): <baseUrl>/v1/tasks */
|
|
13
|
+
tasksBaseUrl: string;
|
|
16
14
|
}
|
|
17
|
-
interface ConfigInput {
|
|
18
|
-
clientSecret: string;
|
|
19
|
-
}
|
|
20
|
-
/** Resolve o clientSecret nos endpoints do Monitor e do Manager. */
|
|
21
|
-
declare function resolveConfig(options: ConfigInput, prefix?: string): ResolvedConfig;
|
|
22
15
|
|
|
23
16
|
type BreadcrumbInput = Omit<Breadcrumb, 'timestamp'> & {
|
|
24
17
|
timestamp?: string;
|
|
@@ -55,7 +48,7 @@ declare class Client {
|
|
|
55
48
|
#private;
|
|
56
49
|
readonly logger: Logger;
|
|
57
50
|
private readonly transport;
|
|
58
|
-
constructor(options: InitOptions);
|
|
51
|
+
constructor(options: InitOptions, config?: ResolvedConfig);
|
|
59
52
|
get options(): InitOptions;
|
|
60
53
|
get config(): ResolvedConfig;
|
|
61
54
|
/** Serialização explícita nunca inclui o secret. */
|
|
@@ -98,7 +91,7 @@ declare class Transaction {
|
|
|
98
91
|
name: string;
|
|
99
92
|
readonly op?: string | undefined;
|
|
100
93
|
private readonly sampled;
|
|
101
|
-
/** Correlaciona a uma execução
|
|
94
|
+
/** Correlaciona a uma execução de task — preenchido automaticamente em ctx.tx */
|
|
102
95
|
private readonly runId?;
|
|
103
96
|
readonly eventId: string;
|
|
104
97
|
readonly spanId: string;
|
|
@@ -108,7 +101,7 @@ declare class Transaction {
|
|
|
108
101
|
private readonly tags;
|
|
109
102
|
private finished;
|
|
110
103
|
constructor(client: Client | undefined, name: string, op?: string | undefined, sampled?: boolean,
|
|
111
|
-
/** Correlaciona a uma execução
|
|
104
|
+
/** Correlaciona a uma execução de task — preenchido automaticamente em ctx.tx */
|
|
112
105
|
runId?: string | undefined);
|
|
113
106
|
createSpan(parentSpanId: string, op?: string, description?: string): Span;
|
|
114
107
|
/** Span direto da transaction. */
|
|
@@ -119,8 +112,8 @@ declare class Transaction {
|
|
|
119
112
|
finish(): void;
|
|
120
113
|
}
|
|
121
114
|
|
|
122
|
-
/** Opções
|
|
123
|
-
interface
|
|
115
|
+
/** Opções de tasks dentro de `init({ tasks: ... })`. Credencial (clientSecret), identidade (instanceId) e debug vêm do init. */
|
|
116
|
+
interface TasksOptions {
|
|
124
117
|
/** Intervalo entre polls sem trabalho. Default: 5_000 (mínimo 1_000) */
|
|
125
118
|
pollIntervalMs?: number;
|
|
126
119
|
/** Runs simultâneas (1..5). Default: 1 (sequencial) */
|
|
@@ -146,17 +139,6 @@ interface ManagerOptions {
|
|
|
146
139
|
*/
|
|
147
140
|
installExitHandlers?: boolean;
|
|
148
141
|
}
|
|
149
|
-
/** Opções resolvidas pelo init unificado e entregues ao ManagerAgent. */
|
|
150
|
-
interface ManagerAgentOptions extends ManagerOptions {
|
|
151
|
-
/** O Client Secret do projeto — o mesmo do Monitor */
|
|
152
|
-
clientSecret: string;
|
|
153
|
-
/** Identidade do agente no dashboard — o instanceId do init */
|
|
154
|
-
instanceId: string;
|
|
155
|
-
/** Loga atividade do SDK no console */
|
|
156
|
-
debug?: boolean;
|
|
157
|
-
/** Client do Monitor compartilhado — usado para enviar a transaction de performance de cada run (ctx.tx) */
|
|
158
|
-
client?: Client;
|
|
159
|
-
}
|
|
160
142
|
interface RunLogger {
|
|
161
143
|
debug(message: string): void;
|
|
162
144
|
info(message: string): void;
|
|
@@ -186,7 +168,7 @@ interface RunContext {
|
|
|
186
168
|
sleep(ms: number): Promise<void>;
|
|
187
169
|
}
|
|
188
170
|
/** O retorno do handler é ignorado — nada além de status/logs/erro é enviado ao servidor. */
|
|
189
|
-
type
|
|
171
|
+
type TaskHandler<P = Record<string, unknown>> = (params: P, ctx: RunContext) => void | Promise<void>;
|
|
190
172
|
|
|
191
173
|
interface HeartbeatOptions {
|
|
192
174
|
/** Intervalo entre batimentos. Default: 30_000 */
|
|
@@ -196,13 +178,13 @@ interface HeartbeatOptions {
|
|
|
196
178
|
metadata?: Record<string, unknown>;
|
|
197
179
|
}
|
|
198
180
|
interface InitOptions {
|
|
199
|
-
/** O Client Secret do projeto (hb_…) — a mesma credencial para
|
|
181
|
+
/** O Client Secret do projeto (hb_…) — a mesma credencial para telemetria e tasks. Copie em Configurações → Projetos. */
|
|
200
182
|
clientSecret: string;
|
|
201
183
|
/** Default: 'production' */
|
|
202
184
|
environment?: string;
|
|
203
185
|
/** Versão do programa, ex.: 'robo-nfe@1.4.2' */
|
|
204
186
|
release?: string;
|
|
205
|
-
/** Identificador único e estável desta instância — a identidade do agente no painel (heartbeat
|
|
187
|
+
/** Identificador único e estável desta instância — a identidade do agente no painel (heartbeat e poll de tasks convergem nele) */
|
|
206
188
|
instanceId: string;
|
|
207
189
|
/** Tags aplicadas a todos os eventos */
|
|
208
190
|
tags?: Record<string, string>;
|
|
@@ -217,10 +199,11 @@ interface InitOptions {
|
|
|
217
199
|
/** Habilita heartbeat periódico (true usa defaults) */
|
|
218
200
|
heartbeat?: boolean | HeartbeatOptions;
|
|
219
201
|
/**
|
|
220
|
-
* Habilita
|
|
221
|
-
* Usa o mesmo clientSecret e o instanceId como identidade.
|
|
202
|
+
* Habilita a execução remota de tarefas sob demanda — o módulo Solicitações do app
|
|
203
|
+
* (true usa defaults). Usa o mesmo clientSecret e o instanceId como identidade.
|
|
204
|
+
* Depois de init(), chame register() e start().
|
|
222
205
|
*/
|
|
223
|
-
|
|
206
|
+
tasks?: boolean | TasksOptions;
|
|
224
207
|
/** Última chance de editar/descartar um evento (retorne null para descartar) */
|
|
225
208
|
beforeSend?: (event: EventPayload) => EventPayload | null;
|
|
226
209
|
/** Loga atividade do SDK no console */
|
|
@@ -247,10 +230,7 @@ interface CheckInOptions {
|
|
|
247
230
|
schedule?: string;
|
|
248
231
|
timezone?: string;
|
|
249
232
|
}
|
|
250
|
-
|
|
251
|
-
schedule?: string;
|
|
252
|
-
timezone?: string;
|
|
253
|
-
}
|
|
233
|
+
type WithMonitorOptions = Pick<CheckInOptions, 'schedule' | 'timezone'>;
|
|
254
234
|
|
|
255
235
|
/** Inicializa o SDK. Chame uma vez, o mais cedo possível no programa. */
|
|
256
236
|
declare function init(options: InitOptions): void;
|
|
@@ -275,100 +255,21 @@ declare function checkIn(options: CheckInOptions): string | undefined;
|
|
|
275
255
|
declare function withMonitor<T>(monitorSlug: string, fn: () => T | Promise<T>, options?: WithMonitorOptions): Promise<T>;
|
|
276
256
|
/** Aguarda o envio de tudo que está na fila (até timeoutMs). */
|
|
277
257
|
declare function flush(timeoutMs?: number): Promise<boolean>;
|
|
278
|
-
/** Registra o handler de uma task
|
|
279
|
-
declare function register<P = Record<string, unknown>>(task: string, handler:
|
|
258
|
+
/** Registra o handler de uma task (o task_slug configurado no formulário do app, em Configurações → Formulários). */
|
|
259
|
+
declare function register<P = Record<string, unknown>>(task: string, handler: TaskHandler<P>): void;
|
|
280
260
|
/**
|
|
281
|
-
* Inicia o polling
|
|
282
|
-
* aguardando trabalho até stop()/close() — o inverso deliberado
|
|
261
|
+
* Inicia o polling de tasks. O timer NÃO é unref'd: o processo fica vivo
|
|
262
|
+
* aguardando trabalho até stop()/close() — o inverso deliberado da telemetria.
|
|
283
263
|
*/
|
|
284
264
|
declare function start(): void;
|
|
285
|
-
/** Para só o
|
|
265
|
+
/** Para só o polling de tasks e aguarda as runs ativas (até timeoutMs). A telemetria continua. */
|
|
286
266
|
declare function stop(timeoutMs?: number): Promise<boolean>;
|
|
287
267
|
/**
|
|
288
|
-
* Encerra tudo: para o
|
|
289
|
-
* flush final do transport. Chame antes do processo terminar.
|
|
268
|
+
* Encerra tudo: para o polling de tasks (aguardando runs em voo), o heartbeat
|
|
269
|
+
* e faz o flush final do transport. Chame antes do processo terminar.
|
|
290
270
|
*/
|
|
291
271
|
declare function close(timeoutMs?: number): Promise<boolean>;
|
|
292
272
|
|
|
293
273
|
declare function scrubSecrets(text: string): string;
|
|
294
274
|
|
|
295
|
-
|
|
296
|
-
* Loop de polling do Manager: busca runs pendentes, executa os handlers registrados
|
|
297
|
-
* e reporta status/logs/result. Ao contrário do Monitor, o timer de polling NÃO é
|
|
298
|
-
* unref'd — um agente iniciado mantém o processo vivo até stop().
|
|
299
|
-
*/
|
|
300
|
-
declare class ManagerAgent {
|
|
301
|
-
private readonly options;
|
|
302
|
-
private readonly registry;
|
|
303
|
-
readonly logger: Logger;
|
|
304
|
-
private readonly api;
|
|
305
|
-
private readonly client;
|
|
306
|
-
private readonly pollIntervalMs;
|
|
307
|
-
private readonly concurrency;
|
|
308
|
-
private readonly instanceId;
|
|
309
|
-
private readonly taskTimeoutMs?;
|
|
310
|
-
private readonly logFlushIntervalMs?;
|
|
311
|
-
private readonly cancelCheckIntervalMs?;
|
|
312
|
-
private state;
|
|
313
|
-
private timer;
|
|
314
|
-
private pollAbort;
|
|
315
|
-
private consecutiveFailures;
|
|
316
|
-
private consecutiveAuthFailures;
|
|
317
|
-
private readonly activeRuns;
|
|
318
|
-
private readonly reporters;
|
|
319
|
-
private uninstallShutdown;
|
|
320
|
-
constructor(options: ManagerAgentOptions, registry: Map<string, ManagerTaskHandler>);
|
|
321
|
-
get activeCount(): number;
|
|
322
|
-
start(): void;
|
|
323
|
-
/** Para o polling e aguarda as runs ativas (até timeoutMs). Retorna true se tudo terminou a tempo. */
|
|
324
|
-
stop(timeoutMs?: number): Promise<boolean>;
|
|
325
|
-
/**
|
|
326
|
-
* Best-effort do exit path: reporta 'failed'/AgentTerminated para as runs ativas
|
|
327
|
-
* antes do processo morrer, fora da fila do reporter e com timeout curto. Runs já
|
|
328
|
-
* canceladas no app (reporter morto) são puladas; erros de rede são engolidos —
|
|
329
|
-
* o sweep server-side é o backstop.
|
|
330
|
-
*/
|
|
331
|
-
reportAgentTerminated(message: string, timeoutMs?: number): Promise<void>;
|
|
332
|
-
/** Timer intencionalmente NÃO unref'd: o agente é a razão do processo existir. */
|
|
333
|
-
private schedule;
|
|
334
|
-
private tick;
|
|
335
|
-
private delayAfterPollError;
|
|
336
|
-
private dispatch;
|
|
337
|
-
private executeRun;
|
|
338
|
-
private invokeWithTimeout;
|
|
339
|
-
}
|
|
340
|
-
|
|
341
|
-
declare class ManagerApiError extends Error {
|
|
342
|
-
readonly status: number;
|
|
343
|
-
constructor(message: string, status: number);
|
|
344
|
-
}
|
|
345
|
-
interface ManagerApiOptions {
|
|
346
|
-
baseUrl: string;
|
|
347
|
-
key: string;
|
|
348
|
-
logger: Logger;
|
|
349
|
-
}
|
|
350
|
-
/** Cliente HTTP do agente — bearer auth, retry com backoff nos updates. */
|
|
351
|
-
declare class ManagerApi {
|
|
352
|
-
private readonly baseUrl;
|
|
353
|
-
private readonly key;
|
|
354
|
-
private readonly logger;
|
|
355
|
-
constructor(options: ManagerApiOptions);
|
|
356
|
-
private headers;
|
|
357
|
-
/** Um request só — o loop de polling é quem decide o backoff entre tentativas. */
|
|
358
|
-
poll(request: ManagerPollRequest, signal?: AbortSignal): Promise<ManagerPollResponse>;
|
|
359
|
-
/** Nunca confia no shape da resposta: runs malformadas são descartadas e o `max` é respeitado. */
|
|
360
|
-
private parsePollResponse;
|
|
361
|
-
/**
|
|
362
|
-
* PATCH de status/logs com retry em falha de rede/5xx/429.
|
|
363
|
-
* 4xx é definitivo e vira ManagerApiError imediato (409 = run cancelada/transição inválida).
|
|
364
|
-
*/
|
|
365
|
-
updateRun(runId: string, update: ManagerRunUpdateRequest): Promise<void>;
|
|
366
|
-
/**
|
|
367
|
-
* Um único PATCH com timeout curto — exit path (o processo está morrendo, o retry
|
|
368
|
-
* ladder do updateRun é proibido aqui). Status HTTP é ignorado: 409/404 significa
|
|
369
|
-
* que a run já foi cancelada/finalizada, o que é aceitável nesse caminho.
|
|
370
|
-
*/
|
|
371
|
-
updateRunOnce(runId: string, update: ManagerRunUpdateRequest, timeoutMs?: number): Promise<void>;
|
|
372
|
-
}
|
|
373
|
-
|
|
374
|
-
export { Breadcrumb, type BreadcrumbInput, type CaptureHint, type CheckInOptions, CheckInPayload, CheckInStatus, Client, DEFAULT_BASE_URL, EventPayload, EventUser, type HeartbeatOptions, HeartbeatPayload, type InitOptions, ManagerAgent, ManagerApi, ManagerApiError, type ManagerOptions, ManagerPollRequest, ManagerPollResponse, ManagerRunUpdateRequest, type ManagerTaskHandler, type ResolvedConfig, type RunContext, Scope, Severity, Span, SpanData, Transaction, TransactionPayload, type WithMonitorOptions, addBreadcrumb, captureException, captureMessage, checkIn, close, flush, getClient, init, register, resolveConfig, scrubSecrets, setContext, setExtra, setTag, setTags, setUser, start, startTransaction, stop, withMonitor, withScope };
|
|
275
|
+
export { Breadcrumb, type BreadcrumbInput, type CaptureHint, type CheckInOptions, CheckInPayload, CheckInStatus, Client, DEFAULT_BASE_URL, EventPayload, EventUser, type HeartbeatOptions, HeartbeatPayload, type InitOptions, type RunContext, Scope, Severity, Span, SpanData, type TaskHandler, type TasksOptions, Transaction, TransactionPayload, type WithMonitorOptions, addBreadcrumb, captureException, captureMessage, checkIn, close, flush, getClient, init, register, scrubSecrets, setContext, setExtra, setTag, setTags, setUser, start, startTransaction, stop, withMonitor, withScope };
|
package/dist/index.d.ts
CHANGED
|
@@ -1,7 +1,5 @@
|
|
|
1
1
|
import { Breadcrumb, EventUser, Severity, EventPayload, TransactionPayload, CheckInPayload, HeartbeatPayload, SpanStatus, SpanData, CheckInStatus } from './protocol.js';
|
|
2
|
-
export { Envelope, EnvelopeItem, ExceptionData, StackFrame } from './protocol.js';
|
|
3
|
-
import { ManagerPollRequest, ManagerPollResponse, ManagerRunUpdateRequest } from './manager/protocol.js';
|
|
4
|
-
export { ManagerAgentInfo, ManagerRunDescriptor, ManagerRunError, ManagerRunStatus, ManagerRunUpdateResponse, ManagerRunUpdateStatus, RunLogEntry, RunLogLevel } from './manager/protocol.js';
|
|
2
|
+
export { AgentInfo, Envelope, EnvelopeItem, ExceptionData, PollRequest, PollResponse, RunDescriptor, RunError, RunLogEntry, RunLogLevel, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame } from './protocol.js';
|
|
5
3
|
|
|
6
4
|
/** API oficial da Hobots — o SDK sempre fala com ela em produção. */
|
|
7
5
|
declare const DEFAULT_BASE_URL = "https://api2.hobots.app";
|
|
@@ -9,16 +7,11 @@ interface ResolvedConfig {
|
|
|
9
7
|
/** Client Secret do projeto (enviado como Authorization: Bearer, nunca na URL) */
|
|
10
8
|
key: string;
|
|
11
9
|
baseUrl: string;
|
|
12
|
-
/** Ingestão
|
|
10
|
+
/** Ingestão de telemetria: <baseUrl>/v1/ingest */
|
|
13
11
|
ingestEndpoint: string;
|
|
14
|
-
/** API
|
|
15
|
-
|
|
12
|
+
/** API de tasks (execução sob demanda): <baseUrl>/v1/tasks */
|
|
13
|
+
tasksBaseUrl: string;
|
|
16
14
|
}
|
|
17
|
-
interface ConfigInput {
|
|
18
|
-
clientSecret: string;
|
|
19
|
-
}
|
|
20
|
-
/** Resolve o clientSecret nos endpoints do Monitor e do Manager. */
|
|
21
|
-
declare function resolveConfig(options: ConfigInput, prefix?: string): ResolvedConfig;
|
|
22
15
|
|
|
23
16
|
type BreadcrumbInput = Omit<Breadcrumb, 'timestamp'> & {
|
|
24
17
|
timestamp?: string;
|
|
@@ -55,7 +48,7 @@ declare class Client {
|
|
|
55
48
|
#private;
|
|
56
49
|
readonly logger: Logger;
|
|
57
50
|
private readonly transport;
|
|
58
|
-
constructor(options: InitOptions);
|
|
51
|
+
constructor(options: InitOptions, config?: ResolvedConfig);
|
|
59
52
|
get options(): InitOptions;
|
|
60
53
|
get config(): ResolvedConfig;
|
|
61
54
|
/** Serialização explícita nunca inclui o secret. */
|
|
@@ -98,7 +91,7 @@ declare class Transaction {
|
|
|
98
91
|
name: string;
|
|
99
92
|
readonly op?: string | undefined;
|
|
100
93
|
private readonly sampled;
|
|
101
|
-
/** Correlaciona a uma execução
|
|
94
|
+
/** Correlaciona a uma execução de task — preenchido automaticamente em ctx.tx */
|
|
102
95
|
private readonly runId?;
|
|
103
96
|
readonly eventId: string;
|
|
104
97
|
readonly spanId: string;
|
|
@@ -108,7 +101,7 @@ declare class Transaction {
|
|
|
108
101
|
private readonly tags;
|
|
109
102
|
private finished;
|
|
110
103
|
constructor(client: Client | undefined, name: string, op?: string | undefined, sampled?: boolean,
|
|
111
|
-
/** Correlaciona a uma execução
|
|
104
|
+
/** Correlaciona a uma execução de task — preenchido automaticamente em ctx.tx */
|
|
112
105
|
runId?: string | undefined);
|
|
113
106
|
createSpan(parentSpanId: string, op?: string, description?: string): Span;
|
|
114
107
|
/** Span direto da transaction. */
|
|
@@ -119,8 +112,8 @@ declare class Transaction {
|
|
|
119
112
|
finish(): void;
|
|
120
113
|
}
|
|
121
114
|
|
|
122
|
-
/** Opções
|
|
123
|
-
interface
|
|
115
|
+
/** Opções de tasks dentro de `init({ tasks: ... })`. Credencial (clientSecret), identidade (instanceId) e debug vêm do init. */
|
|
116
|
+
interface TasksOptions {
|
|
124
117
|
/** Intervalo entre polls sem trabalho. Default: 5_000 (mínimo 1_000) */
|
|
125
118
|
pollIntervalMs?: number;
|
|
126
119
|
/** Runs simultâneas (1..5). Default: 1 (sequencial) */
|
|
@@ -146,17 +139,6 @@ interface ManagerOptions {
|
|
|
146
139
|
*/
|
|
147
140
|
installExitHandlers?: boolean;
|
|
148
141
|
}
|
|
149
|
-
/** Opções resolvidas pelo init unificado e entregues ao ManagerAgent. */
|
|
150
|
-
interface ManagerAgentOptions extends ManagerOptions {
|
|
151
|
-
/** O Client Secret do projeto — o mesmo do Monitor */
|
|
152
|
-
clientSecret: string;
|
|
153
|
-
/** Identidade do agente no dashboard — o instanceId do init */
|
|
154
|
-
instanceId: string;
|
|
155
|
-
/** Loga atividade do SDK no console */
|
|
156
|
-
debug?: boolean;
|
|
157
|
-
/** Client do Monitor compartilhado — usado para enviar a transaction de performance de cada run (ctx.tx) */
|
|
158
|
-
client?: Client;
|
|
159
|
-
}
|
|
160
142
|
interface RunLogger {
|
|
161
143
|
debug(message: string): void;
|
|
162
144
|
info(message: string): void;
|
|
@@ -186,7 +168,7 @@ interface RunContext {
|
|
|
186
168
|
sleep(ms: number): Promise<void>;
|
|
187
169
|
}
|
|
188
170
|
/** O retorno do handler é ignorado — nada além de status/logs/erro é enviado ao servidor. */
|
|
189
|
-
type
|
|
171
|
+
type TaskHandler<P = Record<string, unknown>> = (params: P, ctx: RunContext) => void | Promise<void>;
|
|
190
172
|
|
|
191
173
|
interface HeartbeatOptions {
|
|
192
174
|
/** Intervalo entre batimentos. Default: 30_000 */
|
|
@@ -196,13 +178,13 @@ interface HeartbeatOptions {
|
|
|
196
178
|
metadata?: Record<string, unknown>;
|
|
197
179
|
}
|
|
198
180
|
interface InitOptions {
|
|
199
|
-
/** O Client Secret do projeto (hb_…) — a mesma credencial para
|
|
181
|
+
/** O Client Secret do projeto (hb_…) — a mesma credencial para telemetria e tasks. Copie em Configurações → Projetos. */
|
|
200
182
|
clientSecret: string;
|
|
201
183
|
/** Default: 'production' */
|
|
202
184
|
environment?: string;
|
|
203
185
|
/** Versão do programa, ex.: 'robo-nfe@1.4.2' */
|
|
204
186
|
release?: string;
|
|
205
|
-
/** Identificador único e estável desta instância — a identidade do agente no painel (heartbeat
|
|
187
|
+
/** Identificador único e estável desta instância — a identidade do agente no painel (heartbeat e poll de tasks convergem nele) */
|
|
206
188
|
instanceId: string;
|
|
207
189
|
/** Tags aplicadas a todos os eventos */
|
|
208
190
|
tags?: Record<string, string>;
|
|
@@ -217,10 +199,11 @@ interface InitOptions {
|
|
|
217
199
|
/** Habilita heartbeat periódico (true usa defaults) */
|
|
218
200
|
heartbeat?: boolean | HeartbeatOptions;
|
|
219
201
|
/**
|
|
220
|
-
* Habilita
|
|
221
|
-
* Usa o mesmo clientSecret e o instanceId como identidade.
|
|
202
|
+
* Habilita a execução remota de tarefas sob demanda — o módulo Solicitações do app
|
|
203
|
+
* (true usa defaults). Usa o mesmo clientSecret e o instanceId como identidade.
|
|
204
|
+
* Depois de init(), chame register() e start().
|
|
222
205
|
*/
|
|
223
|
-
|
|
206
|
+
tasks?: boolean | TasksOptions;
|
|
224
207
|
/** Última chance de editar/descartar um evento (retorne null para descartar) */
|
|
225
208
|
beforeSend?: (event: EventPayload) => EventPayload | null;
|
|
226
209
|
/** Loga atividade do SDK no console */
|
|
@@ -247,10 +230,7 @@ interface CheckInOptions {
|
|
|
247
230
|
schedule?: string;
|
|
248
231
|
timezone?: string;
|
|
249
232
|
}
|
|
250
|
-
|
|
251
|
-
schedule?: string;
|
|
252
|
-
timezone?: string;
|
|
253
|
-
}
|
|
233
|
+
type WithMonitorOptions = Pick<CheckInOptions, 'schedule' | 'timezone'>;
|
|
254
234
|
|
|
255
235
|
/** Inicializa o SDK. Chame uma vez, o mais cedo possível no programa. */
|
|
256
236
|
declare function init(options: InitOptions): void;
|
|
@@ -275,100 +255,21 @@ declare function checkIn(options: CheckInOptions): string | undefined;
|
|
|
275
255
|
declare function withMonitor<T>(monitorSlug: string, fn: () => T | Promise<T>, options?: WithMonitorOptions): Promise<T>;
|
|
276
256
|
/** Aguarda o envio de tudo que está na fila (até timeoutMs). */
|
|
277
257
|
declare function flush(timeoutMs?: number): Promise<boolean>;
|
|
278
|
-
/** Registra o handler de uma task
|
|
279
|
-
declare function register<P = Record<string, unknown>>(task: string, handler:
|
|
258
|
+
/** Registra o handler de uma task (o task_slug configurado no formulário do app, em Configurações → Formulários). */
|
|
259
|
+
declare function register<P = Record<string, unknown>>(task: string, handler: TaskHandler<P>): void;
|
|
280
260
|
/**
|
|
281
|
-
* Inicia o polling
|
|
282
|
-
* aguardando trabalho até stop()/close() — o inverso deliberado
|
|
261
|
+
* Inicia o polling de tasks. O timer NÃO é unref'd: o processo fica vivo
|
|
262
|
+
* aguardando trabalho até stop()/close() — o inverso deliberado da telemetria.
|
|
283
263
|
*/
|
|
284
264
|
declare function start(): void;
|
|
285
|
-
/** Para só o
|
|
265
|
+
/** Para só o polling de tasks e aguarda as runs ativas (até timeoutMs). A telemetria continua. */
|
|
286
266
|
declare function stop(timeoutMs?: number): Promise<boolean>;
|
|
287
267
|
/**
|
|
288
|
-
* Encerra tudo: para o
|
|
289
|
-
* flush final do transport. Chame antes do processo terminar.
|
|
268
|
+
* Encerra tudo: para o polling de tasks (aguardando runs em voo), o heartbeat
|
|
269
|
+
* e faz o flush final do transport. Chame antes do processo terminar.
|
|
290
270
|
*/
|
|
291
271
|
declare function close(timeoutMs?: number): Promise<boolean>;
|
|
292
272
|
|
|
293
273
|
declare function scrubSecrets(text: string): string;
|
|
294
274
|
|
|
295
|
-
|
|
296
|
-
* Loop de polling do Manager: busca runs pendentes, executa os handlers registrados
|
|
297
|
-
* e reporta status/logs/result. Ao contrário do Monitor, o timer de polling NÃO é
|
|
298
|
-
* unref'd — um agente iniciado mantém o processo vivo até stop().
|
|
299
|
-
*/
|
|
300
|
-
declare class ManagerAgent {
|
|
301
|
-
private readonly options;
|
|
302
|
-
private readonly registry;
|
|
303
|
-
readonly logger: Logger;
|
|
304
|
-
private readonly api;
|
|
305
|
-
private readonly client;
|
|
306
|
-
private readonly pollIntervalMs;
|
|
307
|
-
private readonly concurrency;
|
|
308
|
-
private readonly instanceId;
|
|
309
|
-
private readonly taskTimeoutMs?;
|
|
310
|
-
private readonly logFlushIntervalMs?;
|
|
311
|
-
private readonly cancelCheckIntervalMs?;
|
|
312
|
-
private state;
|
|
313
|
-
private timer;
|
|
314
|
-
private pollAbort;
|
|
315
|
-
private consecutiveFailures;
|
|
316
|
-
private consecutiveAuthFailures;
|
|
317
|
-
private readonly activeRuns;
|
|
318
|
-
private readonly reporters;
|
|
319
|
-
private uninstallShutdown;
|
|
320
|
-
constructor(options: ManagerAgentOptions, registry: Map<string, ManagerTaskHandler>);
|
|
321
|
-
get activeCount(): number;
|
|
322
|
-
start(): void;
|
|
323
|
-
/** Para o polling e aguarda as runs ativas (até timeoutMs). Retorna true se tudo terminou a tempo. */
|
|
324
|
-
stop(timeoutMs?: number): Promise<boolean>;
|
|
325
|
-
/**
|
|
326
|
-
* Best-effort do exit path: reporta 'failed'/AgentTerminated para as runs ativas
|
|
327
|
-
* antes do processo morrer, fora da fila do reporter e com timeout curto. Runs já
|
|
328
|
-
* canceladas no app (reporter morto) são puladas; erros de rede são engolidos —
|
|
329
|
-
* o sweep server-side é o backstop.
|
|
330
|
-
*/
|
|
331
|
-
reportAgentTerminated(message: string, timeoutMs?: number): Promise<void>;
|
|
332
|
-
/** Timer intencionalmente NÃO unref'd: o agente é a razão do processo existir. */
|
|
333
|
-
private schedule;
|
|
334
|
-
private tick;
|
|
335
|
-
private delayAfterPollError;
|
|
336
|
-
private dispatch;
|
|
337
|
-
private executeRun;
|
|
338
|
-
private invokeWithTimeout;
|
|
339
|
-
}
|
|
340
|
-
|
|
341
|
-
declare class ManagerApiError extends Error {
|
|
342
|
-
readonly status: number;
|
|
343
|
-
constructor(message: string, status: number);
|
|
344
|
-
}
|
|
345
|
-
interface ManagerApiOptions {
|
|
346
|
-
baseUrl: string;
|
|
347
|
-
key: string;
|
|
348
|
-
logger: Logger;
|
|
349
|
-
}
|
|
350
|
-
/** Cliente HTTP do agente — bearer auth, retry com backoff nos updates. */
|
|
351
|
-
declare class ManagerApi {
|
|
352
|
-
private readonly baseUrl;
|
|
353
|
-
private readonly key;
|
|
354
|
-
private readonly logger;
|
|
355
|
-
constructor(options: ManagerApiOptions);
|
|
356
|
-
private headers;
|
|
357
|
-
/** Um request só — o loop de polling é quem decide o backoff entre tentativas. */
|
|
358
|
-
poll(request: ManagerPollRequest, signal?: AbortSignal): Promise<ManagerPollResponse>;
|
|
359
|
-
/** Nunca confia no shape da resposta: runs malformadas são descartadas e o `max` é respeitado. */
|
|
360
|
-
private parsePollResponse;
|
|
361
|
-
/**
|
|
362
|
-
* PATCH de status/logs com retry em falha de rede/5xx/429.
|
|
363
|
-
* 4xx é definitivo e vira ManagerApiError imediato (409 = run cancelada/transição inválida).
|
|
364
|
-
*/
|
|
365
|
-
updateRun(runId: string, update: ManagerRunUpdateRequest): Promise<void>;
|
|
366
|
-
/**
|
|
367
|
-
* Um único PATCH com timeout curto — exit path (o processo está morrendo, o retry
|
|
368
|
-
* ladder do updateRun é proibido aqui). Status HTTP é ignorado: 409/404 significa
|
|
369
|
-
* que a run já foi cancelada/finalizada, o que é aceitável nesse caminho.
|
|
370
|
-
*/
|
|
371
|
-
updateRunOnce(runId: string, update: ManagerRunUpdateRequest, timeoutMs?: number): Promise<void>;
|
|
372
|
-
}
|
|
373
|
-
|
|
374
|
-
export { Breadcrumb, type BreadcrumbInput, type CaptureHint, type CheckInOptions, CheckInPayload, CheckInStatus, Client, DEFAULT_BASE_URL, EventPayload, EventUser, type HeartbeatOptions, HeartbeatPayload, type InitOptions, ManagerAgent, ManagerApi, ManagerApiError, type ManagerOptions, ManagerPollRequest, ManagerPollResponse, ManagerRunUpdateRequest, type ManagerTaskHandler, type ResolvedConfig, type RunContext, Scope, Severity, Span, SpanData, Transaction, TransactionPayload, type WithMonitorOptions, addBreadcrumb, captureException, captureMessage, checkIn, close, flush, getClient, init, register, resolveConfig, scrubSecrets, setContext, setExtra, setTag, setTags, setUser, start, startTransaction, stop, withMonitor, withScope };
|
|
275
|
+
export { Breadcrumb, type BreadcrumbInput, type CaptureHint, type CheckInOptions, CheckInPayload, CheckInStatus, Client, DEFAULT_BASE_URL, EventPayload, EventUser, type HeartbeatOptions, HeartbeatPayload, type InitOptions, type RunContext, Scope, Severity, Span, SpanData, type TaskHandler, type TasksOptions, Transaction, TransactionPayload, type WithMonitorOptions, addBreadcrumb, captureException, captureMessage, checkIn, close, flush, getClient, init, register, scrubSecrets, setContext, setExtra, setTag, setTags, setUser, start, startTransaction, stop, withMonitor, withScope };
|