hobots 1.0.0 → 1.1.0

package/dist/index.d.ts

@@ -1,25 +1,58 @@
 import { Severity, EventPayload, Breadcrumb, EventUser, TransactionPayload, CheckInPayload, HeartbeatPayload, SpanData, CheckInStatus } from './protocol.js';
 export { Envelope, EnvelopeItem, ExceptionData, StackFrame } from './protocol.js';
-import { L as Logger } from './utils-LReLqjzN.js';
+import { RunLogLevel, ManagerPollRequest, ManagerPollResponse, ManagerRunUpdateRequest } from './manager/protocol.js';
+export { ManagerAgentInfo, ManagerRunDescriptor, ManagerRunError, ManagerRunStatus, ManagerRunUpdateResponse, ManagerRunUpdateStatus, RunLogEntry } from './manager/protocol.js';
+
+/** Opções do Manager dentro de `init({ manager: ... })`. DSN, identidade (instanceId) e debug vêm do init. */
+interface ManagerOptions {
+    /** Intervalo entre polls sem trabalho. Default: 5_000 (mínimo 1_000) */
+    pollIntervalMs?: number;
+    /** Runs simultâneas (1..5). Default: 1 (sequencial) */
+    concurrency?: number;
+    /**
+     * Timeout client-side por run. O handler não é morto — a run é reportada como
+     * falha e o slot é liberado. Default: sem timeout (o servidor é o backstop).
+     */
+    taskTimeoutMs?: number;
+    /** Intervalo do flush incremental de logs. Default: 2_000 */
+    logFlushIntervalMs?: number;
+}
+/** Opções resolvidas pelo init unificado e entregues ao ManagerAgent. */
+interface ManagerAgentOptions extends ManagerOptions {
+    /** A DSN única do projeto — a mesma do Monitor */
+    dsn: string;
+    /** Identidade do agente no dashboard — o instanceId do init */
+    instanceId: string;
+    /** Loga atividade do SDK no console */
+    debug?: boolean;
+}
+interface RunContext {
+    runId: string;
+    task: string;
+    /** Log bufferizado — enviado ao servidor em PATCHes incrementais com throttle */
+    log(level: RunLogLevel, message: string): void;
+    /** Dispara em cancelamento (run cancelada no app), timeout ou shutdown — cancelamento cooperativo */
+    signal: AbortSignal;
+}
+/** O retorno do handler é ignorado — nada além de status/logs/erro é enviado ao servidor. */
+type ManagerTaskHandler<P = Record<string, unknown>> = (params: P, ctx: RunContext) => void | Promise<void>;
 
 interface HeartbeatOptions {
     /** Intervalo entre batimentos. Default: 30_000 */
     intervalMs?: number;
-    /** Identificador estável da instância (default: serverName, HOSTNAME ou id aleatório por processo) */
-    instanceId?: string;
-    /** Nome amigável exibido no dashboard */
+    /** Nome amigável exibido no dashboard. Default: o instanceId do init */
     name?: string;
     metadata?: Record<string, unknown>;
 }
 interface InitOptions {
-    /** Ex.: https://<publicKey>@monitor.hobots.app/<projectId> */
+    /** A DSN única do projeto — a mesma para Monitor e Manager. Ex.: https://<secretKey>@app.hobots.app/<projeto> */
     dsn: string;
     /** Default: 'production' */
     environment?: string;
     /** Versão do programa, ex.: 'robo-nfe@1.4.2' */
     release?: string;
-    /** Nome da máquina/instância; também usado como instanceId do heartbeat */
-    serverName?: string;
+    /** Identificador único e estável desta instância — a identidade do agente no painel (heartbeat do Monitor e agente do Manager convergem nele) */
+    instanceId: string;
     /** Tags aplicadas a todos os eventos */
     tags?: Record<string, string>;
     /** Amostragem de eventos de erro (0..1). Default: 1 */
@@ -32,6 +65,11 @@ interface InitOptions {
     captureUnhandled?: boolean;
     /** Habilita heartbeat periódico (true usa defaults) */
     heartbeat?: boolean | HeartbeatOptions;
+    /**
+     * Habilita o agente Manager — execução remota de tarefas sob demanda (true usa defaults).
+     * Usa a mesma DSN e o instanceId como identidade. Depois de init(), chame register() e start().
+     */
+    manager?: boolean | ManagerOptions;
     /** Última chance de editar/descartar um evento (retorne null para descartar) */
     beforeSend?: (event: EventPayload) => EventPayload | null;
     /** Loga atividade do SDK no console */
@@ -49,12 +87,20 @@ interface CaptureHint {
 }
 
 interface ParsedDsn {
-    publicKey: string;
-    projectId: string;
-    /** URL de ingestão derivada: <origin>/api/ingest/<publicKey> */
-    endpoint: string;
+    /** Chave secreta do projeto (enviada como Authorization: Bearer, nunca na URL) */
+    key: string;
+    /** Slug do projeto (informativo — a identidade real vem da chave) */
+    projectSlug: string;
+    origin: string;
+    /** Ingestão do Monitor: <origin>/api/ingest */
+    ingestEndpoint: string;
+    /** API do Manager: <origin>/api/manager */
+    managerBaseUrl: string;
 }
-/** Formato: https://<publicKey>@host[:porta]/<projectId> */
+/**
+ * A DSN única do projeto Hobots — a mesma para Monitor e Manager.
+ * Formato: https://<secretKey>@host[:porta]/<projectSlug>
+ */
 declare function parseDsn(dsn: string): ParsedDsn;
 
 type BreadcrumbInput = Omit<Breadcrumb, 'timestamp'> & {
@@ -82,6 +128,12 @@ declare class Scope {
     clone(): Scope;
 }
 
+interface Logger {
+    debug: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+}
+
 declare class Client {
     readonly options: InitOptions;
     readonly dsn: ParsedDsn;
@@ -181,7 +233,80 @@ declare function checkIn(options: CheckInOptions): string | undefined;
 declare function withMonitor<T>(monitorSlug: string, fn: () => T | Promise<T>, options?: WithMonitorOptions): Promise<T>;
 /** Aguarda o envio de tudo que está na fila (até timeoutMs). */
 declare function flush(timeoutMs?: number): Promise<boolean>;
-/** Flush final + encerra heartbeat e transport. Chame antes do processo terminar. */
+/** Registra o handler de uma task do Manager (o task_slug configurado no formulário do app). */
+declare function register<P = Record<string, unknown>>(task: string, handler: ManagerTaskHandler<P>): void;
+/**
+ * Inicia o polling do Manager. O timer NÃO é unref'd: o processo fica vivo
+ * aguardando trabalho até stop()/close() — o inverso deliberado do Monitor.
+ */
+declare function start(): void;
+/** Para só o Manager: encerra o polling e aguarda as runs ativas (até timeoutMs). A telemetria continua. */
+declare function stop(timeoutMs?: number): Promise<boolean>;
+/**
+ * Encerra tudo: para o Manager (aguardando runs em voo), o heartbeat e faz o
+ * flush final do transport. Chame antes do processo terminar.
+ */
 declare function close(timeoutMs?: number): Promise<boolean>;
 
-export { Breadcrumb, type BreadcrumbInput, type CaptureHint, type CheckInOptions, CheckInPayload, CheckInStatus, Client, EventPayload, EventUser, type HeartbeatOptions, HeartbeatPayload, type InitOptions, type ParsedDsn, Scope, Severity, Span, SpanData, Transaction, TransactionPayload, type WithMonitorOptions, addBreadcrumb, captureException, captureMessage, checkIn, close, flush, getClient, init, parseDsn, setContext, setExtra, setTag, setTags, setUser, startTransaction, withMonitor, withScope };
+/**
+ * Loop de polling do Manager: busca runs pendentes, executa os handlers registrados
+ * e reporta status/logs/result. Ao contrário do Monitor, o timer de polling NÃO é
+ * unref'd — um agente iniciado mantém o processo vivo até stop().
+ */
+declare class ManagerAgent {
+    private readonly options;
+    private readonly registry;
+    readonly logger: Logger;
+    private readonly api;
+    private readonly pollIntervalMs;
+    private readonly concurrency;
+    private readonly instanceId;
+    private readonly taskTimeoutMs?;
+    private readonly logFlushIntervalMs?;
+    private state;
+    private timer;
+    private pollAbort;
+    private consecutiveFailures;
+    private consecutiveAuthFailures;
+    private readonly activeRuns;
+    private readonly reporters;
+    constructor(options: ManagerAgentOptions, registry: Map<string, ManagerTaskHandler>);
+    get activeCount(): number;
+    start(): void;
+    /** Para o polling e aguarda as runs ativas (até timeoutMs). Retorna true se tudo terminou a tempo. */
+    stop(timeoutMs?: number): Promise<boolean>;
+    /** Timer intencionalmente NÃO unref'd: o agente é a razão do processo existir. */
+    private schedule;
+    private tick;
+    private delayAfterPollError;
+    private dispatch;
+    private executeRun;
+    private invokeWithTimeout;
+}
+
+declare class ManagerApiError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+interface ManagerApiOptions {
+    baseUrl: string;
+    key: string;
+    logger: Logger;
+}
+/** Cliente HTTP do agente — bearer auth, retry com backoff nos updates. */
+declare class ManagerApi {
+    private readonly baseUrl;
+    private readonly key;
+    private readonly logger;
+    constructor(options: ManagerApiOptions);
+    private headers;
+    /** Um request só — o loop de polling é quem decide o backoff entre tentativas. */
+    poll(request: ManagerPollRequest, signal?: AbortSignal): Promise<ManagerPollResponse>;
+    /**
+     * PATCH de status/logs com retry em falha de rede/5xx/429.
+     * 4xx é definitivo e vira ManagerApiError imediato (409 = run cancelada/transição inválida).
+     */
+    updateRun(runId: string, update: ManagerRunUpdateRequest): Promise<void>;
+}
+
+export { Breadcrumb, type BreadcrumbInput, type CaptureHint, type CheckInOptions, CheckInPayload, CheckInStatus, Client, EventPayload, EventUser, type HeartbeatOptions, HeartbeatPayload, type InitOptions, ManagerAgent, ManagerApi, ManagerApiError, type ManagerOptions, ManagerPollRequest, ManagerPollResponse, ManagerRunUpdateRequest, type ManagerTaskHandler, type ParsedDsn, type RunContext, RunLogLevel, Scope, Severity, Span, SpanData, Transaction, TransactionPayload, type WithMonitorOptions, addBreadcrumb, captureException, captureMessage, checkIn, close, flush, getClient, init, parseDsn, register, setContext, setExtra, setTag, setTags, setUser, start, startTransaction, stop, withMonitor, withScope };