@belvador/browser 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 Belvador
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This software depends on the Sentry JavaScript SDK (https://github.com/getsentry/sentry-javascript),
+which is distributed under its own MIT License (Copyright (c) Functional Software, Inc. dba Sentry)
+in each of its npm packages. Belvador is not affiliated with or endorsed by Sentry.

package/README.md

@@ -1,3 +1,64 @@
-# Temporary Holding Version
+# @belvador/browser
 
-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.
+Error tracking for browser apps, sending to your [Belvador](https://belvador.dev) node.
+
+```sh
+npm install @belvador/browser
+```
+
+```ts
+import { init, captureException } from "@belvador/browser";
+
+init({
+  dsn: "https://<key>@ingest.belvador.dev/<project>", // Project settings → DSN
+  release: import.meta.env.VITE_APP_VERSION,          // your build or commit id
+  environment: import.meta.env.MODE,
+});
+
+try {
+  risky();
+} catch (error) {
+  captureException(error);
+}
+```
+
+Uncaught errors and unhandled promise rejections are captured automatically. Only
+`window.onerror` and `onunhandledrejection` are hooked by default; breadcrumbs from
+`console`, `fetch`, `xhr`, DOM clicks and history are opt-in:
+`init({ dsn, instrument: { fetch: true, console: true } })`.
+
+Allow the ingest origin in your Content-Security-Policy: `connect-src https://ingest.belvador.dev`.
+
+## What it sends
+
+Errors only (exceptions, messages, breadcrumbs you turn on, attachments if you enable them).
+No tracing, session replay, logs or profiling — those items are dropped inside your app.
+
+Before anything leaves your app the SDK removes `Authorization`, `Cookie` and `Set-Cookie`
+headers, request bodies and cookies, client IP headers, and masks credentials in URLs, query
+strings, tags, contexts, extra data and breadcrumbs (passwords, tokens, API keys, JWTs, card
+numbers, e-mail addresses). Only `user.id` is kept from `setUser`. Your Belvador node scrubs
+again on its own.
+
+Sending never slows down or breaks your app: at most 30 envelopes / 1 MB wait to be sent,
+each attempt times out after 10 s, failed sends retry at most 5 times, `429` rate limits are
+respected, and a revoked key (`401`/`403`) stops sending for the life of the page or isolate.
+Every public function catches its own errors.
+
+## Check the connection
+
+"No errors" is not proof that errors arrive. Call `verifyIntegration()` from `@belvador/browser` once after `init`:
+it sends one marked test error (never an issue), reads it back and resolves to
+`{ outcome: "verified" | "problem" | "unconfirmed", checks, docsUrl, … }`. It never throws.
+Requests the visitor cancelled (`AbortError`) are not reported unless you set `captureAborted: true`.
+See https://belvador.dev/docs/sdk/verify
+
+## Status
+
+`0.x` — used by Belvador's own apps first. The API may still change before `1.0`.
+
+Built on the open-source [Sentry JavaScript SDK](https://github.com/getsentry/sentry-javascript)
+(MIT), pinned to one audited version, with Belvador's privacy and sending rules. Events go only
+to your Belvador DSN; no Sentry account is involved. Belvador is not affiliated with Sentry.
+
+License: MIT · https://belvador.dev

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+import type { VerificationResult, VerifyOptions } from "@belvador/core";
+import { type BrowserOptions } from "./internal.js";
+export type { BrowserOptions } from "./internal.js";
+export { SDK_VERSION, addBreadcrumb, captureException, captureMessage, close, flush, getDiagnostics, lastEventId, setContext, setTag, setTags, setUser, withScope, type BelvadorBreadcrumb, type BelvadorEvent, type BelvadorEventHint, type Diagnostic, type DiagnosticCode, type DiagnosticsSnapshot, type Scope, type SeverityLevel, type VerificationResult, type VerifyOptions, } from "@belvador/core";
+/** Starts error tracking; returns whether it is running. Never throws. */
+export declare function init(options: BrowserOptions): boolean;
+/**
+ * Proves this page reports to Belvador: a captured and an uncaught verification error
+ * (the console shows one "expected" error), read back from Belvador. Run it once after
+ * setup or deploy; never automatic. Always resolves; prints one summary line.
+ */
+export declare function verifyIntegration(options?: VerifyOptions): Promise<VerificationResult>;

package/dist/index.js

@@ -0,0 +1,18 @@
+// @belvador/browser — errors from the browser to your Belvador node.
+// Built on the open-source Sentry JavaScript SDK (MIT), with Belvador's
+// privacy and sending rules. Importing this module does nothing until init().
+import { init as engineInit } from "@sentry/browser";
+import { initWith, verifyBrowser } from "./internal.js";
+export { SDK_VERSION, addBreadcrumb, captureException, captureMessage, close, flush, getDiagnostics, lastEventId, setContext, setTag, setTags, setUser, withScope, } from "@belvador/core";
+/** Starts error tracking; returns whether it is running. Never throws. */
+export function init(options) {
+    return initWith(engineInit, options, "browser");
+}
+/**
+ * Proves this page reports to Belvador: a captured and an uncaught verification error
+ * (the console shows one "expected" error), read back from Belvador. Run it once after
+ * setup or deploy; never automatic. Always resolves; prints one summary line.
+ */
+export function verifyIntegration(options) {
+    return verifyBrowser(options);
+}

package/dist/internal.d.ts

@@ -0,0 +1,30 @@
+import type { BrowserOptions as EngineBrowserOptions } from "@sentry/browser";
+import { type BelvadorOptions, type RuntimeName, type VerificationResult, type VerifyOptions } from "@belvador/core";
+export type BrowserOptions = BelvadorOptions & {
+    /** Breadcrumb sources, all off by default (each one patches a browser API). */
+    instrument?: {
+        console?: boolean;
+        dom?: boolean;
+        fetch?: boolean;
+        xhr?: boolean;
+        history?: boolean;
+    };
+    /** Wrap setTimeout/addEventListener/requestAnimationFrame for better stacks. Default false. */
+    wrapBrowserApis?: boolean;
+    allowUrls?: Array<string | RegExp>;
+    /** Added to the built-in browser-extension filter. */
+    denyUrls?: Array<string | RegExp>;
+};
+/** Engine options for a browser runtime, or null when the SDK must stay off. */
+export declare function browserEngineOptions(options: BrowserOptions, runtime: Extract<RuntimeName, "browser" | "react" | "tanstack-start">): EngineBrowserOptions | null;
+/**
+ * Idempotent init: a second call with the same DSN keeps the running client
+ * (HMR, StrictMode); a different DSN or another SDK's client is never
+ * replaced silently. Returns whether Belvador is running. Never throws.
+ */
+export declare function initWith(engineInit: (options: EngineBrowserOptions) => unknown, options: BrowserOptions, runtime: Extract<RuntimeName, "browser" | "react" | "tanstack-start">): boolean;
+/**
+ * Browser verification (integration-health spec 02 §3): the global error handler is
+ * installed, a captured verification arrives, and an uncaught one does too.
+ */
+export declare function verifyBrowser(options?: VerifyOptions): Promise<VerificationResult>;

package/dist/internal.js

@@ -0,0 +1,85 @@
+// Shared by @belvador/browser, /react and /tanstack-start: browser engine
+// options and the idempotent init. Not a public API.
+import { breadcrumbsIntegration, browserApiErrorsIntegration, dedupeIntegration, eventFiltersIntegration, functionToStringIntegration, getClient, globalHandlersIntegration, httpContextIntegration, linkedErrorsIntegration, } from "@sentry/browser";
+import { BELVADOR_MARKER, buildEngineOptions, isActive, reportDiagnostic, runVerification, warnOnce, } from "@belvador/core";
+const EXTENSION_URLS = [
+    /^chrome-extension:\/\//i,
+    /^moz-extension:\/\//i,
+    /^safari-(web-)?extension:\/\//i,
+];
+/** Engine options for a browser runtime, or null when the SDK must stay off. */
+export function browserEngineOptions(options, runtime) {
+    const base = buildEngineOptions(options, runtime, { browser: true });
+    if (!base)
+        return null;
+    const i = options.instrument ?? {};
+    const crumbs = {
+        console: i.console === true,
+        dom: i.dom === true,
+        fetch: i.fetch === true,
+        xhr: i.xhr === true,
+        history: i.history === true,
+        sentry: false,
+    };
+    // Only window.onerror and onunhandledrejection by default (t4 §A).
+    const integrations = [
+        eventFiltersIntegration(),
+        linkedErrorsIntegration(),
+        dedupeIntegration(),
+        globalHandlersIntegration({ onerror: true, onunhandledrejection: true }),
+        httpContextIntegration(),
+    ];
+    if (crumbs.console || crumbs.dom || crumbs.fetch || crumbs.xhr || crumbs.history)
+        integrations.push(breadcrumbsIntegration(crumbs));
+    if (options.wrapBrowserApis === true)
+        integrations.push(functionToStringIntegration(), browserApiErrorsIntegration());
+    return {
+        ...base,
+        integrations,
+        ...(Array.isArray(options.allowUrls) ? { allowUrls: options.allowUrls } : {}),
+        denyUrls: [...EXTENSION_URLS, ...(Array.isArray(options.denyUrls) ? options.denyUrls : [])],
+    };
+}
+/**
+ * Idempotent init: a second call with the same DSN keeps the running client
+ * (HMR, StrictMode); a different DSN or another SDK's client is never
+ * replaced silently. Returns whether Belvador is running. Never throws.
+ */
+export function initWith(engineInit, options, runtime) {
+    try {
+        const existing = getClient();
+        if (existing) {
+            const prev = existing.getOptions();
+            if (prev[BELVADOR_MARKER] === true && prev["dsn"] === options?.dsn)
+                return true;
+            reportDiagnostic("BLV_INIT_CONFLICT");
+            warnOnce("init skipped: another error-tracking client is already running in this page. Remove the old init so errors are not captured twice.");
+            return false;
+        }
+        const engineOptions = browserEngineOptions(options, runtime);
+        if (!engineOptions)
+            return false;
+        engineInit(engineOptions);
+        return isActive();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Browser verification (integration-health spec 02 §3): the global error handler is
+ * installed, a captured verification arrives, and an uncaught one does too.
+ */
+export function verifyBrowser(options) {
+    return runVerification({
+        surface: "browser",
+        hook: () => {
+            try {
+                return { ok: Boolean(getClient()?.getIntegrationByName("GlobalHandlers")) };
+            }
+            catch {
+                return { ok: false };
+            }
+        },
+    }, options);
+}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@belvador/browser",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Belvador error tracking for the browser: one init, errors only, private by default.",
+  "license": "MIT",
+  "author": "Belvador (https://belvador.dev)",
+  "homepage": "https://belvador.dev",
+  "keywords": [
+    "belvador",
+    "error-tracking",
+    "errors",
+    "monitoring"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "import": "./dist/internal.js",
+      "default": "./dist/internal.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@belvador/core": "0.2.0",
+    "@sentry/browser": "10.76.2"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  }
+}