hobots 1.5.1 → 1.7.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 +46 -74
- package/dist/index.cjs +267 -144
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +31 -123
- package/dist/index.d.ts +31 -123
- package/dist/index.js +267 -144
- 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 +8 -8
- package/docs/api-reference.md +40 -44
- package/docs/concepts.md +67 -52
- package/docs/getting-started.md +17 -17
- package/docs/monitor.md +8 -8
- package/docs/protocol.md +21 -25
- package/docs/{manager.md → tasks.md} +18 -18
- package/package.json +3 -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;
|
|
@@ -52,11 +45,14 @@ interface Logger {
|
|
|
52
45
|
}
|
|
53
46
|
|
|
54
47
|
declare class Client {
|
|
55
|
-
|
|
56
|
-
readonly config: ResolvedConfig;
|
|
48
|
+
#private;
|
|
57
49
|
readonly logger: Logger;
|
|
58
50
|
private readonly transport;
|
|
59
|
-
constructor(options: InitOptions);
|
|
51
|
+
constructor(options: InitOptions, config?: ResolvedConfig);
|
|
52
|
+
get options(): InitOptions;
|
|
53
|
+
get config(): ResolvedConfig;
|
|
54
|
+
/** Serialização explícita nunca inclui o secret. */
|
|
55
|
+
toJSON(): Record<string, unknown>;
|
|
60
56
|
captureException(error: unknown, hint: CaptureHint | undefined, scope: Scope): string;
|
|
61
57
|
captureMessage(message: string, level: Severity, hint: CaptureHint | undefined, scope: Scope): string;
|
|
62
58
|
captureEvent(event: EventPayload, hint: CaptureHint | undefined, scope: Scope): string;
|
|
@@ -95,7 +91,7 @@ declare class Transaction {
|
|
|
95
91
|
name: string;
|
|
96
92
|
readonly op?: string | undefined;
|
|
97
93
|
private readonly sampled;
|
|
98
|
-
/** Correlaciona a uma execução
|
|
94
|
+
/** Correlaciona a uma execução de task — preenchido automaticamente em ctx.tx */
|
|
99
95
|
private readonly runId?;
|
|
100
96
|
readonly eventId: string;
|
|
101
97
|
readonly spanId: string;
|
|
@@ -105,7 +101,7 @@ declare class Transaction {
|
|
|
105
101
|
private readonly tags;
|
|
106
102
|
private finished;
|
|
107
103
|
constructor(client: Client | undefined, name: string, op?: string | undefined, sampled?: boolean,
|
|
108
|
-
/** Correlaciona a uma execução
|
|
104
|
+
/** Correlaciona a uma execução de task — preenchido automaticamente em ctx.tx */
|
|
109
105
|
runId?: string | undefined);
|
|
110
106
|
createSpan(parentSpanId: string, op?: string, description?: string): Span;
|
|
111
107
|
/** Span direto da transaction. */
|
|
@@ -116,8 +112,8 @@ declare class Transaction {
|
|
|
116
112
|
finish(): void;
|
|
117
113
|
}
|
|
118
114
|
|
|
119
|
-
/** Opções
|
|
120
|
-
interface
|
|
115
|
+
/** Opções de tasks dentro de `init({ tasks: ... })`. Credencial (clientSecret), identidade (instanceId) e debug vêm do init. */
|
|
116
|
+
interface TasksOptions {
|
|
121
117
|
/** Intervalo entre polls sem trabalho. Default: 5_000 (mínimo 1_000) */
|
|
122
118
|
pollIntervalMs?: number;
|
|
123
119
|
/** Runs simultâneas (1..5). Default: 1 (sequencial) */
|
|
@@ -143,17 +139,6 @@ interface ManagerOptions {
|
|
|
143
139
|
*/
|
|
144
140
|
installExitHandlers?: boolean;
|
|
145
141
|
}
|
|
146
|
-
/** Opções resolvidas pelo init unificado e entregues ao ManagerAgent. */
|
|
147
|
-
interface ManagerAgentOptions extends ManagerOptions {
|
|
148
|
-
/** O Client Secret do projeto — o mesmo do Monitor */
|
|
149
|
-
clientSecret: string;
|
|
150
|
-
/** Identidade do agente no dashboard — o instanceId do init */
|
|
151
|
-
instanceId: string;
|
|
152
|
-
/** Loga atividade do SDK no console */
|
|
153
|
-
debug?: boolean;
|
|
154
|
-
/** Client do Monitor compartilhado — usado para enviar a transaction de performance de cada run (ctx.tx) */
|
|
155
|
-
client?: Client;
|
|
156
|
-
}
|
|
157
142
|
interface RunLogger {
|
|
158
143
|
debug(message: string): void;
|
|
159
144
|
info(message: string): void;
|
|
@@ -183,7 +168,7 @@ interface RunContext {
|
|
|
183
168
|
sleep(ms: number): Promise<void>;
|
|
184
169
|
}
|
|
185
170
|
/** O retorno do handler é ignorado — nada além de status/logs/erro é enviado ao servidor. */
|
|
186
|
-
type
|
|
171
|
+
type TaskHandler<P = Record<string, unknown>> = (params: P, ctx: RunContext) => void | Promise<void>;
|
|
187
172
|
|
|
188
173
|
interface HeartbeatOptions {
|
|
189
174
|
/** Intervalo entre batimentos. Default: 30_000 */
|
|
@@ -193,13 +178,13 @@ interface HeartbeatOptions {
|
|
|
193
178
|
metadata?: Record<string, unknown>;
|
|
194
179
|
}
|
|
195
180
|
interface InitOptions {
|
|
196
|
-
/** 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. */
|
|
197
182
|
clientSecret: string;
|
|
198
183
|
/** Default: 'production' */
|
|
199
184
|
environment?: string;
|
|
200
185
|
/** Versão do programa, ex.: 'robo-nfe@1.4.2' */
|
|
201
186
|
release?: string;
|
|
202
|
-
/** 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) */
|
|
203
188
|
instanceId: string;
|
|
204
189
|
/** Tags aplicadas a todos os eventos */
|
|
205
190
|
tags?: Record<string, string>;
|
|
@@ -214,10 +199,11 @@ interface InitOptions {
|
|
|
214
199
|
/** Habilita heartbeat periódico (true usa defaults) */
|
|
215
200
|
heartbeat?: boolean | HeartbeatOptions;
|
|
216
201
|
/**
|
|
217
|
-
* Habilita
|
|
218
|
-
* 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().
|
|
219
205
|
*/
|
|
220
|
-
|
|
206
|
+
tasks?: boolean | TasksOptions;
|
|
221
207
|
/** Última chance de editar/descartar um evento (retorne null para descartar) */
|
|
222
208
|
beforeSend?: (event: EventPayload) => EventPayload | null;
|
|
223
209
|
/** Loga atividade do SDK no console */
|
|
@@ -244,10 +230,7 @@ interface CheckInOptions {
|
|
|
244
230
|
schedule?: string;
|
|
245
231
|
timezone?: string;
|
|
246
232
|
}
|
|
247
|
-
|
|
248
|
-
schedule?: string;
|
|
249
|
-
timezone?: string;
|
|
250
|
-
}
|
|
233
|
+
type WithMonitorOptions = Pick<CheckInOptions, 'schedule' | 'timezone'>;
|
|
251
234
|
|
|
252
235
|
/** Inicializa o SDK. Chame uma vez, o mais cedo possível no programa. */
|
|
253
236
|
declare function init(options: InitOptions): void;
|
|
@@ -272,96 +255,21 @@ declare function checkIn(options: CheckInOptions): string | undefined;
|
|
|
272
255
|
declare function withMonitor<T>(monitorSlug: string, fn: () => T | Promise<T>, options?: WithMonitorOptions): Promise<T>;
|
|
273
256
|
/** Aguarda o envio de tudo que está na fila (até timeoutMs). */
|
|
274
257
|
declare function flush(timeoutMs?: number): Promise<boolean>;
|
|
275
|
-
/** Registra o handler de uma task
|
|
276
|
-
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;
|
|
277
260
|
/**
|
|
278
|
-
* Inicia o polling
|
|
279
|
-
* 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.
|
|
280
263
|
*/
|
|
281
264
|
declare function start(): void;
|
|
282
|
-
/** Para só o
|
|
265
|
+
/** Para só o polling de tasks e aguarda as runs ativas (até timeoutMs). A telemetria continua. */
|
|
283
266
|
declare function stop(timeoutMs?: number): Promise<boolean>;
|
|
284
267
|
/**
|
|
285
|
-
* Encerra tudo: para o
|
|
286
|
-
* 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.
|
|
287
270
|
*/
|
|
288
271
|
declare function close(timeoutMs?: number): Promise<boolean>;
|
|
289
272
|
|
|
290
|
-
|
|
291
|
-
* Loop de polling do Manager: busca runs pendentes, executa os handlers registrados
|
|
292
|
-
* e reporta status/logs/result. Ao contrário do Monitor, o timer de polling NÃO é
|
|
293
|
-
* unref'd — um agente iniciado mantém o processo vivo até stop().
|
|
294
|
-
*/
|
|
295
|
-
declare class ManagerAgent {
|
|
296
|
-
private readonly options;
|
|
297
|
-
private readonly registry;
|
|
298
|
-
readonly logger: Logger;
|
|
299
|
-
private readonly api;
|
|
300
|
-
private readonly client;
|
|
301
|
-
private readonly pollIntervalMs;
|
|
302
|
-
private readonly concurrency;
|
|
303
|
-
private readonly instanceId;
|
|
304
|
-
private readonly taskTimeoutMs?;
|
|
305
|
-
private readonly logFlushIntervalMs?;
|
|
306
|
-
private readonly cancelCheckIntervalMs?;
|
|
307
|
-
private state;
|
|
308
|
-
private timer;
|
|
309
|
-
private pollAbort;
|
|
310
|
-
private consecutiveFailures;
|
|
311
|
-
private consecutiveAuthFailures;
|
|
312
|
-
private readonly activeRuns;
|
|
313
|
-
private readonly reporters;
|
|
314
|
-
private uninstallShutdown;
|
|
315
|
-
constructor(options: ManagerAgentOptions, registry: Map<string, ManagerTaskHandler>);
|
|
316
|
-
get activeCount(): number;
|
|
317
|
-
start(): void;
|
|
318
|
-
/** Para o polling e aguarda as runs ativas (até timeoutMs). Retorna true se tudo terminou a tempo. */
|
|
319
|
-
stop(timeoutMs?: number): Promise<boolean>;
|
|
320
|
-
/**
|
|
321
|
-
* Best-effort do exit path: reporta 'failed'/AgentTerminated para as runs ativas
|
|
322
|
-
* antes do processo morrer, fora da fila do reporter e com timeout curto. Runs já
|
|
323
|
-
* canceladas no app (reporter morto) são puladas; erros de rede são engolidos —
|
|
324
|
-
* o sweep server-side é o backstop.
|
|
325
|
-
*/
|
|
326
|
-
reportAgentTerminated(message: string, timeoutMs?: number): Promise<void>;
|
|
327
|
-
/** Timer intencionalmente NÃO unref'd: o agente é a razão do processo existir. */
|
|
328
|
-
private schedule;
|
|
329
|
-
private tick;
|
|
330
|
-
private delayAfterPollError;
|
|
331
|
-
private dispatch;
|
|
332
|
-
private executeRun;
|
|
333
|
-
private invokeWithTimeout;
|
|
334
|
-
}
|
|
335
|
-
|
|
336
|
-
declare class ManagerApiError extends Error {
|
|
337
|
-
readonly status: number;
|
|
338
|
-
constructor(message: string, status: number);
|
|
339
|
-
}
|
|
340
|
-
interface ManagerApiOptions {
|
|
341
|
-
baseUrl: string;
|
|
342
|
-
key: string;
|
|
343
|
-
logger: Logger;
|
|
344
|
-
}
|
|
345
|
-
/** Cliente HTTP do agente — bearer auth, retry com backoff nos updates. */
|
|
346
|
-
declare class ManagerApi {
|
|
347
|
-
private readonly baseUrl;
|
|
348
|
-
private readonly key;
|
|
349
|
-
private readonly logger;
|
|
350
|
-
constructor(options: ManagerApiOptions);
|
|
351
|
-
private headers;
|
|
352
|
-
/** Um request só — o loop de polling é quem decide o backoff entre tentativas. */
|
|
353
|
-
poll(request: ManagerPollRequest, signal?: AbortSignal): Promise<ManagerPollResponse>;
|
|
354
|
-
/**
|
|
355
|
-
* PATCH de status/logs com retry em falha de rede/5xx/429.
|
|
356
|
-
* 4xx é definitivo e vira ManagerApiError imediato (409 = run cancelada/transição inválida).
|
|
357
|
-
*/
|
|
358
|
-
updateRun(runId: string, update: ManagerRunUpdateRequest): Promise<void>;
|
|
359
|
-
/**
|
|
360
|
-
* Um único PATCH com timeout curto — exit path (o processo está morrendo, o retry
|
|
361
|
-
* ladder do updateRun é proibido aqui). Status HTTP é ignorado: 409/404 significa
|
|
362
|
-
* que a run já foi cancelada/finalizada, o que é aceitável nesse caminho.
|
|
363
|
-
*/
|
|
364
|
-
updateRunOnce(runId: string, update: ManagerRunUpdateRequest, timeoutMs?: number): Promise<void>;
|
|
365
|
-
}
|
|
273
|
+
declare function scrubSecrets(text: string): string;
|
|
366
274
|
|
|
367
|
-
export { Breadcrumb, type BreadcrumbInput, type CaptureHint, type CheckInOptions, CheckInPayload, CheckInStatus, Client, DEFAULT_BASE_URL, EventPayload, EventUser, type HeartbeatOptions, HeartbeatPayload, type InitOptions,
|
|
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;
|
|
@@ -52,11 +45,14 @@ interface Logger {
|
|
|
52
45
|
}
|
|
53
46
|
|
|
54
47
|
declare class Client {
|
|
55
|
-
|
|
56
|
-
readonly config: ResolvedConfig;
|
|
48
|
+
#private;
|
|
57
49
|
readonly logger: Logger;
|
|
58
50
|
private readonly transport;
|
|
59
|
-
constructor(options: InitOptions);
|
|
51
|
+
constructor(options: InitOptions, config?: ResolvedConfig);
|
|
52
|
+
get options(): InitOptions;
|
|
53
|
+
get config(): ResolvedConfig;
|
|
54
|
+
/** Serialização explícita nunca inclui o secret. */
|
|
55
|
+
toJSON(): Record<string, unknown>;
|
|
60
56
|
captureException(error: unknown, hint: CaptureHint | undefined, scope: Scope): string;
|
|
61
57
|
captureMessage(message: string, level: Severity, hint: CaptureHint | undefined, scope: Scope): string;
|
|
62
58
|
captureEvent(event: EventPayload, hint: CaptureHint | undefined, scope: Scope): string;
|
|
@@ -95,7 +91,7 @@ declare class Transaction {
|
|
|
95
91
|
name: string;
|
|
96
92
|
readonly op?: string | undefined;
|
|
97
93
|
private readonly sampled;
|
|
98
|
-
/** Correlaciona a uma execução
|
|
94
|
+
/** Correlaciona a uma execução de task — preenchido automaticamente em ctx.tx */
|
|
99
95
|
private readonly runId?;
|
|
100
96
|
readonly eventId: string;
|
|
101
97
|
readonly spanId: string;
|
|
@@ -105,7 +101,7 @@ declare class Transaction {
|
|
|
105
101
|
private readonly tags;
|
|
106
102
|
private finished;
|
|
107
103
|
constructor(client: Client | undefined, name: string, op?: string | undefined, sampled?: boolean,
|
|
108
|
-
/** Correlaciona a uma execução
|
|
104
|
+
/** Correlaciona a uma execução de task — preenchido automaticamente em ctx.tx */
|
|
109
105
|
runId?: string | undefined);
|
|
110
106
|
createSpan(parentSpanId: string, op?: string, description?: string): Span;
|
|
111
107
|
/** Span direto da transaction. */
|
|
@@ -116,8 +112,8 @@ declare class Transaction {
|
|
|
116
112
|
finish(): void;
|
|
117
113
|
}
|
|
118
114
|
|
|
119
|
-
/** Opções
|
|
120
|
-
interface
|
|
115
|
+
/** Opções de tasks dentro de `init({ tasks: ... })`. Credencial (clientSecret), identidade (instanceId) e debug vêm do init. */
|
|
116
|
+
interface TasksOptions {
|
|
121
117
|
/** Intervalo entre polls sem trabalho. Default: 5_000 (mínimo 1_000) */
|
|
122
118
|
pollIntervalMs?: number;
|
|
123
119
|
/** Runs simultâneas (1..5). Default: 1 (sequencial) */
|
|
@@ -143,17 +139,6 @@ interface ManagerOptions {
|
|
|
143
139
|
*/
|
|
144
140
|
installExitHandlers?: boolean;
|
|
145
141
|
}
|
|
146
|
-
/** Opções resolvidas pelo init unificado e entregues ao ManagerAgent. */
|
|
147
|
-
interface ManagerAgentOptions extends ManagerOptions {
|
|
148
|
-
/** O Client Secret do projeto — o mesmo do Monitor */
|
|
149
|
-
clientSecret: string;
|
|
150
|
-
/** Identidade do agente no dashboard — o instanceId do init */
|
|
151
|
-
instanceId: string;
|
|
152
|
-
/** Loga atividade do SDK no console */
|
|
153
|
-
debug?: boolean;
|
|
154
|
-
/** Client do Monitor compartilhado — usado para enviar a transaction de performance de cada run (ctx.tx) */
|
|
155
|
-
client?: Client;
|
|
156
|
-
}
|
|
157
142
|
interface RunLogger {
|
|
158
143
|
debug(message: string): void;
|
|
159
144
|
info(message: string): void;
|
|
@@ -183,7 +168,7 @@ interface RunContext {
|
|
|
183
168
|
sleep(ms: number): Promise<void>;
|
|
184
169
|
}
|
|
185
170
|
/** O retorno do handler é ignorado — nada além de status/logs/erro é enviado ao servidor. */
|
|
186
|
-
type
|
|
171
|
+
type TaskHandler<P = Record<string, unknown>> = (params: P, ctx: RunContext) => void | Promise<void>;
|
|
187
172
|
|
|
188
173
|
interface HeartbeatOptions {
|
|
189
174
|
/** Intervalo entre batimentos. Default: 30_000 */
|
|
@@ -193,13 +178,13 @@ interface HeartbeatOptions {
|
|
|
193
178
|
metadata?: Record<string, unknown>;
|
|
194
179
|
}
|
|
195
180
|
interface InitOptions {
|
|
196
|
-
/** 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. */
|
|
197
182
|
clientSecret: string;
|
|
198
183
|
/** Default: 'production' */
|
|
199
184
|
environment?: string;
|
|
200
185
|
/** Versão do programa, ex.: 'robo-nfe@1.4.2' */
|
|
201
186
|
release?: string;
|
|
202
|
-
/** 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) */
|
|
203
188
|
instanceId: string;
|
|
204
189
|
/** Tags aplicadas a todos os eventos */
|
|
205
190
|
tags?: Record<string, string>;
|
|
@@ -214,10 +199,11 @@ interface InitOptions {
|
|
|
214
199
|
/** Habilita heartbeat periódico (true usa defaults) */
|
|
215
200
|
heartbeat?: boolean | HeartbeatOptions;
|
|
216
201
|
/**
|
|
217
|
-
* Habilita
|
|
218
|
-
* 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().
|
|
219
205
|
*/
|
|
220
|
-
|
|
206
|
+
tasks?: boolean | TasksOptions;
|
|
221
207
|
/** Última chance de editar/descartar um evento (retorne null para descartar) */
|
|
222
208
|
beforeSend?: (event: EventPayload) => EventPayload | null;
|
|
223
209
|
/** Loga atividade do SDK no console */
|
|
@@ -244,10 +230,7 @@ interface CheckInOptions {
|
|
|
244
230
|
schedule?: string;
|
|
245
231
|
timezone?: string;
|
|
246
232
|
}
|
|
247
|
-
|
|
248
|
-
schedule?: string;
|
|
249
|
-
timezone?: string;
|
|
250
|
-
}
|
|
233
|
+
type WithMonitorOptions = Pick<CheckInOptions, 'schedule' | 'timezone'>;
|
|
251
234
|
|
|
252
235
|
/** Inicializa o SDK. Chame uma vez, o mais cedo possível no programa. */
|
|
253
236
|
declare function init(options: InitOptions): void;
|
|
@@ -272,96 +255,21 @@ declare function checkIn(options: CheckInOptions): string | undefined;
|
|
|
272
255
|
declare function withMonitor<T>(monitorSlug: string, fn: () => T | Promise<T>, options?: WithMonitorOptions): Promise<T>;
|
|
273
256
|
/** Aguarda o envio de tudo que está na fila (até timeoutMs). */
|
|
274
257
|
declare function flush(timeoutMs?: number): Promise<boolean>;
|
|
275
|
-
/** Registra o handler de uma task
|
|
276
|
-
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;
|
|
277
260
|
/**
|
|
278
|
-
* Inicia o polling
|
|
279
|
-
* 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.
|
|
280
263
|
*/
|
|
281
264
|
declare function start(): void;
|
|
282
|
-
/** Para só o
|
|
265
|
+
/** Para só o polling de tasks e aguarda as runs ativas (até timeoutMs). A telemetria continua. */
|
|
283
266
|
declare function stop(timeoutMs?: number): Promise<boolean>;
|
|
284
267
|
/**
|
|
285
|
-
* Encerra tudo: para o
|
|
286
|
-
* 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.
|
|
287
270
|
*/
|
|
288
271
|
declare function close(timeoutMs?: number): Promise<boolean>;
|
|
289
272
|
|
|
290
|
-
|
|
291
|
-
* Loop de polling do Manager: busca runs pendentes, executa os handlers registrados
|
|
292
|
-
* e reporta status/logs/result. Ao contrário do Monitor, o timer de polling NÃO é
|
|
293
|
-
* unref'd — um agente iniciado mantém o processo vivo até stop().
|
|
294
|
-
*/
|
|
295
|
-
declare class ManagerAgent {
|
|
296
|
-
private readonly options;
|
|
297
|
-
private readonly registry;
|
|
298
|
-
readonly logger: Logger;
|
|
299
|
-
private readonly api;
|
|
300
|
-
private readonly client;
|
|
301
|
-
private readonly pollIntervalMs;
|
|
302
|
-
private readonly concurrency;
|
|
303
|
-
private readonly instanceId;
|
|
304
|
-
private readonly taskTimeoutMs?;
|
|
305
|
-
private readonly logFlushIntervalMs?;
|
|
306
|
-
private readonly cancelCheckIntervalMs?;
|
|
307
|
-
private state;
|
|
308
|
-
private timer;
|
|
309
|
-
private pollAbort;
|
|
310
|
-
private consecutiveFailures;
|
|
311
|
-
private consecutiveAuthFailures;
|
|
312
|
-
private readonly activeRuns;
|
|
313
|
-
private readonly reporters;
|
|
314
|
-
private uninstallShutdown;
|
|
315
|
-
constructor(options: ManagerAgentOptions, registry: Map<string, ManagerTaskHandler>);
|
|
316
|
-
get activeCount(): number;
|
|
317
|
-
start(): void;
|
|
318
|
-
/** Para o polling e aguarda as runs ativas (até timeoutMs). Retorna true se tudo terminou a tempo. */
|
|
319
|
-
stop(timeoutMs?: number): Promise<boolean>;
|
|
320
|
-
/**
|
|
321
|
-
* Best-effort do exit path: reporta 'failed'/AgentTerminated para as runs ativas
|
|
322
|
-
* antes do processo morrer, fora da fila do reporter e com timeout curto. Runs já
|
|
323
|
-
* canceladas no app (reporter morto) são puladas; erros de rede são engolidos —
|
|
324
|
-
* o sweep server-side é o backstop.
|
|
325
|
-
*/
|
|
326
|
-
reportAgentTerminated(message: string, timeoutMs?: number): Promise<void>;
|
|
327
|
-
/** Timer intencionalmente NÃO unref'd: o agente é a razão do processo existir. */
|
|
328
|
-
private schedule;
|
|
329
|
-
private tick;
|
|
330
|
-
private delayAfterPollError;
|
|
331
|
-
private dispatch;
|
|
332
|
-
private executeRun;
|
|
333
|
-
private invokeWithTimeout;
|
|
334
|
-
}
|
|
335
|
-
|
|
336
|
-
declare class ManagerApiError extends Error {
|
|
337
|
-
readonly status: number;
|
|
338
|
-
constructor(message: string, status: number);
|
|
339
|
-
}
|
|
340
|
-
interface ManagerApiOptions {
|
|
341
|
-
baseUrl: string;
|
|
342
|
-
key: string;
|
|
343
|
-
logger: Logger;
|
|
344
|
-
}
|
|
345
|
-
/** Cliente HTTP do agente — bearer auth, retry com backoff nos updates. */
|
|
346
|
-
declare class ManagerApi {
|
|
347
|
-
private readonly baseUrl;
|
|
348
|
-
private readonly key;
|
|
349
|
-
private readonly logger;
|
|
350
|
-
constructor(options: ManagerApiOptions);
|
|
351
|
-
private headers;
|
|
352
|
-
/** Um request só — o loop de polling é quem decide o backoff entre tentativas. */
|
|
353
|
-
poll(request: ManagerPollRequest, signal?: AbortSignal): Promise<ManagerPollResponse>;
|
|
354
|
-
/**
|
|
355
|
-
* PATCH de status/logs com retry em falha de rede/5xx/429.
|
|
356
|
-
* 4xx é definitivo e vira ManagerApiError imediato (409 = run cancelada/transição inválida).
|
|
357
|
-
*/
|
|
358
|
-
updateRun(runId: string, update: ManagerRunUpdateRequest): Promise<void>;
|
|
359
|
-
/**
|
|
360
|
-
* Um único PATCH com timeout curto — exit path (o processo está morrendo, o retry
|
|
361
|
-
* ladder do updateRun é proibido aqui). Status HTTP é ignorado: 409/404 significa
|
|
362
|
-
* que a run já foi cancelada/finalizada, o que é aceitável nesse caminho.
|
|
363
|
-
*/
|
|
364
|
-
updateRunOnce(runId: string, update: ManagerRunUpdateRequest, timeoutMs?: number): Promise<void>;
|
|
365
|
-
}
|
|
273
|
+
declare function scrubSecrets(text: string): string;
|
|
366
274
|
|
|
367
|
-
export { Breadcrumb, type BreadcrumbInput, type CaptureHint, type CheckInOptions, CheckInPayload, CheckInStatus, Client, DEFAULT_BASE_URL, EventPayload, EventUser, type HeartbeatOptions, HeartbeatPayload, type InitOptions,
|
|
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 };
|