@monzori/browser 0.0.0-stage → 0.1.2

package/README.md

@@ -1,3 +1,58 @@
-# Temporary Holding Version
+# Monzori Browser SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Captura erros globais, promises rejeitadas, reporte manual e console error/warn. Demais níveis de console são opt-in. O adaptador React exporta MonzoriErrorBoundary; React é peer opcional e fica fora do núcleo.
+
+Instale com npm install @monzori/browser. Versão inicial para piloto privado.
+
+A partir da versão 0.1.2, falhas recuperáveis de importação, inicialização e envio afetam somente a coleta. Recursos de navegador indisponíveis devolvem um cliente inativo; inicialização parcial desfaz os hooks instalados. A fila é limitada e o envio tem prazo de três segundos, backoff e tratamento terminal de rejeições.
+
+Para isolar também falhas de download/avaliação do módulo, carregue o SDK após iniciar o React, sem aguardá-lo no caminho de renderização:
+
+```js
+// Execute após iniciar o frontend; falhas encerram somente a coleta.
+void import('@monzori/browser')
+  .then(({default: Monzori}) => {
+    Monzori.start({apiKey: 'IDENTIFICADOR_PUBLICO', release: 'web-2026.11.14'});
+  })
+  .catch(() => {});
+```
+
+Não condicione login, navegação ou ações do usuário ao resultado de flush(). Um beforeSend fornecido pela aplicação deve ser curto: código executado no mesmo contexto JavaScript não pode ser isolado de callbacks que nunca retornam ou do esgotamento de recursos do navegador.
+
+O piloto hospedado usa o endereço padrão abaixo. Para obter a chave, abra **Integração** na sua aplicação frontend no painel. Configure um endpoint explícito somente para testes locais.
+
+```ts
+import Monzori from '@monzori/browser';
+
+const monzori = Monzori.start({
+  apiKey: 'IDENTIFICADOR_PUBLICO_GERADO_NO_PAINEL',
+  release: 'web-2026.11.10',
+  console: { log: false, info: false, debug: false }
+});
+
+monzori.captureException(new Error('Evento explícito de teste'));
+```
+
+O endereço padrão é `https://ingest.monzori.com.br/v1/web/events`. `apiKey` é o identificador público restrito à ingestão da fonte, não uma senha de administração. A inicialização devolve o client usado no Error Boundary e no reporte manual. Há também o export nomeado `start`.
+
+`endpoint` é uma opção avançada: para testes locais, informar `http://localhost:3333/v1/web/events`; destinos fora de loopback exigem HTTPS. Um endpoint explícito inválido desabilita o envio, sem fallback silencioso. O endereço padrão não implica que a infraestrutura do piloto já esteja publicada.
+
+Compatibilidade: `initMonzori({publicKey, release, endpoint})` continua funcionando como alias legado, usando o mesmo client; preferir `Monzori.start({apiKey, release})` nas novas integrações. Escolher `apiKey` ou `publicKey`, sem combinar os dois. A primeira inicialização fica ativa até `close()`, sem duplicar listeners em chamadas subsequentes.
+
+```tsx
+import { MonzoriErrorBoundary } from '@monzori/browser/react';
+
+<MonzoriErrorBoundary client={monzori} fallback={<p>Não foi possível exibir este conteúdo.</p>}>
+  <App />
+</MonzoriErrorBoundary>
+```
+
+Novas integrações podem receber eventos de qualquer site. A restrição opcional fica em **Integração → Configurações → Domínios permitidos**; integrações anteriores mantêm suas restrições. HTTP é aceito apenas em loopback local. O identificador público só admite eventos naquele vínculo, sem permitir leitura ou upload de mapas. A instalação local usa http://localhost:3333/v1/web/events. Release precisa coincidir com o upload privado dos source maps. Identificadores de release devem ser únicos por versão; não reutilizá-los para substituir mapas de um mesmo artefato.
+
+Buffer somente em memória, sem cookies/storage/DOM/formulários/identificação de visitantes automáticos. Limites: 100 eventos/256 KiB, flush a cada 5 segundos ou 20 eventos, até 50 eventos e 32 KiB por pedido. O SDK reserva espaço para contexto do servidor e descarta um evento serializado acima de 6 KiB; o teto canônico na API é 8 KiB. Reenvio com o mesmo ID, backoff de 1–60 segundos com jitter, até 24 horas de idade; fechar a página pode perder eventos não admitidos. No máximo 60 entradas de console por minuto/página. O SDK não registra seus próprios diagnósticos no console monitorado.
+
+URL, mensagens, stacks e atributos são sanitizados antes do envio; antes do commit há uma segunda sanitização no servidor. beforeSend permite remover eventos ou ajustar conteúdo. Nenhuma heurística remove todo segredo ou dado pessoal de texto livre: evite emiti-los. Contexto usa apenas propriedades próprias de objetos simples, sem avaliar getters; a stack de um Error real é lida explicitamente para suportar engines com stack lazy.
+
+monzori.stats() mostra pendências, bytes, descartes, reenvios e confirmações HTTP locais. Confirmado não significa já pesquisável. monzori.flush() tenta enviar os pendentes, respeitando backoff. monzori.close() encerra captura/timers e restaura os métodos de console se eles ainda forem os wrappers instalados pelo SDK.
+
+Source maps v3 planos Vite/Rollup e Webpack são enviados de forma privada pelo painel/API autenticada, fora do SDK. Não publicar .map no bucket/CDN público. O backend só consulta mapas cadastrados para organização/aplicação/release/URL do artefato exatos; nunca busca sourceMappingURL na Internet. Sem mapa, o painel preserva a stack recebida.

package/dist/index.d.ts

@@ -0,0 +1,52 @@
+export type Kind = 'js_error' | 'promise_rejection' | 'react_error' | 'console' | 'manual';
+export type Severity = 'error' | 'warn' | 'info' | 'debug';
+type BaseOptions = {
+    endpoint?: string;
+    release: string;
+    console?: false | {
+        log?: boolean;
+        info?: boolean;
+        debug?: boolean;
+    };
+    beforeSend?: (event: WebEvent) => WebEvent | null;
+};
+export type Options = BaseOptions & ({
+    apiKey: string;
+    publicKey?: never;
+} | {
+    publicKey: string;
+    apiKey?: never;
+});
+export declare const DEFAULT_ENDPOINT = "https://ingest.monzori.com.br/v1/web/events";
+export type WebEvent = {
+    event_id: string;
+    occurred_at: string;
+    kind: Kind;
+    severity: Severity;
+    message: string;
+    stack: string;
+    url: string;
+    release: string;
+    attributes: unknown;
+};
+export type Client = {
+    captureException: (error: unknown, context?: unknown, kind?: Kind) => void;
+    captureMessage: (message: string, severity?: Severity, context?: unknown) => void;
+    flush: () => Promise<void>;
+    close: () => void;
+    stats: () => {
+        pending: number;
+        bytes: number;
+        dropped: number;
+        retries: number;
+        confirmed: number;
+        disabled: boolean;
+    };
+};
+export declare function start(options: Options): Client;
+/** @deprecated Use Monzori.start(options) or the named start export. */
+export declare const initMonzori: typeof start;
+declare const Monzori: {
+    start: typeof start;
+};
+export default Monzori;

package/dist/index.js

@@ -0,0 +1,274 @@
+import { cleanText, cleanUrl, safeValue } from './sanitize.js';
+export const DEFAULT_ENDPOINT = 'https://ingest.monzori.com.br/v1/web/events';
+let active;
+export function start(options) {
+    if (active)
+        return active;
+    const restorers = [];
+    try {
+        return createClient(options, restorers);
+    }
+    catch {
+        for (const restore of restorers.reverse()) {
+            try {
+                restore();
+            }
+            catch { /* best effort cleanup */ }
+        }
+        const client = { captureException: () => { }, captureMessage: () => { }, flush: async () => { }, close: () => { if (active === client)
+                active = undefined; }, stats: () => ({ pending: 0, bytes: 0, dropped: 0, retries: 0, confirmed: 0, disabled: true }) };
+        active = client;
+        return client;
+    }
+}
+function createClient(options, restorers) {
+    const encode = new TextEncoder();
+    let endpoint = '', apiKey = '', disabled = false;
+    try {
+        apiKey = options.apiKey ?? options.publicKey ?? '';
+        const parsed = new URL(options.endpoint === undefined ? DEFAULT_ENDPOINT : options.endpoint);
+        if (parsed.protocol !== 'https:' && !(['localhost', '127.0.0.1', '[::1]'].includes(parsed.hostname) && parsed.protocol === 'http:'))
+            throw Error();
+        if (parsed.username || parsed.password || parsed.search || parsed.hash)
+            throw Error();
+        endpoint = parsed.href;
+        if ((options.apiKey !== undefined && options.publicKey !== undefined) || !/^[A-Za-z0-9_-]{43}$/.test(apiKey) || !/^[A-Za-z0-9_.\/-]{1,128}$/.test(options.release))
+            throw Error();
+    }
+    catch {
+        disabled = true;
+    }
+    if (typeof window === 'undefined' || typeof crypto === 'undefined' || typeof fetch === 'undefined' || typeof AbortController === 'undefined')
+        disabled = true;
+    let queue = [], bytes = 0, dropped = 0, retries = 0, confirmed = 0, closed = false, attempt = 0, nextAttempt = 0;
+    let pending;
+    let controller;
+    const protectedIds = new Set();
+    const disable = () => { disabled = true; queue = []; bytes = 0; protectedIds.clear(); };
+    const expired = () => { const keep = queue.filter(entry => { if (Date.now() - Date.parse(entry.event.occurred_at) > 86400000) {
+        bytes -= entry.size;
+        dropped++;
+        return false;
+    } return true; }); queue = keep; };
+    function capture(message, stack, kind, severity, context) {
+        if (disabled || closed)
+            return;
+        try {
+            let event = { event_id: crypto.randomUUID(), occurred_at: new Date().toISOString(), kind, severity, message: cleanText(message, 1200) || 'Evento sem mensagem', stack: cleanText(stack, 4000), url: cleanUrl(window.location.href), release: options.release, attributes: safeValue(context ?? {}) };
+            if (options.beforeSend) {
+                const candidate = options.beforeSend(event);
+                if (!candidate) {
+                    dropped++;
+                    return;
+                }
+                event = { ...candidate, event_id: event.event_id, occurred_at: event.occurred_at, kind, severity, release: options.release, message: cleanText(String(candidate.message), 1200), stack: cleanText(String(candidate.stack), 4000), url: cleanUrl(String(candidate.url)), attributes: safeValue(candidate.attributes) };
+            }
+            // Reserve room for the server's tenant/application context inside the 8 KiB canonical ceiling.
+            const size = encode.encode(JSON.stringify(event)).length;
+            if (size > 6144) {
+                dropped++;
+                return;
+            }
+            expired();
+            while (queue.length >= 100 || bytes + size > 256 * 1024) {
+                const index = queue.findIndex(e => !protectedIds.has(e.event.event_id));
+                if (index < 0) {
+                    dropped++;
+                    return;
+                }
+                bytes -= queue[index].size;
+                queue.splice(index, 1);
+                dropped++;
+            }
+            queue.push({ event, size });
+            bytes += size;
+            if (queue.length >= 20)
+                void flush();
+        }
+        catch {
+            dropped++;
+        }
+    }
+    function exception(error, context, kind = 'manual') {
+        try {
+            const object = error && typeof error === 'object' ? error : {};
+            const message = Object.getOwnPropertyDescriptor(object, 'message')?.value;
+            let stack = Object.getOwnPropertyDescriptor(object, 'stack')?.value;
+            // Modern engines expose Error.stack lazily. Read that explicit Error field, never arbitrary context getters.
+            if (typeof stack !== 'string' && error instanceof Error) {
+                try {
+                    stack = error.stack;
+                }
+                catch {
+                    stack = '';
+                }
+            }
+            capture(typeof message === 'string' ? message : typeof error === 'string' ? error : 'Erro sem mensagem', typeof stack === 'string' ? stack : '', kind, 'error', context);
+        }
+        catch {
+            dropped++;
+        }
+    }
+    function flush() {
+        try {
+            return send();
+        }
+        catch {
+            disable();
+            return Promise.resolve();
+        }
+    }
+    function send() {
+        if (pending)
+            return pending;
+        if (disabled || closed || Date.now() < nextAttempt)
+            return Promise.resolve();
+        expired();
+        if (!queue.length)
+            return Promise.resolve();
+        const batch = [];
+        let size = 20;
+        for (const entry of queue) {
+            if (batch.length >= 50 || size + entry.size + 1 > 32 * 1024)
+                break;
+            batch.push(entry);
+            size += entry.size + 1;
+            protectedIds.add(entry.event.event_id);
+        }
+        if (!batch.length)
+            return Promise.resolve();
+        pending = Promise.resolve().then(async () => {
+            let timeout;
+            try {
+                const requestController = new AbortController();
+                controller = requestController;
+                const deadline = new Promise((_, reject) => { timeout = setTimeout(() => { try {
+                    requestController.abort();
+                }
+                catch { } reject(Error('timeout')); }, 3000); });
+                const request = Promise.resolve().then(() => fetch(endpoint, { method: 'POST', headers: { 'content-type': 'application/json', 'x-monzori-key': apiKey }, body: JSON.stringify({ events: batch.map(e => e.event) }), credentials: 'omit', referrerPolicy: 'no-referrer', keepalive: true, signal: requestController.signal }));
+                const response = await Promise.race([request, deadline]);
+                if (response.status === 202 || [400, 409, 413, 415, 422].includes(response.status)) {
+                    const ids = new Set(batch.map(e => e.event.event_id));
+                    queue = queue.filter(e => { if (ids.has(e.event.event_id)) {
+                        bytes -= e.size;
+                        return false;
+                    } return true; });
+                    if (response.status === 202)
+                        confirmed += batch.length;
+                    else
+                        dropped += batch.length;
+                    attempt = 0;
+                    nextAttempt = 0;
+                }
+                else if (response.status === 401 || response.status === 403) {
+                    disabled = true;
+                    dropped += queue.length;
+                    queue = [];
+                    bytes = 0;
+                }
+                else
+                    throw Error('retry');
+            }
+            catch {
+                if (!closed) {
+                    retries++;
+                    const delay = Math.min(60000, 1000 * 2 ** Math.min(attempt++, 6));
+                    nextAttempt = Date.now() + Math.max(1000, delay * (.5 + Math.random() * .5));
+                }
+            }
+            finally {
+                try {
+                    clearTimeout(timeout);
+                }
+                catch { }
+                protectedIds.clear();
+                pending = undefined;
+                controller = undefined;
+            }
+        }).catch(() => { disable(); pending = undefined; });
+        return pending;
+    }
+    const client = { captureException: exception, captureMessage: (message, severity = 'info', context) => capture(message, '', 'manual', severity, context), flush,
+        stats: () => ({ pending: queue.length, bytes, dropped, retries, confirmed, disabled }),
+        close: () => { closed = true; try {
+            controller?.abort();
+        }
+        catch { } for (const restore of restorers.splice(0).reverse()) {
+            try {
+                restore();
+            }
+            catch { }
+        } queue = []; bytes = 0; if (active === client)
+            active = undefined; }
+    };
+    if (!disabled) {
+        const onError = (event) => { try {
+            if (event.error)
+                exception(event.error, {}, 'js_error');
+            else if (event.message)
+                capture(event.message, event.filename ? `${event.filename}:${event.lineno}:${event.colno}` : '', 'js_error', 'error');
+        }
+        catch { } };
+        const onRejection = (event) => { try {
+            exception(event.reason, {}, 'promise_rejection');
+        }
+        catch { } };
+        const onVisibility = () => { try {
+            if (document.visibilityState === 'hidden')
+                void flush();
+        }
+        catch { } };
+        restorers.push(() => window.removeEventListener('error', onError));
+        window.addEventListener('error', onError);
+        restorers.push(() => window.removeEventListener('unhandledrejection', onRejection));
+        window.addEventListener('unhandledrejection', onRejection);
+        restorers.push(() => document.removeEventListener('visibilitychange', onVisibility));
+        document.addEventListener('visibilitychange', onVisibility);
+        if (options.console !== false) {
+            let minute = 0, count = 0;
+            const levels = ['error', 'warn', ...(options.console?.log ? ['log'] : []), ...(options.console?.info ? ['info'] : []), ...(options.console?.debug ? ['debug'] : [])];
+            for (const level of levels) {
+                const original = console[level];
+                const wrapped = (...args) => {
+                    const result = Reflect.apply(original, console, args);
+                    try {
+                        const now = Math.floor(Date.now() / 60000);
+                        if (now !== minute) {
+                            minute = now;
+                            count = 0;
+                        }
+                        if (count++ >= 60)
+                            dropped++;
+                        else {
+                            const values = args.slice(0, 20), error = values.find(value => value instanceof Error);
+                            let stack = '';
+                            if (error instanceof Error) {
+                                try {
+                                    stack = error.stack ?? '';
+                                }
+                                catch { /* Optional console stack. */ }
+                            }
+                            capture(values.map(a => typeof a === 'string' ? cleanText(a, 1000) : a instanceof Error ? String(Object.getOwnPropertyDescriptor(a, 'message')?.value ?? '[Error]') : JSON.stringify(safeValue(a))).join(' '), stack, 'console', level === 'log' ? 'info' : level);
+                        }
+                    }
+                    catch {
+                        dropped++;
+                    }
+                    return result;
+                };
+                restorers.push(() => { if (console[level] === wrapped)
+                    console[level] = original; });
+                console[level] = wrapped;
+            }
+        }
+        const timer = setInterval(() => void flush(), 5000);
+        restorers.push(() => clearInterval(timer));
+    }
+    active = client;
+    return client;
+}
+/** @deprecated Use Monzori.start(options) or the named start export. */
+export const initMonzori = start;
+const Monzori = { start };
+export default Monzori;

package/dist/react.d.ts

@@ -0,0 +1,18 @@
+import { Component, type ErrorInfo, type ReactNode } from 'react';
+import type { Client } from './index.js';
+export declare class MonzoriErrorBoundary extends Component<{
+    client: Client;
+    children: ReactNode;
+    fallback?: ReactNode;
+}, {
+    failed: boolean;
+}> {
+    state: {
+        failed: boolean;
+    };
+    static getDerivedStateFromError(): {
+        failed: boolean;
+    };
+    componentDidCatch(error: unknown, info: ErrorInfo): void;
+    render(): ReactNode;
+}

package/dist/react.js

@@ -0,0 +1,13 @@
+import { Component, createElement } from 'react';
+export class MonzoriErrorBoundary extends Component {
+    constructor() {
+        super(...arguments);
+        this.state = { failed: false };
+    }
+    static getDerivedStateFromError() { return { failed: true }; }
+    componentDidCatch(error, info) { try {
+        this.props.client.captureException(error, { componentStack: info.componentStack ?? '' }, 'react_error');
+    }
+    catch { /* Telemetry must not break React's error handling. */ } }
+    render() { return this.state.failed ? this.props.fallback ?? createElement('p', null, 'Não foi possível exibir este conteúdo.') : this.props.children; }
+}

package/dist/sanitize.d.ts

@@ -0,0 +1,6 @@
+export declare function cleanUrl(value: string): string;
+export declare function cleanText(text: string, max?: number): string;
+export declare function safeValue(value: unknown, depth?: number, budget?: {
+    nodes: number;
+    characters: number;
+}): unknown;

package/dist/sanitize.js

@@ -0,0 +1,57 @@
+const sensitive = /password|passwd|secret|authorization|cookie|token|api[_-]?key|localstorage|sessionstorage/i;
+export function cleanUrl(value) { try {
+    const u = new URL(value);
+    return ['http:', 'https:'].includes(u.protocol) ? `${u.origin}${u.pathname}` : '';
+}
+catch {
+    return '';
+} }
+export function cleanText(text, max = 4000) { return text.slice(0, 16000).replace(/https?:\/\/[^\s'"<>\)]+/g, raw => { const suffix = raw.match(/(:\d+:\d+)$/)?.[1] ?? ''; return cleanUrl(suffix ? raw.slice(0, -suffix.length) : raw) + suffix; }).replace(/Bearer\s+[A-Za-z0-9._~+/=-]+/gi, 'Bearer [redacted]').replace(/\b(password|passwd|secret|token|api[_-]?key|authorization|cookie)\s*[:=]\s*(?:"[^"]*"|'[^']*'|[^\s,;]+)/gi, '$1=[redacted]').slice(0, max); }
+export function safeValue(value, depth = 0, budget = { nodes: 128, characters: 2000 }) {
+    try {
+        if (budget.nodes-- <= 0)
+            return '[value limit]';
+        if (depth > 3)
+            return '[depth limit]';
+        if (typeof value === 'string') {
+            if (budget.characters <= 0)
+                return '[string limit]';
+            const text = cleanText(value.slice(0, Math.min(1000, budget.characters)), 1000);
+            budget.characters -= text.length;
+            return text;
+        }
+        if (typeof value === 'number')
+            return Number.isFinite(value) ? value : String(value);
+        if (typeof value === 'boolean' || value === null)
+            return value;
+        if (typeof value === 'function')
+            return '[function]';
+        if (typeof value !== 'object')
+            return cleanText(String(value), 100);
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null && !Array.isArray(value) && !(value instanceof Error))
+            return '[non-plain object]';
+        const keys = [];
+        for (const key in value) {
+            if (Object.prototype.hasOwnProperty.call(value, key))
+                keys.push(key);
+            if (keys.length >= 20)
+                break;
+        }
+        const out = {};
+        for (const key of keys.sort()) {
+            if (budget.nodes <= 0) {
+                out['...'] = '[value limit]';
+                break;
+            }
+            const item = Object.getOwnPropertyDescriptor(value, key);
+            if (!item)
+                continue;
+            out[key.slice(0, 80)] = sensitive.test(key) ? '[redacted]' : 'value' in item ? safeValue(item.value, depth + 1, budget) : '[accessor omitted]';
+        }
+        return out;
+    }
+    catch {
+        return '[unavailable]';
+    }
+}

package/package.json

@@ -1,6 +1,46 @@
 {
-  "name": "@monzori/browser",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+ "name": "@monzori/browser",
+ "version": "0.1.2",
+ "description": "Browser error and console collection SDK for Monzori",
+ "publishConfig": {
+  "access": "public",
+  "registry": "https://registry.npmjs.org/"
+ },
+ "type": "module",
+ "exports": {
+  ".": {
+   "types": "./dist/index.d.ts",
+   "default": "./dist/index.js"
+  },
+  "./react": {
+   "types": "./dist/react.d.ts",
+   "default": "./dist/react.js"
+  }
+ },
+ "files": [
+  "dist/index.js",
+  "dist/index.d.ts",
+  "dist/react.js",
+  "dist/react.d.ts",
+  "dist/sanitize.js",
+  "dist/sanitize.d.ts"
+ ],
+ "sideEffects": false,
+ "scripts": {
+  "build": "tsc -p tsconfig.json",
+  "typecheck": "tsc --noEmit -p tsconfig.json",
+  "test": "vitest run"
+ },
+ "peerDependencies": {
+  "react": ">=18 <20"
+ },
+ "peerDependenciesMeta": {
+  "react": {
+   "optional": true
+  }
+ },
+ "devDependencies": {
+  "@types/react": "^19.2.2",
+  "vitest": "^5.1.0"
+ }
+}