@flareapp/vue 1.2.0 → 2.0.0

package/.oxlintrc.json

@@ -0,0 +1,8 @@
+{
+    "$schema": "../../node_modules/oxlint/configuration_schema.json",
+    "extends": ["../../.oxlintrc.json"],
+    "plugins": ["vue"],
+    "env": {
+        "browser": true
+    }
+}

package/CHANGELOG.md

@@ -1,12 +1,23 @@
-# @flareapp/vue
+## 2.0.0
 
-## 1.2.0
+### Breaking changes
 
-### Changed
-- Peer dependency on `@flareapp/js` tightened from `^1.0.0` to `^1.2.0`. Consumers must upgrade `@flareapp/js` in lock-step so the v2-wire-format mapper is present at the egress boundary.
+- Bumps peer dependency `@flareapp/js` to `^2.0.0`. See its CHANGELOG for wire format changes.
+- `flareVue` no longer passes a third `extraSolutionParameters` arg to `flare.report`.
+- Vue error context now lands on the report as `attributes['context.custom'].vue.*` (was nested under `context.vue.*`). Key fields: `vue.info`, `vue.errorOrigin`, `vue.componentName`, `vue.componentHierarchy`, `vue.componentHierarchyFrames`, `vue.componentProps`, `vue.route`.
+- `vue-router` moved from a required to an optional peer dependency.
+- Dropped Vue 2 support. Only Vue 3 (`^3.0.0`) is supported.
 
-No functional changes in this package.
+### New
 
-## 1.0.1
-
-Initial release tracked here. Prior history is in git.
+- **`FlareErrorBoundary` component.** Vue equivalent of the React error boundary. Catches errors in its subtree via `onErrorCaptured`, reports to Flare with full Vue context, and renders a `#fallback` slot with `error`, `componentProps`, `componentHierarchy`, `componentHierarchyFrames`, and `resetErrorBoundary`. Supports `resetKeys` for auto-reset and `onReset` callback.
+- **Lifecycle hooks on `flareVue()`.** `beforeEvaluate`, `beforeSubmit`, and `afterSubmit` options give control over the report pipeline at the app level.
+- **`captureWarnings` option.** When enabled, Vue warnings are reported via `flare.reportMessage()` at `warning` level.
+- **Prop serialization.** `attachProps` (boolean), `propsMaxDepth` (number), `propsDenylist` (regex), and `replaceDefaultDenylist` (boolean) control which component props are included in reports. `DEFAULT_PROPS_DENYLIST` is exported.
+- **Component hierarchy frames.** Reports include structured `componentHierarchyFrames` with component name, file path, and serialized props per frame.
+- Route context is automatically captured from `app.config.globalProperties.$router` when an error occurs. No explicit router option needed.
+- Non-`Error` values are coerced to `Error`.
+- Chains existing `app.config.errorHandler` instead of replacing it silently.
+- Duplicate-install guard prevents double-reporting when `app.use(flareVue)` is called more than once.
+- The package self-identifies via `flare.setSdkInfo({ name: '@flareapp/vue', version })` and `flare.setFramework({ name: 'Vue', version: app.version })` on install.
+- New exported types: `ComponentHierarchyFrame`, `ErrorOrigin`, `FlareErrorBoundaryFallbackProps`, `FlareErrorBoundaryHookParams`, `FlareVueContext`, `FlareVueOptions`, `FlareVueWarningContext`, `RouteContext`, `RouteParamValue`, `RouteQueryValue`.

package/README.md

@@ -1,5 +1,41 @@
-# The JavaScript client for Flare to catch frontend errors
+# @flareapp/vue
 
-Read the JavaScript error tracking section in [the Flare documentation](https://flareapp.io/docs/javascript-error-tracking/installation) for more information.
+Vue integration for [Flare](https://flareapp.io) error tracking. Installs a Vue error handler that catches component errors and reports them to Flare with Vue-specific context (component name, lifecycle info).
 
-Flare client: https://www.npmjs.com/package/@flareapp/js
+## Installation
+
+```bash
+npm install @flareapp/vue @flareapp/js
+```
+
+## Quick start
+
+Initialize the Flare client and register the Vue error handler:
+
+```js
+import { createApp } from 'vue';
+import { flare } from '@flareapp/js';
+import { flareVue } from '@flareapp/vue';
+
+import App from './App.vue';
+
+flare.light('YOUR_FLARE_API_KEY');
+
+const app = createApp(App);
+
+flareVue(app);
+
+app.mount('#app');
+```
+
+## Documentation
+
+Full documentation on the Vue error handler and its options is available at [flareapp.io/docs/vue/general/installation](https://flareapp.io/docs/vue/general/installation).
+
+## Compatibility
+
+- Vue 3
+
+## License
+
+The MIT License (MIT). Please see [License File](../../LICENSE.md) for more information.

package/dist/index.cjs

@@ -0,0 +1,445 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+let _flareapp_js = require("@flareapp/js");
+let vue = require("vue");
+
+//#region src/constants.ts
+const PACKAGE_VERSION = typeof process !== "undefined" && typeof process.env?.PACKAGE_VERSION !== "undefined" ? process.env.PACKAGE_VERSION : "?";
+const MAX_HIERARCHY_DEPTH = 50;
+const DEFAULT_PROPS_DENYLIST = /password|passwd|pwd|token|secret|authorization|\bauth\b|bearer|oauth|credentials?|cookie|api[-_]?key|private[-_]?key|session|csrf|xsrf|\bpin\b|\bssn\b|card[-_]?number|\bcvv\b/i;
+function resolveDenylist(custom, replaceDefault = false) {
+	return (0, _flareapp_js.resolveDenylist)(custom, replaceDefault, DEFAULT_PROPS_DENYLIST);
+}
+const MAX_PROP_STRING_LENGTH = 1e3;
+const MAX_PROP_ARRAY_LENGTH = 100;
+const MAX_PROP_OBJECT_KEYS = 100;
+const INFO_TO_ORIGIN = {
+	"setup function": "setup",
+	"render function": "render",
+	"component update": "render",
+	"watcher getter": "watcher",
+	"watcher callback": "watcher",
+	"watcher cleanup function": "watcher",
+	"native event handler": "event",
+	"component event handler": "event",
+	"beforeCreate hook": "lifecycle",
+	"created hook": "lifecycle",
+	"beforeMount hook": "lifecycle",
+	"mounted hook": "lifecycle",
+	"beforeUpdate hook": "lifecycle",
+	"updated hook": "lifecycle",
+	"beforeUnmount hook": "lifecycle",
+	"unmounted hook": "lifecycle",
+	"activated hook": "lifecycle",
+	"deactivated hook": "lifecycle",
+	"errorCaptured hook": "lifecycle",
+	"renderTracked hook": "lifecycle",
+	"renderTriggered hook": "lifecycle",
+	"serverPrefetch hook": "lifecycle",
+	"vnode hook": "lifecycle",
+	"directive hook": "lifecycle",
+	"transition hook": "lifecycle",
+	"ref function": "setup",
+	"async component loader": "setup",
+	"scheduler flush": "render",
+	"app errorHandler": "lifecycle",
+	"app warnHandler": "lifecycle",
+	"app unmount cleanup function": "lifecycle",
+	"0": "setup",
+	"1": "render",
+	"2": "watcher",
+	"3": "watcher",
+	"4": "watcher",
+	"5": "event",
+	"6": "event",
+	"7": "lifecycle",
+	"8": "lifecycle",
+	"9": "lifecycle",
+	"10": "lifecycle",
+	"11": "lifecycle",
+	"12": "setup",
+	"13": "setup",
+	"14": "render",
+	"15": "render",
+	"16": "lifecycle",
+	"sp": "lifecycle",
+	"bc": "lifecycle",
+	"c": "lifecycle",
+	"bm": "lifecycle",
+	"m": "lifecycle",
+	"bu": "lifecycle",
+	"u": "lifecycle",
+	"bum": "lifecycle",
+	"um": "lifecycle",
+	"a": "lifecycle",
+	"da": "lifecycle",
+	"ec": "lifecycle",
+	"rtc": "lifecycle",
+	"rtg": "lifecycle"
+};
+
+//#endregion
+//#region src/getComponentName.ts
+function getComponentName(instance) {
+	if (!instance) return "AnonymousComponent";
+	const options = instance.$options;
+	return options.__name || options.name || "AnonymousComponent";
+}
+
+//#endregion
+//#region src/buildComponentHierarchy.ts
+function buildComponentHierarchy(instance) {
+	const hierarchy = [];
+	let current = instance;
+	while (current && hierarchy.length < MAX_HIERARCHY_DEPTH) {
+		hierarchy.push(getComponentName(current));
+		current = current.$parent;
+	}
+	return hierarchy;
+}
+
+//#endregion
+//#region src/serializeProps.ts
+function serializeProps(value, maxDepth, denylist = DEFAULT_PROPS_DENYLIST) {
+	return serialize(value, 0, maxDepth, /* @__PURE__ */ new WeakSet(), denylist);
+}
+function serialize(value, depth, maxDepth, seen, denylist) {
+	if (value === null) return null;
+	const type = typeof value;
+	if (type === "function") return "[Function]";
+	if (type === "symbol") return "[Symbol]";
+	if (type === "bigint") return value.toString();
+	if (type === "string") return truncateString(value);
+	if (type !== "object") return value;
+	if (seen.has(value)) return "[Circular]";
+	if (Array.isArray(value)) {
+		if (depth > maxDepth) return "[Array]";
+		seen.add(value);
+		const out = (value.length > MAX_PROP_ARRAY_LENGTH ? value.slice(0, MAX_PROP_ARRAY_LENGTH) : value).map((item) => serialize(item, depth + 1, maxDepth, seen, denylist));
+		if (value.length > MAX_PROP_ARRAY_LENGTH) out.push(`[… ${value.length - MAX_PROP_ARRAY_LENGTH} more items]`);
+		seen.delete(value);
+		return out;
+	}
+	if (!isPlainObject(value)) return "[Object]";
+	if (depth > maxDepth) return "[Object]";
+	seen.add(value);
+	const out = {};
+	const keys = Object.keys(value);
+	const limitedKeys = keys.length > MAX_PROP_OBJECT_KEYS ? keys.slice(0, MAX_PROP_OBJECT_KEYS) : keys;
+	for (const key of limitedKeys) {
+		if (denylist.test(key)) {
+			out[key] = "[redacted]";
+			continue;
+		}
+		out[key] = serialize(value[key], depth + 1, maxDepth, seen, denylist);
+	}
+	if (keys.length > MAX_PROP_OBJECT_KEYS) out["…"] = `[${keys.length - MAX_PROP_OBJECT_KEYS} more keys]`;
+	seen.delete(value);
+	return out;
+}
+function truncateString(value) {
+	if (value.length <= MAX_PROP_STRING_LENGTH) return value;
+	return `${value.slice(0, MAX_PROP_STRING_LENGTH)}…[truncated ${value.length - MAX_PROP_STRING_LENGTH} chars]`;
+}
+function isPlainObject(value) {
+	if (value === null || typeof value !== "object") return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === null || prototype === Object.prototype;
+}
+
+//#endregion
+//#region src/buildComponentHierarchyFrames.ts
+function buildComponentHierarchyFrames(instance, options) {
+	const frames = [];
+	let current = instance;
+	while (current && frames.length < MAX_HIERARCHY_DEPTH) {
+		const frameOptions = current.$options;
+		const frame = {
+			component: getComponentName(current),
+			file: frameOptions.__file ?? null
+		};
+		if (options.attachProps && current.$props) frame.props = serializeProps(current.$props, options.propsMaxDepth, options.propsDenylist);
+		frames.push(frame);
+		current = current.$parent;
+	}
+	return frames;
+}
+
+//#endregion
+//#region src/convertToError.ts
+function convertToError(error) {
+	if (error instanceof Error) return error;
+	if (typeof error === "string") return new Error(error);
+	return new Error(String(error));
+}
+
+//#endregion
+//#region src/getErrorOrigin.ts
+function getErrorOrigin(info) {
+	return INFO_TO_ORIGIN[info] ?? "unknown";
+}
+
+//#endregion
+//#region src/getRouteContext.ts
+const ROUTE_PARAMS_DEPTH = 2;
+function getRouteContext(router, options = {}) {
+	if (!router || typeof router !== "object" || !("currentRoute" in router)) return null;
+	const currentRouteRef = router.currentRoute;
+	if (!currentRouteRef || typeof currentRouteRef !== "object" || !("value" in currentRouteRef)) return null;
+	const route = currentRouteRef.value;
+	if (!route || typeof route !== "object") return null;
+	const r = route;
+	const name = r.name;
+	const denylist = options.denylist ?? DEFAULT_PROPS_DENYLIST;
+	const params = r.params && typeof r.params === "object" ? r.params : {};
+	const query = r.query && typeof r.query === "object" ? r.query : {};
+	return {
+		name: typeof name === "string" ? name : typeof name === "symbol" ? name.toString() : null,
+		path: typeof r.path === "string" ? r.path : "",
+		fullPath: typeof r.fullPath === "string" ? (0, _flareapp_js.redactFullPath)(r.fullPath, denylist) : "",
+		params: serializeProps(params, ROUTE_PARAMS_DEPTH, denylist),
+		query: serializeProps(query, ROUTE_PARAMS_DEPTH, denylist),
+		hash: typeof r.hash === "string" ? r.hash : "",
+		matched: Array.isArray(r.matched) ? r.matched.map((record) => {
+			if (!record || typeof record !== "object") return "unknown";
+			const n = record.name;
+			return typeof n === "string" ? n : typeof n === "symbol" ? n.toString() : "unknown";
+		}) : []
+	};
+}
+
+//#endregion
+//#region src/flareVue.ts
+function vueContextToAttributes(context) {
+	const vue = {
+		info: context.vue.info,
+		errorOrigin: context.vue.errorOrigin,
+		componentName: context.vue.componentName,
+		componentHierarchy: context.vue.componentHierarchy,
+		componentHierarchyFrames: context.vue.componentHierarchyFrames
+	};
+	if (context.vue.componentProps) vue.componentProps = context.vue.componentProps;
+	if (context.vue.route) vue.route = context.vue.route;
+	return { "context.custom": {
+		framework: "vue",
+		vue
+	} };
+}
+function vueWarningContextToAttributes(context) {
+	const vue = {
+		type: context.vue.type,
+		info: context.vue.info,
+		componentName: context.vue.componentName,
+		componentTrace: context.vue.componentTrace
+	};
+	if (context.vue.route) vue.route = context.vue.route;
+	return { "context.custom": {
+		framework: "vue",
+		vue
+	} };
+}
+const installedApps = /* @__PURE__ */ new WeakSet();
+const flareVue = (app, options) => {
+	if (installedApps.has(app)) return;
+	installedApps.add(app);
+	_flareapp_js.flare.setSdkInfo({
+		name: "@flareapp/vue",
+		version: PACKAGE_VERSION
+	});
+	_flareapp_js.flare.setFramework({
+		name: "Vue",
+		version: app.version
+	});
+	const attachProps = options?.attachProps ?? false;
+	const propsMaxDepth = options?.propsMaxDepth ?? 2;
+	const propsDenylist = resolveDenylist(options?.propsDenylist, options?.replaceDefaultDenylist);
+	const initialErrorHandler = app.config.errorHandler;
+	app.config.errorHandler = (error, instance, info) => {
+		const errorToReport = convertToError(error);
+		options?.beforeEvaluate?.({
+			error: errorToReport,
+			instance,
+			info
+		});
+		const errorOrigin = getErrorOrigin(info);
+		const componentName = getComponentName(instance);
+		const componentProps = attachProps && instance?.$props ? serializeProps(instance.$props, propsMaxDepth, propsDenylist) : void 0;
+		const componentHierarchy = buildComponentHierarchy(instance);
+		const componentHierarchyFrames = buildComponentHierarchyFrames(instance, {
+			attachProps,
+			propsMaxDepth,
+			propsDenylist
+		});
+		const route = getRouteContext(app.config.globalProperties.$router, { denylist: propsDenylist });
+		const context = { vue: {
+			info,
+			errorOrigin,
+			componentName,
+			...componentProps && { componentProps },
+			componentHierarchy,
+			componentHierarchyFrames,
+			...route && { route }
+		} };
+		const finalContext = options?.beforeSubmit?.({
+			error: errorToReport,
+			instance,
+			info,
+			context
+		}) ?? context;
+		Promise.resolve(_flareapp_js.flare.report(errorToReport, vueContextToAttributes(finalContext))).catch(() => {});
+		options?.afterSubmit?.({
+			error: errorToReport,
+			instance,
+			info,
+			context: finalContext
+		});
+		if (typeof initialErrorHandler === "function") {
+			initialErrorHandler(error, instance, info);
+			return;
+		}
+		console.error(error);
+	};
+	if (options?.captureWarnings) {
+		const initialWarnHandler = app.config.warnHandler;
+		app.config.warnHandler = (msg, instance, trace) => {
+			const componentName = getComponentName(instance);
+			const route = getRouteContext(app.config.globalProperties.$router, { denylist: propsDenylist });
+			const context = { vue: {
+				type: "warning",
+				info: msg,
+				componentName,
+				componentTrace: trace,
+				...route && { route }
+			} };
+			Promise.resolve(_flareapp_js.flare.reportMessage(msg, "warning", vueWarningContextToAttributes(context))).catch(() => {});
+			if (typeof initialWarnHandler === "function") initialWarnHandler(msg, instance, trace);
+		};
+	}
+};
+
+//#endregion
+//#region src/FlareErrorBoundary.ts
+const FlareErrorBoundary = (0, vue.defineComponent)({
+	name: "FlareErrorBoundary",
+	props: {
+		beforeEvaluate: {
+			type: Function,
+			default: void 0
+		},
+		beforeSubmit: {
+			type: Function,
+			default: void 0
+		},
+		afterSubmit: {
+			type: Function,
+			default: void 0
+		},
+		onReset: {
+			type: Function,
+			default: void 0
+		},
+		resetKeys: {
+			type: Array,
+			default: void 0
+		},
+		attachProps: {
+			type: Boolean,
+			default: false
+		},
+		propsMaxDepth: {
+			type: Number,
+			default: 2
+		},
+		propsDenylist: {
+			type: RegExp,
+			default: void 0
+		},
+		replaceDefaultDenylist: {
+			type: Boolean,
+			default: false
+		}
+	},
+	setup(props, { slots }) {
+		const currentInstance = (0, vue.getCurrentInstance)();
+		const error = (0, vue.ref)(null);
+		const componentProps = (0, vue.ref)(void 0);
+		const componentHierarchy = (0, vue.ref)([]);
+		const componentHierarchyFrames = (0, vue.ref)([]);
+		const resetErrorBoundary = () => {
+			props.onReset?.(error.value);
+			error.value = null;
+			componentProps.value = void 0;
+			componentHierarchy.value = [];
+			componentHierarchyFrames.value = [];
+		};
+		(0, vue.watch)(() => props.resetKeys, (nextKeys, prevKeys) => {
+			if (error.value === null || !nextKeys || !prevKeys) return;
+			const lengthChanged = prevKeys.length !== nextKeys.length;
+			const valuesChanged = nextKeys.some((key, i) => !Object.is(key, prevKeys[i]));
+			if (lengthChanged || valuesChanged) resetErrorBoundary();
+		});
+		(0, vue.onErrorCaptured)((currentError, instance, info) => {
+			const errorToReport = convertToError(currentError);
+			props.beforeEvaluate?.({
+				error: errorToReport,
+				instance,
+				info
+			});
+			const resolvedDenylist = resolveDenylist(props.propsDenylist, props.replaceDefaultDenylist);
+			const hierarchy = buildComponentHierarchy(instance);
+			const hierarchyFrames = buildComponentHierarchyFrames(instance, {
+				attachProps: props.attachProps,
+				propsMaxDepth: props.propsMaxDepth,
+				propsDenylist: resolvedDenylist
+			});
+			const componentName = getComponentName(instance);
+			error.value = errorToReport;
+			const instanceProps = props.attachProps && instance?.$props ? serializeProps(instance.$props, props.propsMaxDepth, resolvedDenylist) : void 0;
+			const errorOrigin = getErrorOrigin(info);
+			const route = getRouteContext(currentInstance?.appContext.config.globalProperties.$router, { denylist: resolvedDenylist });
+			const context = { vue: {
+				info,
+				errorOrigin,
+				...route && { route },
+				componentName,
+				...instanceProps && { componentProps: instanceProps },
+				componentHierarchy: hierarchy,
+				componentHierarchyFrames: hierarchyFrames
+			} };
+			const finalContext = props.beforeSubmit?.({
+				error: errorToReport,
+				instance,
+				info,
+				context
+			}) ?? context;
+			componentProps.value = finalContext.vue.componentProps;
+			componentHierarchy.value = finalContext.vue.componentHierarchy;
+			componentHierarchyFrames.value = finalContext.vue.componentHierarchyFrames;
+			Promise.resolve(_flareapp_js.flare.report(errorToReport, vueContextToAttributes(finalContext))).catch(() => {});
+			props.afterSubmit?.({
+				error: errorToReport,
+				instance,
+				info,
+				context: finalContext
+			});
+			return false;
+		});
+		return () => {
+			if (error.value !== null) {
+				if (slots.fallback) return slots.fallback({
+					error: error.value,
+					...componentProps.value && { componentProps: componentProps.value },
+					componentHierarchy: componentHierarchy.value,
+					componentHierarchyFrames: componentHierarchyFrames.value,
+					resetErrorBoundary
+				});
+				return null;
+			}
+			return slots.default?.();
+		};
+	}
+});
+
+//#endregion
+exports.DEFAULT_PROPS_DENYLIST = DEFAULT_PROPS_DENYLIST;
+exports.FlareErrorBoundary = FlareErrorBoundary;
+exports.flareVue = flareVue;