@victor-studio/monitor 0.2.0 → 0.4.0

package/dist/errors/index.cjs

@@ -0,0 +1,93 @@
+'use strict';
+
+// src/errors/normalize.ts
+function generateGroupingKey(error) {
+  const name = error.name || "Error";
+  const message = stripDynamicValues(error.message);
+  const frames = extractTopFrames(error.stack, 3);
+  const raw = `${name}:${message}:${frames.join("|")}`;
+  return simpleHash(raw);
+}
+function normalizeStack(stack) {
+  if (!stack) return void 0;
+  return stack.split("\n").map((line) => {
+    let normalized = line.replace(/\(?\/?(?:[\w.-]+\/)+/g, "");
+    normalized = normalized.replace(/\?[^):\s]+/g, "");
+    return normalized;
+  }).join("\n");
+}
+function extractTopFrames(stack, count) {
+  if (!stack) return [];
+  return stack.split("\n").filter((line) => line.includes("at ") || line.includes("@")).slice(0, count).map((line) => line.trim());
+}
+function stripDynamicValues(message) {
+  return message.replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, "<uuid>").replace(/\b\d{4,}\b/g, "<n>").replace(/["'][^"']{32,}["']/g, "<token>");
+}
+function simpleHash(str) {
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash = (hash << 5) - hash + char | 0;
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+
+// src/errors/handler.ts
+function captureError(monitor, error, context) {
+  const normalized = toError(error);
+  const data = {
+    type: "caught",
+    message: normalized.message,
+    stack: normalizeStack(normalized.stack),
+    groupingKey: generateGroupingKey(normalized),
+    route: context?.route,
+    method: context?.method,
+    statusCode: context?.statusCode,
+    extra: context?.extra
+  };
+  monitor.captureError(data);
+}
+function setupGlobalHandlers(monitor) {
+  if (typeof window === "undefined") return () => {
+  };
+  const onError = (event) => {
+    const error = event.error ?? new Error(event.message);
+    const normalized = toError(error);
+    monitor.captureError({
+      type: "unhandled",
+      message: normalized.message,
+      stack: normalizeStack(normalized.stack),
+      groupingKey: generateGroupingKey(normalized),
+      route: window.location.pathname
+    });
+  };
+  const onRejection = (event) => {
+    const error = event.reason ?? new Error("Unhandled promise rejection");
+    const normalized = toError(error);
+    monitor.captureError({
+      type: "promise",
+      message: normalized.message,
+      stack: normalizeStack(normalized.stack),
+      groupingKey: generateGroupingKey(normalized),
+      route: window.location.pathname
+    });
+  };
+  window.addEventListener("error", onError);
+  window.addEventListener("unhandledrejection", onRejection);
+  return () => {
+    window.removeEventListener("error", onError);
+    window.removeEventListener("unhandledrejection", onRejection);
+  };
+}
+function toError(value) {
+  if (value instanceof Error) return value;
+  if (typeof value === "string") return new Error(value);
+  return new Error(String(value));
+}
+
+exports.captureError = captureError;
+exports.generateGroupingKey = generateGroupingKey;
+exports.normalizeStack = normalizeStack;
+exports.setupGlobalHandlers = setupGlobalHandlers;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/errors/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/errors/normalize.ts","../../src/errors/handler.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["// Normalização de erros — stack cleanup e grouping key\n\n/**\n * Gera uma chave de agrupamento a partir do erro.\n * Erros com o mesmo groupingKey são agrupados no dashboard.\n * Usa: nome do erro + mensagem + 3 primeiros frames do stack.\n */\nexport function generateGroupingKey(error: Error): string {\n  const name = error.name || 'Error'\n  const message = stripDynamicValues(error.message)\n  const frames = extractTopFrames(error.stack, 3)\n\n  const raw = `${name}:${message}:${frames.join('|')}`\n  return simpleHash(raw)\n}\n\n/**\n * Normaliza stack trace — remove caminhos absolutos e queries dinâmicas.\n */\nexport function normalizeStack(stack: string | undefined): string | undefined {\n  if (!stack) return undefined\n\n  return stack\n    .split('\\n')\n    .map((line) => {\n      // Remover caminhos absolutos do filesystem\n      let normalized = line.replace(/\\(?\\/?(?:[\\w.-]+\\/)+/g, '')\n      // Remover query strings e hashes de URLs\n      normalized = normalized.replace(/\\?[^):\\s]+/g, '')\n      return normalized\n    })\n    .join('\\n')\n}\n\n// ─── Helpers internos ───────────────────────────────\n\n/** Extrai as N primeiras linhas significativas do stack */\nfunction extractTopFrames(stack: string | undefined, count: number): string[] {\n  if (!stack) return []\n\n  return stack\n    .split('\\n')\n    .filter((line) => line.includes('at ') || line.includes('@'))\n    .slice(0, count)\n    .map((line) => line.trim())\n}\n\n/** Remove valores dinâmicos da mensagem (UUIDs, números, tokens) */\nfunction stripDynamicValues(message: string): string {\n  return message\n    .replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, '<uuid>')\n    .replace(/\\b\\d{4,}\\b/g, '<n>')\n    .replace(/[\"'][^\"']{32,}[\"']/g, '<token>')\n}\n\n/** Hash simples para gerar groupingKey determinístico */\nfunction simpleHash(str: string): string {\n  let hash = 0\n  for (let i = 0; i < str.length; i++) {\n    const char = str.charCodeAt(i)\n    hash = ((hash << 5) - hash + char) | 0\n  }\n  // Converter para hex positivo\n  return (hash >>> 0).toString(16).padStart(8, '0')\n}\n","// Error handler — captura de erros manual e automática\n\nimport type { MonitorClient } from '../core/client'\nimport type { ErrorData } from '../types'\nimport { generateGroupingKey, normalizeStack } from './normalize'\n\ninterface CaptureContext {\n  route?: string\n  method?: string\n  statusCode?: number\n  extra?: Record<string, string>\n}\n\n/**\n * Captura um erro e envia pro monitor.\n *\n * @example\n * ```ts\n * try {\n *   await riskyOperation()\n * } catch (err) {\n *   captureError(monitor, err, { route: '/api/users' })\n * }\n * ```\n */\nexport function captureError(\n  monitor: MonitorClient,\n  error: unknown,\n  context?: CaptureContext,\n): void {\n  const normalized = toError(error)\n  const data: ErrorData = {\n    type: 'caught',\n    message: normalized.message,\n    stack: normalizeStack(normalized.stack),\n    groupingKey: generateGroupingKey(normalized),\n    route: context?.route,\n    method: context?.method,\n    statusCode: context?.statusCode,\n    extra: context?.extra,\n  }\n\n  monitor.captureError(data)\n}\n\n/**\n * Registra handlers globais para erros não capturados.\n * Só funciona no browser — no servidor, NÃO interceptamos uncaughtException\n * (perigoso para um SDK de monitoring).\n *\n * @returns Função de cleanup que remove os handlers\n *\n * @example\n * ```ts\n * const cleanup = setupGlobalHandlers(monitor)\n * // Quando quiser parar:\n * cleanup()\n * ```\n */\nexport function setupGlobalHandlers(monitor: MonitorClient): () => void {\n  if (typeof window === 'undefined') return () => {}\n\n  const onError = (event: ErrorEvent) => {\n    const error = event.error ?? new Error(event.message)\n    const normalized = toError(error)\n\n    monitor.captureError({\n      type: 'unhandled',\n      message: normalized.message,\n      stack: normalizeStack(normalized.stack),\n      groupingKey: generateGroupingKey(normalized),\n      route: window.location.pathname,\n    })\n  }\n\n  const onRejection = (event: PromiseRejectionEvent) => {\n    const error = event.reason ?? new Error('Unhandled promise rejection')\n    const normalized = toError(error)\n\n    monitor.captureError({\n      type: 'promise',\n      message: normalized.message,\n      stack: normalizeStack(normalized.stack),\n      groupingKey: generateGroupingKey(normalized),\n      route: window.location.pathname,\n    })\n  }\n\n  window.addEventListener('error', onError)\n  window.addEventListener('unhandledrejection', onRejection)\n\n  return () => {\n    window.removeEventListener('error', onError)\n    window.removeEventListener('unhandledrejection', onRejection)\n  }\n}\n\n/** Converte qualquer valor em Error */\nfunction toError(value: unknown): Error {\n  if (value instanceof Error) return value\n  if (typeof value === 'string') return new Error(value)\n  return new Error(String(value))\n}\n"]}

package/dist/errors/index.d.cts

@@ -0,0 +1,183 @@
+interface HeartbeatData {
+    status: 'online' | 'offline';
+    latencyMs: number;
+}
+interface RequestData {
+    method: string;
+    route: string;
+    statusCode: number;
+    responseTimeMs: number;
+    userAgent?: string;
+    region?: string;
+}
+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;
+};
+/** 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 */
+    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;
+    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: RequestData): void;
+    /** Registra um Web Vital (usado pelo MonitorScript) */
+    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;
+}
+
+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;
+
+/**
+ * Gera uma chave de agrupamento a partir do erro.
+ * Erros com o mesmo groupingKey são agrupados no dashboard.
+ * Usa: nome do erro + mensagem + 3 primeiros frames do stack.
+ */
+declare function generateGroupingKey(error: Error): string;
+/**
+ * Normaliza stack trace — remove caminhos absolutos e queries dinâmicas.
+ */
+declare function normalizeStack(stack: string | undefined): string | undefined;
+
+export { captureError, generateGroupingKey, normalizeStack, setupGlobalHandlers };

package/dist/errors/index.d.ts

@@ -0,0 +1,183 @@
+interface HeartbeatData {
+    status: 'online' | 'offline';
+    latencyMs: number;
+}
+interface RequestData {
+    method: string;
+    route: string;
+    statusCode: number;
+    responseTimeMs: number;
+    userAgent?: string;
+    region?: string;
+}
+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;
+};
+/** 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 */
+    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;
+    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: RequestData): void;
+    /** Registra um Web Vital (usado pelo MonitorScript) */
+    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;
+}
+
+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;
+
+/**
+ * Gera uma chave de agrupamento a partir do erro.
+ * Erros com o mesmo groupingKey são agrupados no dashboard.
+ * Usa: nome do erro + mensagem + 3 primeiros frames do stack.
+ */
+declare function generateGroupingKey(error: Error): string;
+/**
+ * Normaliza stack trace — remove caminhos absolutos e queries dinâmicas.
+ */
+declare function normalizeStack(stack: string | undefined): string | undefined;
+
+export { captureError, generateGroupingKey, normalizeStack, setupGlobalHandlers };

package/dist/errors/index.js

@@ -0,0 +1,88 @@
+// src/errors/normalize.ts
+function generateGroupingKey(error) {
+  const name = error.name || "Error";
+  const message = stripDynamicValues(error.message);
+  const frames = extractTopFrames(error.stack, 3);
+  const raw = `${name}:${message}:${frames.join("|")}`;
+  return simpleHash(raw);
+}
+function normalizeStack(stack) {
+  if (!stack) return void 0;
+  return stack.split("\n").map((line) => {
+    let normalized = line.replace(/\(?\/?(?:[\w.-]+\/)+/g, "");
+    normalized = normalized.replace(/\?[^):\s]+/g, "");
+    return normalized;
+  }).join("\n");
+}
+function extractTopFrames(stack, count) {
+  if (!stack) return [];
+  return stack.split("\n").filter((line) => line.includes("at ") || line.includes("@")).slice(0, count).map((line) => line.trim());
+}
+function stripDynamicValues(message) {
+  return message.replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, "<uuid>").replace(/\b\d{4,}\b/g, "<n>").replace(/["'][^"']{32,}["']/g, "<token>");
+}
+function simpleHash(str) {
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash = (hash << 5) - hash + char | 0;
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+
+// src/errors/handler.ts
+function captureError(monitor, error, context) {
+  const normalized = toError(error);
+  const data = {
+    type: "caught",
+    message: normalized.message,
+    stack: normalizeStack(normalized.stack),
+    groupingKey: generateGroupingKey(normalized),
+    route: context?.route,
+    method: context?.method,
+    statusCode: context?.statusCode,
+    extra: context?.extra
+  };
+  monitor.captureError(data);
+}
+function setupGlobalHandlers(monitor) {
+  if (typeof window === "undefined") return () => {
+  };
+  const onError = (event) => {
+    const error = event.error ?? new Error(event.message);
+    const normalized = toError(error);
+    monitor.captureError({
+      type: "unhandled",
+      message: normalized.message,
+      stack: normalizeStack(normalized.stack),
+      groupingKey: generateGroupingKey(normalized),
+      route: window.location.pathname
+    });
+  };
+  const onRejection = (event) => {
+    const error = event.reason ?? new Error("Unhandled promise rejection");
+    const normalized = toError(error);
+    monitor.captureError({
+      type: "promise",
+      message: normalized.message,
+      stack: normalizeStack(normalized.stack),
+      groupingKey: generateGroupingKey(normalized),
+      route: window.location.pathname
+    });
+  };
+  window.addEventListener("error", onError);
+  window.addEventListener("unhandledrejection", onRejection);
+  return () => {
+    window.removeEventListener("error", onError);
+    window.removeEventListener("unhandledrejection", onRejection);
+  };
+}
+function toError(value) {
+  if (value instanceof Error) return value;
+  if (typeof value === "string") return new Error(value);
+  return new Error(String(value));
+}
+
+export { captureError, generateGroupingKey, normalizeStack, setupGlobalHandlers };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/errors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/errors/normalize.ts","../../src/errors/handler.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["// Normalização de erros — stack cleanup e grouping key\n\n/**\n * Gera uma chave de agrupamento a partir do erro.\n * Erros com o mesmo groupingKey são agrupados no dashboard.\n * Usa: nome do erro + mensagem + 3 primeiros frames do stack.\n */\nexport function generateGroupingKey(error: Error): string {\n  const name = error.name || 'Error'\n  const message = stripDynamicValues(error.message)\n  const frames = extractTopFrames(error.stack, 3)\n\n  const raw = `${name}:${message}:${frames.join('|')}`\n  return simpleHash(raw)\n}\n\n/**\n * Normaliza stack trace — remove caminhos absolutos e queries dinâmicas.\n */\nexport function normalizeStack(stack: string | undefined): string | undefined {\n  if (!stack) return undefined\n\n  return stack\n    .split('\\n')\n    .map((line) => {\n      // Remover caminhos absolutos do filesystem\n      let normalized = line.replace(/\\(?\\/?(?:[\\w.-]+\\/)+/g, '')\n      // Remover query strings e hashes de URLs\n      normalized = normalized.replace(/\\?[^):\\s]+/g, '')\n      return normalized\n    })\n    .join('\\n')\n}\n\n// ─── Helpers internos ───────────────────────────────\n\n/** Extrai as N primeiras linhas significativas do stack */\nfunction extractTopFrames(stack: string | undefined, count: number): string[] {\n  if (!stack) return []\n\n  return stack\n    .split('\\n')\n    .filter((line) => line.includes('at ') || line.includes('@'))\n    .slice(0, count)\n    .map((line) => line.trim())\n}\n\n/** Remove valores dinâmicos da mensagem (UUIDs, números, tokens) */\nfunction stripDynamicValues(message: string): string {\n  return message\n    .replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, '<uuid>')\n    .replace(/\\b\\d{4,}\\b/g, '<n>')\n    .replace(/[\"'][^\"']{32,}[\"']/g, '<token>')\n}\n\n/** Hash simples para gerar groupingKey determinístico */\nfunction simpleHash(str: string): string {\n  let hash = 0\n  for (let i = 0; i < str.length; i++) {\n    const char = str.charCodeAt(i)\n    hash = ((hash << 5) - hash + char) | 0\n  }\n  // Converter para hex positivo\n  return (hash >>> 0).toString(16).padStart(8, '0')\n}\n","// Error handler — captura de erros manual e automática\n\nimport type { MonitorClient } from '../core/client'\nimport type { ErrorData } from '../types'\nimport { generateGroupingKey, normalizeStack } from './normalize'\n\ninterface CaptureContext {\n  route?: string\n  method?: string\n  statusCode?: number\n  extra?: Record<string, string>\n}\n\n/**\n * Captura um erro e envia pro monitor.\n *\n * @example\n * ```ts\n * try {\n *   await riskyOperation()\n * } catch (err) {\n *   captureError(monitor, err, { route: '/api/users' })\n * }\n * ```\n */\nexport function captureError(\n  monitor: MonitorClient,\n  error: unknown,\n  context?: CaptureContext,\n): void {\n  const normalized = toError(error)\n  const data: ErrorData = {\n    type: 'caught',\n    message: normalized.message,\n    stack: normalizeStack(normalized.stack),\n    groupingKey: generateGroupingKey(normalized),\n    route: context?.route,\n    method: context?.method,\n    statusCode: context?.statusCode,\n    extra: context?.extra,\n  }\n\n  monitor.captureError(data)\n}\n\n/**\n * Registra handlers globais para erros não capturados.\n * Só funciona no browser — no servidor, NÃO interceptamos uncaughtException\n * (perigoso para um SDK de monitoring).\n *\n * @returns Função de cleanup que remove os handlers\n *\n * @example\n * ```ts\n * const cleanup = setupGlobalHandlers(monitor)\n * // Quando quiser parar:\n * cleanup()\n * ```\n */\nexport function setupGlobalHandlers(monitor: MonitorClient): () => void {\n  if (typeof window === 'undefined') return () => {}\n\n  const onError = (event: ErrorEvent) => {\n    const error = event.error ?? new Error(event.message)\n    const normalized = toError(error)\n\n    monitor.captureError({\n      type: 'unhandled',\n      message: normalized.message,\n      stack: normalizeStack(normalized.stack),\n      groupingKey: generateGroupingKey(normalized),\n      route: window.location.pathname,\n    })\n  }\n\n  const onRejection = (event: PromiseRejectionEvent) => {\n    const error = event.reason ?? new Error('Unhandled promise rejection')\n    const normalized = toError(error)\n\n    monitor.captureError({\n      type: 'promise',\n      message: normalized.message,\n      stack: normalizeStack(normalized.stack),\n      groupingKey: generateGroupingKey(normalized),\n      route: window.location.pathname,\n    })\n  }\n\n  window.addEventListener('error', onError)\n  window.addEventListener('unhandledrejection', onRejection)\n\n  return () => {\n    window.removeEventListener('error', onError)\n    window.removeEventListener('unhandledrejection', onRejection)\n  }\n}\n\n/** Converte qualquer valor em Error */\nfunction toError(value: unknown): Error {\n  if (value instanceof Error) return value\n  if (typeof value === 'string') return new Error(value)\n  return new Error(String(value))\n}\n"]}