@victor-studio/monitor 0.1.0 → 0.4.0

package/dist/index.d.cts

@@ -1,72 +1,177 @@
-interface MonitorEvent {
-    type: 'heartbeat' | 'request' | 'vital';
-    data: Record<string, unknown>;
-    timestamp: string;
+interface HeartbeatData {
+    status: 'online' | 'offline';
+    latencyMs: number;
 }
-interface TransportConfig {
-    endpoint: string;
-    apiKey: string;
+interface RequestData {
+    method: string;
+    route: string;
+    statusCode: number;
+    responseTimeMs: number;
+    userAgent?: string;
+    region?: string;
 }
-
-declare class Collector {
-    private buffer;
-    private timer;
-    private config;
-    private flushInterval;
-    constructor(config: TransportConfig, flushInterval?: number);
-    start(): void;
-    stop(): void;
-    push(event: Omit<MonitorEvent, 'timestamp'>): void;
-    private flush;
+interface VitalData {
+    name: 'LCP' | 'INP' | 'CLS' | 'FCP' | 'TTFB';
+    value: number;
+    rating: 'good' | 'needs-improvement' | 'poor';
+    page?: string;
+    deviceType?: string;
+    browser?: string;
+}
+interface ErrorData {
+    type: 'unhandled' | 'caught' | 'promise';
+    message: string;
+    stack?: string;
+    groupingKey: string;
+    route?: string;
+    method?: string;
+    statusCode?: number;
+    environment?: string;
+    commitHash?: string;
+    extra?: Record<string, string>;
+}
+interface DeployData {
+    commitHash: string;
+    branch?: string;
+    author?: string;
+    status: 'started' | 'succeeded' | 'failed';
+    buildDurationMs?: number;
+    url?: string;
+    environment?: string;
+    provider?: string;
 }
+interface AdapterData {
+    adapter: string;
+    operation: string;
+    durationMs: number;
+    success: boolean;
+    error?: string;
+    meta?: Record<string, string>;
+}
+type MonitorEvent = {
+    type: 'heartbeat';
+    data: HeartbeatData;
+    timestamp: string;
+} | {
+    type: 'request';
+    data: RequestData;
+    timestamp: string;
+} | {
+    type: 'vital';
+    data: VitalData;
+    timestamp: string;
+} | {
+    type: 'error';
+    data: ErrorData;
+    timestamp: string;
+} | {
+    type: 'deploy';
+    data: DeployData;
+    timestamp: string;
+} | {
+    type: 'adapter';
+    data: AdapterData;
+    timestamp: string;
+};
+type MonitorEventType = MonitorEvent['type'];
+/** Evento sem timestamp — usado pelo collector ao receber do client */
+type MonitorEventInput = Omit<MonitorEvent, 'timestamp'>;
+/** Hook para filtrar/modificar eventos antes do envio */
+type BeforeSendHook = (event: MonitorEvent) => MonitorEvent | null;
 
 interface MonitorConfig {
     /** ID do projeto no Nuvio */
     projectId: string;
     /** API key gerada no Nuvio */
     apiKey: string;
-    /** URL do endpoint de ingest (ex: https://app.nuvio.com/api/monitor/ingest) */
+    /** URL do endpoint de ingest */
     endpoint: string;
     /** Intervalo do heartbeat em ms (default: 60000) */
     heartbeatInterval?: number;
     /** Intervalo do flush do buffer em ms (default: 30000) */
     flushInterval?: number;
+    /** Timeout do fetch em ms (default: 10000) */
+    timeout?: number;
+    /** Max tentativas de retry (default: 3) */
+    maxRetries?: number;
     /** Desabilitar em desenvolvimento (default: true) */
     disableInDev?: boolean;
+    /** Taxa de amostragem 0.0-1.0 (default: 1.0). Heartbeats nunca são amostrados */
+    sampleRate?: number;
+    /** Hook chamado antes de enfileirar cada evento. Retorna null para dropar */
+    beforeSend?: BeforeSendHook;
+    /** Habilitar logs de debug no console (default: false) */
+    debug?: boolean;
+    /** Capturar erros globais automaticamente — window.onerror (default: false) */
+    captureErrors?: boolean;
+    /** Capturar unhandled promise rejections automaticamente (default: false) */
+    captureUnhandledRejections?: boolean;
 }
 declare class MonitorClient {
     readonly config: MonitorConfig;
-    readonly collector: Collector;
+    private readonly collector;
+    private readonly logger;
     private heartbeatTimer;
+    private globalHandlersCleanup;
     private active;
     constructor(config: MonitorConfig);
     /** Inicia o monitoring (heartbeat + collector) */
     start(): void;
     /** Para o monitoring */
     stop(): void;
+    /** Força um flush imediato do buffer */
+    flush(): void;
+    /** Verifica se o monitoring está ativo */
+    get isActive(): boolean;
     /** Registra um evento de request HTTP (usado pelo middleware) */
-    trackRequest(data: {
-        method: string;
-        route: string;
-        statusCode: number;
-        responseTimeMs: number;
-        userAgent?: string;
-        region?: string;
-    }): void;
+    trackRequest(data: RequestData): void;
     /** Registra um Web Vital (usado pelo MonitorScript) */
-    trackVital(data: {
-        name: 'LCP' | 'INP' | 'CLS' | 'FCP' | 'TTFB';
-        value: number;
-        rating: 'good' | 'needs-improvement' | 'poor';
-        page?: string;
-        deviceType?: string;
-        browser?: string;
-    }): void;
+    trackVital(data: VitalData): void;
+    /** Registra um evento de adapter (DB, cache, AI, queue, email) */
+    trackAdapter(data: AdapterData): void;
+    /** Registra um erro capturado */
+    captureError(data: ErrorData): void;
+    /** Registra um evento de deploy */
+    trackDeploy(data: DeployData): void;
     private startHeartbeat;
     private sendHeartbeat;
-    private isDev;
 }
 
+interface CaptureContext {
+    route?: string;
+    method?: string;
+    statusCode?: number;
+    extra?: Record<string, string>;
+}
+/**
+ * Captura um erro e envia pro monitor.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await riskyOperation()
+ * } catch (err) {
+ *   captureError(monitor, err, { route: '/api/users' })
+ * }
+ * ```
+ */
+declare function captureError(monitor: MonitorClient, error: unknown, context?: CaptureContext): void;
+/**
+ * Registra handlers globais para erros não capturados.
+ * Só funciona no browser — no servidor, NÃO interceptamos uncaughtException
+ * (perigoso para um SDK de monitoring).
+ *
+ * @returns Função de cleanup que remove os handlers
+ *
+ * @example
+ * ```ts
+ * const cleanup = setupGlobalHandlers(monitor)
+ * // Quando quiser parar:
+ * cleanup()
+ * ```
+ */
+declare function setupGlobalHandlers(monitor: MonitorClient): () => void;
+
 /**
  * Cria e inicia uma instância do monitor.
  *
@@ -77,10 +182,10 @@ declare class MonitorClient {
  * export const monitor = createMonitor({
  *   projectId: 'uuid-do-projeto',
  *   apiKey: 'nuvio_mon_xxxxxxxx',
- *   endpoint: 'https://app.nuvio.com/api/monitor/ingest',
+ *   endpoint: 'https://nuvio.app/api/monitor/ingest',
  * })
  * ```
  */
 declare function createMonitor(config: MonitorConfig): MonitorClient;
 
-export { MonitorClient, type MonitorConfig, createMonitor };
+export { type AdapterData, type BeforeSendHook, type DeployData, type ErrorData, type HeartbeatData, MonitorClient, type MonitorConfig, type MonitorEvent, type MonitorEventInput, type MonitorEventType, type RequestData, type VitalData, captureError, createMonitor, setupGlobalHandlers };

package/dist/index.d.ts

@@ -1,72 +1,177 @@
-interface MonitorEvent {
-    type: 'heartbeat' | 'request' | 'vital';
-    data: Record<string, unknown>;
-    timestamp: string;
+interface HeartbeatData {
+    status: 'online' | 'offline';
+    latencyMs: number;
 }
-interface TransportConfig {
-    endpoint: string;
-    apiKey: string;
+interface RequestData {
+    method: string;
+    route: string;
+    statusCode: number;
+    responseTimeMs: number;
+    userAgent?: string;
+    region?: string;
 }
-
-declare class Collector {
-    private buffer;
-    private timer;
-    private config;
-    private flushInterval;
-    constructor(config: TransportConfig, flushInterval?: number);
-    start(): void;
-    stop(): void;
-    push(event: Omit<MonitorEvent, 'timestamp'>): void;
-    private flush;
+interface VitalData {
+    name: 'LCP' | 'INP' | 'CLS' | 'FCP' | 'TTFB';
+    value: number;
+    rating: 'good' | 'needs-improvement' | 'poor';
+    page?: string;
+    deviceType?: string;
+    browser?: string;
+}
+interface ErrorData {
+    type: 'unhandled' | 'caught' | 'promise';
+    message: string;
+    stack?: string;
+    groupingKey: string;
+    route?: string;
+    method?: string;
+    statusCode?: number;
+    environment?: string;
+    commitHash?: string;
+    extra?: Record<string, string>;
+}
+interface DeployData {
+    commitHash: string;
+    branch?: string;
+    author?: string;
+    status: 'started' | 'succeeded' | 'failed';
+    buildDurationMs?: number;
+    url?: string;
+    environment?: string;
+    provider?: string;
 }
+interface AdapterData {
+    adapter: string;
+    operation: string;
+    durationMs: number;
+    success: boolean;
+    error?: string;
+    meta?: Record<string, string>;
+}
+type MonitorEvent = {
+    type: 'heartbeat';
+    data: HeartbeatData;
+    timestamp: string;
+} | {
+    type: 'request';
+    data: RequestData;
+    timestamp: string;
+} | {
+    type: 'vital';
+    data: VitalData;
+    timestamp: string;
+} | {
+    type: 'error';
+    data: ErrorData;
+    timestamp: string;
+} | {
+    type: 'deploy';
+    data: DeployData;
+    timestamp: string;
+} | {
+    type: 'adapter';
+    data: AdapterData;
+    timestamp: string;
+};
+type MonitorEventType = MonitorEvent['type'];
+/** Evento sem timestamp — usado pelo collector ao receber do client */
+type MonitorEventInput = Omit<MonitorEvent, 'timestamp'>;
+/** Hook para filtrar/modificar eventos antes do envio */
+type BeforeSendHook = (event: MonitorEvent) => MonitorEvent | null;
 
 interface MonitorConfig {
     /** ID do projeto no Nuvio */
     projectId: string;
     /** API key gerada no Nuvio */
     apiKey: string;
-    /** URL do endpoint de ingest (ex: https://app.nuvio.com/api/monitor/ingest) */
+    /** URL do endpoint de ingest */
     endpoint: string;
     /** Intervalo do heartbeat em ms (default: 60000) */
     heartbeatInterval?: number;
     /** Intervalo do flush do buffer em ms (default: 30000) */
     flushInterval?: number;
+    /** Timeout do fetch em ms (default: 10000) */
+    timeout?: number;
+    /** Max tentativas de retry (default: 3) */
+    maxRetries?: number;
     /** Desabilitar em desenvolvimento (default: true) */
     disableInDev?: boolean;
+    /** Taxa de amostragem 0.0-1.0 (default: 1.0). Heartbeats nunca são amostrados */
+    sampleRate?: number;
+    /** Hook chamado antes de enfileirar cada evento. Retorna null para dropar */
+    beforeSend?: BeforeSendHook;
+    /** Habilitar logs de debug no console (default: false) */
+    debug?: boolean;
+    /** Capturar erros globais automaticamente — window.onerror (default: false) */
+    captureErrors?: boolean;
+    /** Capturar unhandled promise rejections automaticamente (default: false) */
+    captureUnhandledRejections?: boolean;
 }
 declare class MonitorClient {
     readonly config: MonitorConfig;
-    readonly collector: Collector;
+    private readonly collector;
+    private readonly logger;
     private heartbeatTimer;
+    private globalHandlersCleanup;
     private active;
     constructor(config: MonitorConfig);
     /** Inicia o monitoring (heartbeat + collector) */
     start(): void;
     /** Para o monitoring */
     stop(): void;
+    /** Força um flush imediato do buffer */
+    flush(): void;
+    /** Verifica se o monitoring está ativo */
+    get isActive(): boolean;
     /** Registra um evento de request HTTP (usado pelo middleware) */
-    trackRequest(data: {
-        method: string;
-        route: string;
-        statusCode: number;
-        responseTimeMs: number;
-        userAgent?: string;
-        region?: string;
-    }): void;
+    trackRequest(data: RequestData): void;
     /** Registra um Web Vital (usado pelo MonitorScript) */
-    trackVital(data: {
-        name: 'LCP' | 'INP' | 'CLS' | 'FCP' | 'TTFB';
-        value: number;
-        rating: 'good' | 'needs-improvement' | 'poor';
-        page?: string;
-        deviceType?: string;
-        browser?: string;
-    }): void;
+    trackVital(data: VitalData): void;
+    /** Registra um evento de adapter (DB, cache, AI, queue, email) */
+    trackAdapter(data: AdapterData): void;
+    /** Registra um erro capturado */
+    captureError(data: ErrorData): void;
+    /** Registra um evento de deploy */
+    trackDeploy(data: DeployData): void;
     private startHeartbeat;
     private sendHeartbeat;
-    private isDev;
 }
 
+interface CaptureContext {
+    route?: string;
+    method?: string;
+    statusCode?: number;
+    extra?: Record<string, string>;
+}
+/**
+ * Captura um erro e envia pro monitor.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await riskyOperation()
+ * } catch (err) {
+ *   captureError(monitor, err, { route: '/api/users' })
+ * }
+ * ```
+ */
+declare function captureError(monitor: MonitorClient, error: unknown, context?: CaptureContext): void;
+/**
+ * Registra handlers globais para erros não capturados.
+ * Só funciona no browser — no servidor, NÃO interceptamos uncaughtException
+ * (perigoso para um SDK de monitoring).
+ *
+ * @returns Função de cleanup que remove os handlers
+ *
+ * @example
+ * ```ts
+ * const cleanup = setupGlobalHandlers(monitor)
+ * // Quando quiser parar:
+ * cleanup()
+ * ```
+ */
+declare function setupGlobalHandlers(monitor: MonitorClient): () => void;
+
 /**
  * Cria e inicia uma instância do monitor.
  *
@@ -77,10 +182,10 @@ declare class MonitorClient {
  * export const monitor = createMonitor({
  *   projectId: 'uuid-do-projeto',
  *   apiKey: 'nuvio_mon_xxxxxxxx',
- *   endpoint: 'https://app.nuvio.com/api/monitor/ingest',
+ *   endpoint: 'https://nuvio.app/api/monitor/ingest',
  * })
  * ```
  */
 declare function createMonitor(config: MonitorConfig): MonitorClient;
 
-export { MonitorClient, type MonitorConfig, createMonitor };
+export { type AdapterData, type BeforeSendHook, type DeployData, type ErrorData, type HeartbeatData, MonitorClient, type MonitorConfig, type MonitorEvent, type MonitorEventInput, type MonitorEventType, type RequestData, type VitalData, captureError, createMonitor, setupGlobalHandlers };