hobots 0.3.1 → 1.1.0

package/dist/index.d.ts

@@ -0,0 +1,312 @@
+import { Severity, EventPayload, Breadcrumb, EventUser, TransactionPayload, CheckInPayload, HeartbeatPayload, SpanData, CheckInStatus } from './protocol.js';
+export { Envelope, EnvelopeItem, ExceptionData, StackFrame } from './protocol.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;
+    /** Nome amigável exibido no dashboard. Default: o instanceId do init */
+    name?: string;
+    metadata?: Record<string, unknown>;
+}
+interface InitOptions {
+    /** 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;
+    /** 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 */
+    sampleRate?: number;
+    /** Amostragem de transactions (0..1). Default: 1 */
+    tracesSampleRate?: number;
+    /** Default: 100 */
+    maxBreadcrumbs?: number;
+    /** Registra handlers globais de erro (uncaughtException etc.). Default: true */
+    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 */
+    debug?: boolean;
+    /** Intervalo do flush automático do transport. Default: 2_000 */
+    flushIntervalMs?: number;
+    /** Itens por envelope antes de flush imediato. Default: 10 */
+    maxBatchSize?: number;
+}
+interface CaptureHint {
+    level?: Severity;
+    tags?: Record<string, string>;
+    extra?: Record<string, unknown>;
+    fingerprint?: string[];
+}
+
+interface ParsedDsn {
+    /** 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;
+}
+/**
+ * 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'> & {
+    timestamp?: string;
+};
+/** Estado contextual anexado aos eventos: tags, usuário, contexts, extras e breadcrumbs. */
+declare class Scope {
+    tags: Record<string, string>;
+    user?: EventUser;
+    contexts: Record<string, Record<string, unknown>>;
+    extra: Record<string, unknown>;
+    level?: Severity;
+    fingerprint?: string[];
+    breadcrumbs: Breadcrumb[];
+    setTag(key: string, value: string): this;
+    setTags(tags: Record<string, string>): this;
+    setUser(user: EventUser | null): this;
+    setContext(name: string, context: Record<string, unknown> | null): this;
+    setExtra(key: string, value: unknown): this;
+    setExtras(extras: Record<string, unknown>): this;
+    setLevel(level: Severity): this;
+    setFingerprint(fingerprint: string[]): this;
+    addBreadcrumb(crumb: BreadcrumbInput, maxBreadcrumbs: number): this;
+    clearBreadcrumbs(): this;
+    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;
+    readonly logger: Logger;
+    private readonly transport;
+    constructor(options: InitOptions);
+    captureException(error: unknown, hint: CaptureHint | undefined, scope: Scope): string;
+    captureMessage(message: string, level: Severity, hint: CaptureHint | undefined, scope: Scope): string;
+    captureEvent(event: EventPayload, hint: CaptureHint | undefined, scope: Scope): string;
+    private prepareEvent;
+    sendTransaction(payload: TransactionPayload): void;
+    sendCheckIn(payload: CheckInPayload): void;
+    sendHeartbeat(payload: HeartbeatPayload): void;
+    flush(timeoutMs?: number): Promise<boolean>;
+    close(timeoutMs?: number): Promise<boolean>;
+}
+
+declare class Span {
+    private readonly transaction;
+    readonly parentSpanId: string;
+    readonly op?: string | undefined;
+    readonly description?: string | undefined;
+    readonly spanId: string;
+    readonly startTimestamp: string;
+    status: string;
+    endTimestamp?: string;
+    data?: Record<string, unknown>;
+    constructor(transaction: Transaction, parentSpanId: string, op?: string | undefined, description?: string | undefined);
+    setStatus(status: string): this;
+    setData(key: string, value: unknown): this;
+    /** Span aninhado (filho deste span). */
+    startChild(op?: string, description?: string): Span;
+    finish(): void;
+    toJSON(): SpanData;
+}
+/**
+ * Uma unidade de trabalho nomeada (ex.: uma execução de rotina, uma sincronização).
+ * Spans filhos medem as etapas internas (chamadas HTTP, queries, etc.).
+ */
+declare class Transaction {
+    private readonly client;
+    name: string;
+    readonly op?: string | undefined;
+    private readonly sampled;
+    readonly eventId: string;
+    readonly spanId: string;
+    readonly startTimestamp: string;
+    status: string;
+    private readonly spans;
+    private readonly tags;
+    private finished;
+    constructor(client: Client | undefined, name: string, op?: string | undefined, sampled?: boolean);
+    createSpan(parentSpanId: string, op?: string, description?: string): Span;
+    /** Span direto da transaction. */
+    startChild(op?: string, description?: string): Span;
+    setTag(key: string, value: string): this;
+    setStatus(status: string): this;
+    setName(name: string): this;
+    finish(): void;
+}
+
+interface CheckInOptions {
+    monitorSlug: string;
+    status: CheckInStatus;
+    /** Reutilize o id retornado pelo check-in 'in_progress' para fechar a execução */
+    checkInId?: string;
+    durationMs?: number;
+    /** Expressão cron — cria/atualiza o monitor automaticamente no servidor */
+    schedule?: string;
+    timezone?: string;
+}
+interface WithMonitorOptions {
+    schedule?: string;
+    timezone?: string;
+}
+
+/** Inicializa o SDK. Chame uma vez, o mais cedo possível no programa. */
+declare function init(options: InitOptions): void;
+declare function getClient(): Client | undefined;
+/** Captura uma exceção e retorna o event_id (undefined se o SDK não foi inicializado). */
+declare function captureException(error: unknown, hint?: CaptureHint): string | undefined;
+declare function captureMessage(message: string, level?: Severity, hint?: CaptureHint): string | undefined;
+/** Registra um breadcrumb — anexado aos próximos eventos como trilha do que aconteceu antes. */
+declare function addBreadcrumb(crumb: BreadcrumbInput): void;
+declare function setTag(key: string, value: string): void;
+declare function setTags(tags: Record<string, string>): void;
+declare function setUser(user: EventUser | null): void;
+declare function setContext(name: string, context: Record<string, unknown> | null): void;
+declare function setExtra(key: string, value: unknown): void;
+/** Executa o callback com uma cópia isolada do scope (alterações não vazam para fora). */
+declare function withScope<T>(callback: (scope: Scope) => T): T;
+/** Inicia uma transaction de performance. Chame .finish() para enviá-la. */
+declare function startTransaction(name: string, op?: string): Transaction;
+/** Check-in manual de um monitor cron. Retorna o check_in_id para fechar a execução depois. */
+declare function checkIn(options: CheckInOptions): string | undefined;
+/** Envolve um job monitorado: envia in_progress → ok/error com duração e captura a exceção em caso de falha. */
+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>;
+/** 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>;
+
+/**
+ * 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 };