@belvador/browser 0.1.0 → 0.3.0

package/README.md

@@ -32,7 +32,7 @@ Allow the ingest origin in your Content-Security-Policy: `connect-src https://in
 ## 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.
+No spans, session replay, logs, profiling or check-ins — 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
@@ -45,6 +45,24 @@ each attempt times out after 10 s, failed sends retry at most 5 times, `429` rat
 respected, and a revoked key (`401`/`403`) stops sending for the life of the page or isolate.
 Every public function catches its own errors.
 
+## Link requests with one trace
+
+Off by default. `tracePropagation: { targets: [/^\/api\//, "https://api.example.com"] }` adds
+`traceparent` and `sentry-trace` headers to `fetch` calls to those URLs (relative patterns
+match same-origin paths), so a browser error and the server error behind the same request
+share one trace id. The receiving API must allow these headers in CORS. No spans or
+transactions are sent; `baggage` only with `baggage: true`. A View Transition the browser
+skipped on purpose is not reported unless you set `captureViewTransitionSkips: true`.
+See https://belvador.dev/docs/sdk/tracing
+
+## 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`.

package/dist/index.d.ts

@@ -1,5 +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, lastEventId, setContext, setTag, setTags, setUser, withScope, type BelvadorBreadcrumb, type BelvadorEvent, type BelvadorEventHint, type Scope, type SeverityLevel, } from "@belvador/core";
+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

@@ -2,9 +2,17 @@
 // 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 } from "./internal.js";
-export { SDK_VERSION, addBreadcrumb, captureException, captureMessage, close, flush, lastEventId, setContext, setTag, setTags, setUser, withScope, } from "@belvador/core";
+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

@@ -1,5 +1,5 @@
 import type { BrowserOptions as EngineBrowserOptions } from "@sentry/browser";
-import { type BelvadorOptions, type RuntimeName } from "@belvador/core";
+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?: {
@@ -23,3 +23,8 @@ export declare function browserEngineOptions(options: BrowserOptions, runtime: E
  * 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

@@ -1,7 +1,7 @@
 // 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, warnOnce, } from "@belvador/core";
+import { BELVADOR_MARKER, TRACE_OPTION, buildEngineOptions, installTracePropagation, isActive, reportDiagnostic, runVerification, warnOnce, } from "@belvador/core";
 const EXTENSION_URLS = [
     /^chrome-extension:\/\//i,
     /^moz-extension:\/\//i,
@@ -52,6 +52,7 @@ export function initWith(engineInit, options, runtime) {
             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;
         }
@@ -59,9 +60,29 @@ export function initWith(engineInit, options, runtime) {
         if (!engineOptions)
             return false;
         engineInit(engineOptions);
+        // Only when the app asked for it (spec 06 §5): fetch to its targets carries the trace.
+        if (engineOptions[TRACE_OPTION])
+            installTracePropagation();
         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,6 @@
 {
   "name": "@belvador/browser",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Belvador error tracking for the browser: one init, errors only, private by default.",
   "license": "MIT",
   "author": "Belvador (https://belvador.dev)",
@@ -37,7 +37,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@belvador/core": "0.1.0",
+    "@belvador/core": "0.3.0",
     "@sentry/browser": "10.76.2"
   },
   "publishConfig": {