@belvador/react 0.0.0-stage → 0.1.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,59 @@
-# Temporary Holding Version
+# @belvador/react
 
-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 React 18 and 19 apps, sending to your [Belvador](https://belvador.dev) node.
+
+```sh
+npm install @belvador/react
+```
+
+```tsx
+import { createRoot } from "react-dom/client";
+import { ErrorBoundary, init, reactErrorHandler } from "@belvador/react";
+
+init({
+  dsn: "https://<key>@ingest.belvador.dev/<project>",
+  release: import.meta.env.VITE_APP_VERSION,
+  environment: import.meta.env.MODE,
+});
+
+createRoot(document.getElementById("root")!, {
+  // React 19: report errors React handles itself
+  onUncaughtError: reactErrorHandler(),
+  onCaughtError: reactErrorHandler(),
+  onRecoverableError: reactErrorHandler(),
+}).render(
+  <ErrorBoundary fallback={<p>Something went wrong.</p>}>
+    <App />
+  </ErrorBoundary>,
+);
+```
+
+`ErrorBoundary` reports a render error once (with the component stack) and shows `fallback`.
+The report dialog of other SDKs is not available: it would load a script from the network.
+Everything in `@belvador/browser` is exported here too.
+
+## 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.
+
+## 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,25 @@
+import type { ErrorBoundaryProps as EngineErrorBoundaryProps } from "@sentry/react";
+import { type ComponentType, type FC, type ReactElement } from "react";
+import type { BrowserOptions } from "@belvador/browser/internal";
+export type ReactOptions = BrowserOptions;
+export type { FallbackRender } from "@sentry/react";
+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";
+/**
+ * Engine boundary props without the report dialog: it loads a script from
+ * the DSN host, which Belvador never does (spec 01 §3).
+ */
+export type ErrorBoundaryProps = Omit<EngineErrorBoundaryProps, "showDialog" | "dialogOptions">;
+/** Starts error tracking for a React app; returns whether it is running. Never throws. */
+export declare function init(options: ReactOptions): boolean;
+/** Catches render errors in its subtree, reports them once, and shows `fallback`. */
+export declare function ErrorBoundary(props: ErrorBoundaryProps): ReactElement;
+export declare function withErrorBoundary<P extends Record<string, unknown>>(component: ComponentType<P>, options: ErrorBoundaryProps): FC<P>;
+/**
+ * React 19 root error hooks: `createRoot(el, { onUncaughtError: reactErrorHandler(),
+ * onCaughtError: reactErrorHandler(), onRecoverableError: reactErrorHandler() })`.
+ */
+export declare function reactErrorHandler(callback?: (error: unknown, errorInfo: {
+    componentStack?: string;
+}, eventId: string) => void): (error: unknown, errorInfo: {
+    componentStack?: string;
+}) => void;

package/dist/index.js

@@ -0,0 +1,37 @@
+// @belvador/react — errors from React 18/19 apps 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 { ErrorBoundary as EngineErrorBoundary, reactErrorHandler as engineReactErrorHandler, withErrorBoundary as engineWithErrorBoundary, } from "@sentry/react";
+import { createElement } from "react";
+import { initReact } from "./internal.js";
+export { SDK_VERSION, addBreadcrumb, captureException, captureMessage, close, flush, lastEventId, setContext, setTag, setTags, setUser, withScope, } from "@belvador/core";
+function withoutDialog(props) {
+    const { showDialog: _show, dialogOptions: _dialog, ...rest } = props;
+    return rest;
+}
+/** Starts error tracking for a React app; returns whether it is running. Never throws. */
+export function init(options) {
+    return initReact(options, "react");
+}
+/** Catches render errors in its subtree, reports them once, and shows `fallback`. */
+export function ErrorBoundary(props) {
+    return createElement(EngineErrorBoundary, withoutDialog(props));
+}
+export function withErrorBoundary(component, options) {
+    return engineWithErrorBoundary(component, withoutDialog(options));
+}
+/**
+ * React 19 root error hooks: `createRoot(el, { onUncaughtError: reactErrorHandler(),
+ * onCaughtError: reactErrorHandler(), onRecoverableError: reactErrorHandler() })`.
+ */
+export function reactErrorHandler(callback) {
+    const handler = engineReactErrorHandler(callback);
+    return (error, errorInfo) => {
+        try {
+            handler(error, errorInfo);
+        }
+        catch {
+            /* never let reporting break React's own error handling */
+        }
+    };
+}

package/dist/internal.d.ts

@@ -0,0 +1,2 @@
+import { type BrowserOptions } from "@belvador/browser/internal";
+export declare function initReact(options: BrowserOptions, runtime: "react" | "tanstack-start"): boolean;

package/dist/internal.js

@@ -0,0 +1,6 @@
+// Shared with @belvador/tanstack-start: React init under another SDK name. Not a public API.
+import { init as engineInit } from "@sentry/react";
+import { initWith } from "@belvador/browser/internal";
+export function initReact(options, runtime) {
+    return initWith(engineInit, options, runtime);
+}

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@belvador/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Belvador error tracking for React 18/19: ErrorBoundary and root error handlers, 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/browser": "0.1.0",
+    "@belvador/core": "0.1.0",
+    "@sentry/react": "10.76.2"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  }
+}