@flareapp/core 2.5.0 → 2.6.0

package/dist/index.cjs

@@ -30,7 +30,7 @@ let error_stack_parser = require("error-stack-parser");
 error_stack_parser = __toESM(error_stack_parser);
 
 //#region src/env/index.ts
-const CLIENT_VERSION = typeof process !== "undefined" && true ? "2.5.0" : "?";
+const CLIENT_VERSION = typeof process !== "undefined" && true ? "2.6.0" : "?";
 const KEY = typeof FLARE_JS_KEY === "undefined" ? "" : FLARE_JS_KEY;
 const SOURCEMAP_VERSION = typeof FLARE_SOURCEMAP_VERSION === "undefined" ? "" : FLARE_SOURCEMAP_VERSION;
 
@@ -171,6 +171,49 @@ function safeDecode(value) {
 	}
 }
 
+//#endregion
+//#region src/util/rejection.ts
+/** Best-effort human-readable description of an arbitrary rejection reason. */
+function describeRejectionReason(reason) {
+	if (typeof reason === "string") return reason;
+	if (reason && typeof reason === "object") {
+		const message = reason.message;
+		if (typeof message === "string" && message) return message;
+		try {
+			return JSON.stringify(reason);
+		} catch {
+			return "Unhandled promise rejection (non-serializable reason)";
+		}
+	}
+	return String(reason);
+}
+function hasStack$1(reason) {
+	return !!reason && typeof reason === "object" && typeof reason.stack === "string";
+}
+/**
+* Route a rejection reason to the reporter: an Error (or any stack-bearing
+* object) goes to `reportSilently` so the STACK survives; only a stackless
+* reason falls back to `reportUnhandledRejection` (string message, empty-stack
+* `UnhandledRejection` class). Any rejection from `reportUnhandledRejection`'s
+* returned promise is swallowed so a transport failure cannot itself surface as
+* an unhandled rejection. `reportSilently` is assumed not to throw synchronously
+* (core's does its work asynchronously); it is intentionally not wrapped, so a
+* synchronous throw there would propagate.
+*/
+function routeRejection(reporter, reason) {
+	if (reason instanceof Error) {
+		reporter.reportSilently(reason);
+		return;
+	}
+	if (hasStack$1(reason)) {
+		const error = new Error(describeRejectionReason(reason));
+		error.stack = reason.stack;
+		reporter.reportSilently(error);
+		return;
+	}
+	Promise.resolve(reporter.reportUnhandledRejection(describeRejectionReason(reason))).catch(() => {});
+}
+
 //#endregion
 //#region src/api/Api.ts
 var Api = class {
@@ -500,6 +543,39 @@ function partitionAttributes(attributes) {
 //#endregion
 //#region src/Scope.ts
 /**
+* Maps each `User` identity field to the flat report attribute key it projects to.
+* `Flare.setUser`'s set pass writes through these so the literal key strings live in
+* exactly one place; `USER_IDENTITY_KEYS` (the clear pass) derives from them, so adding
+* a field here can never silently leave the clear pass out of date.
+*/
+const USER_FIELD_KEYS = {
+	id: "user.id",
+	email: "user.email",
+	fullName: "user.full_name",
+	ipAddress: "client.address"
+};
+/**
+* The report attribute keys that `Flare.setUser` owns: the four projected identity
+* fields plus the `user.attributes` bag for extras. Single source of truth so the
+* clear pass and the set pass in `setUser` cannot drift, and so consumers that must
+* stamp identity outside core's report pipeline (Electron's forwarded-renderer path)
+* pick up the exact same set instead of re-hardcoding it.
+*/
+const USER_IDENTITY_KEYS = [...Object.values(USER_FIELD_KEYS), "user.attributes"];
+/**
+* Pick the user-identity attributes currently set on a scope. Used where identity must
+* be copied onto a report that does not flow through `Flare.report()` (which would
+* otherwise spread `pendingAttributes` automatically).
+*/
+function userIdentityAttributes(scope) {
+	const attrs = {};
+	for (const key of USER_IDENTITY_KEYS) {
+		const value = scope.pendingAttributes[key];
+		if (value !== void 0) attrs[key] = value;
+	}
+	return attrs;
+}
+/**
 * Holds the per-call mutable state that used to live on the `Flare` instance:
 * breadcrumbs (`glows`), custom attributes (`pendingAttributes`), and the
 * current entry-point handler.
@@ -516,9 +592,9 @@ function partitionAttributes(attributes) {
 * holding the state directly, so the per-request behavior comes from the
 * provider, not from the class itself.
 *
-* `NodeScope` (in `@flareapp/node`) extends this with two more buckets:
-* `request` (HTTP method, path, headers) and `user` (id, email, ...). Browser
-* does not need those.
+* `NodeScope` (in `@flareapp/node`) extends this with a `request` bucket
+* (HTTP method, path, headers). User identity is written to `pendingAttributes`
+* by `Flare.setUser`, so it needs no dedicated field. Browser does not need `request`.
 */
 var Scope = class {
 	glows = [];
@@ -641,18 +717,24 @@ function createStackTrace(error, debug, fileReader) {
 			return resolve([fallbackFrame("stacktrace could not be parsed")]);
 		}
 		Promise.all(parsedFrames.map((frame) => {
-			return getCodeSnippet(fileReader, frame.fileName, frame.lineNumber, frame.columnNumber).then((snippet) => ({
+			const fileName = normalizeFileName(frame.fileName);
+			return getCodeSnippet(fileReader, fileName, frame.lineNumber, frame.columnNumber).then((snippet) => ({
 				lineNumber: frame.lineNumber || 1,
 				columnNumber: frame.columnNumber || 1,
 				method: frame.functionName || "Anonymous or unknown function",
-				file: frame.fileName || "Unknown file",
+				file: fileName || "Unknown file",
 				codeSnippet: snippet.codeSnippet,
 				class: "",
-				isApplicationFrame: isApplicationFrame(frame.fileName)
+				isApplicationFrame: isApplicationFrame(fileName)
 			}));
 		})).then(resolve);
 	});
 }
+const HERMES_ADDRESS_PREFIX = "address at ";
+function normalizeFileName(fileName) {
+	if (fileName?.startsWith(HERMES_ADDRESS_PREFIX)) return fileName.slice(11);
+	return fileName;
+}
 function fallbackFrame(reason) {
 	return {
 		lineNumber: 0,
@@ -975,6 +1057,26 @@ var Flare = class {
 		this.scopeProvider.active().setAttribute(`context.${groupName}`, value);
 		return this;
 	}
+	/**
+	* Attach an identified user to the active scope. Fields are projected to the
+	* keys the Flare backend reads: `user.id`, `user.email`, `user.full_name`,
+	* and `client.address`. Any extra keys are bundled into `user.attributes`.
+	* Pass `null` to clear the user. Scope-aware: in Node this targets the
+	* per-request scope via the scope provider.
+	*/
+	setUser(user) {
+		const scope = this.scopeProvider.active();
+		for (const key of USER_IDENTITY_KEYS) delete scope.pendingAttributes[key];
+		if (!user) return this;
+		const { id, email, fullName, ipAddress, ...rest } = user;
+		if (id !== void 0 && id !== null) scope.setAttribute(USER_FIELD_KEYS.id, String(id));
+		if (email !== void 0) scope.setAttribute(USER_FIELD_KEYS.email, email);
+		if (fullName !== void 0) scope.setAttribute(USER_FIELD_KEYS.fullName, fullName);
+		if (ipAddress !== void 0) scope.setAttribute(USER_FIELD_KEYS.ipAddress, ipAddress);
+		const extras = Object.fromEntries(Object.entries(rest).filter(([, value]) => value !== void 0));
+		if (Object.keys(extras).length > 0) scope.setAttribute("user.attributes", extras);
+		return this;
+	}
 	setEntryPoint(handler) {
 		this.scopeProvider.active().entryPoint = handler;
 		return this;
@@ -1138,10 +1240,12 @@ exports.Logger = Logger;
 exports.NoopFlushScheduler = NoopFlushScheduler;
 exports.NullFileReader = NullFileReader;
 exports.Scope = Scope;
+exports.USER_IDENTITY_KEYS = USER_IDENTITY_KEYS;
 exports.assert = assert;
 exports.assertKey = assertKey;
 exports.convertToError = convertToError;
 exports.createStackTrace = createStackTrace;
+exports.describeRejectionReason = describeRejectionReason;
 exports.extractCode = extractCode;
 exports.flatJsonStringify = flatJsonStringify;
 exports.getCodeSnippet = getCodeSnippet;
@@ -1149,4 +1253,6 @@ exports.glowsToEvents = glowsToEvents;
 exports.now = now;
 exports.readLinesFromFile = readLinesFromFile;
 exports.redactUrlQuery = redactUrlQuery;
-exports.resolveDenylist = resolveDenylist;
+exports.resolveDenylist = resolveDenylist;
+exports.routeRejection = routeRejection;
+exports.userIdentityAttributes = userIdentityAttributes;

package/dist/index.d.cts

@@ -4,6 +4,23 @@ type AttributeValue = string | number | boolean | null | AttributeValue[] | {
   [key: string]: AttributeValue;
 };
 type Attributes = Record<string, AttributeValue>;
+/**
+ * An identified user passed to `Flare.setUser`. The four known fields project to the
+ * report keys the Flare backend reads: `id`→`user.id`, `email`→`user.email`,
+ * `fullName`→`user.full_name`, `ipAddress`→`client.address`. Any OTHER key is bundled
+ * into `user.attributes`.
+ *
+ * Caveat: the open index signature means a misspelled known field (e.g. `fullname` or
+ * `full_name` instead of `fullName`) does NOT raise a type error — it silently lands in
+ * `user.attributes` rather than the identity key. Spell the four known fields exactly.
+ */
+type User = {
+  id?: string | number;
+  email?: string;
+  fullName?: string;
+  ipAddress?: string;
+  [key: string]: AttributeValue | undefined;
+};
 type Config = {
   key: string | null;
   version: string;
@@ -168,6 +185,34 @@ declare const DEFAULT_URL_DENYLIST: RegExp;
 declare function resolveDenylist(custom?: RegExp, replaceDefault?: boolean, defaultDenylist?: RegExp): RegExp;
 declare function redactUrlQuery(fullPath: string, denylist?: RegExp): string;
 //#endregion
+//#region src/util/rejection.d.ts
+/**
+ * Shared unhandled-rejection routing. A rejection "reason" can be anything a
+ * promise was rejected with: an Error, an Error-like object carrying a `.stack`,
+ * a string, or a plain object. The browser `unhandledrejection` listener
+ * (`@flareapp/js`) and the React Native engine rejection tracker
+ * (`@flareapp/react-native`) need the SAME routing so a report looks identical
+ * across SDKs, so it lives here instead of being copy-pasted (and drifting) per
+ * client.
+ */
+type RejectionReporter = {
+  reportSilently: (error: Error) => void;
+  reportUnhandledRejection: (message: string) => unknown;
+};
+/** Best-effort human-readable description of an arbitrary rejection reason. */
+declare function describeRejectionReason(reason: unknown): string;
+/**
+ * Route a rejection reason to the reporter: an Error (or any stack-bearing
+ * object) goes to `reportSilently` so the STACK survives; only a stackless
+ * reason falls back to `reportUnhandledRejection` (string message, empty-stack
+ * `UnhandledRejection` class). Any rejection from `reportUnhandledRejection`'s
+ * returned promise is swallowed so a transport failure cannot itself surface as
+ * an unhandled rejection. `reportSilently` is assumed not to throw synchronously
+ * (core's does its work asynchronously); it is intentionally not wrapped, so a
+ * synchronous throw there would propagate.
+ */
+declare function routeRejection(reporter: RejectionReporter, reason: unknown): void;
+//#endregion
 //#region src/api/Api.d.ts
 declare class Api {
   report(report: Report, url: string, key: string | null, reportBrowserExtensionErrors: boolean, debug?: boolean): Promise<void>;
@@ -236,6 +281,20 @@ declare class Logger {
 }
 //#endregion
 //#region src/Scope.d.ts
+/**
+ * The report attribute keys that `Flare.setUser` owns: the four projected identity
+ * fields plus the `user.attributes` bag for extras. Single source of truth so the
+ * clear pass and the set pass in `setUser` cannot drift, and so consumers that must
+ * stamp identity outside core's report pipeline (Electron's forwarded-renderer path)
+ * pick up the exact same set instead of re-hardcoding it.
+ */
+declare const USER_IDENTITY_KEYS: readonly [...("user.id" | "user.email" | "user.full_name" | "client.address")[], "user.attributes"];
+/**
+ * Pick the user-identity attributes currently set on a scope. Used where identity must
+ * be copied onto a report that does not flow through `Flare.report()` (which would
+ * otherwise spread `pendingAttributes` automatically).
+ */
+declare function userIdentityAttributes(scope: Scope): Attributes;
 /**
  * Holds the per-call mutable state that used to live on the `Flare` instance:
  * breadcrumbs (`glows`), custom attributes (`pendingAttributes`), and the
@@ -253,9 +312,9 @@ declare class Logger {
  * holding the state directly, so the per-request behavior comes from the
  * provider, not from the class itself.
  *
- * `NodeScope` (in `@flareapp/node`) extends this with two more buckets:
- * `request` (HTTP method, path, headers) and `user` (id, email, ...). Browser
- * does not need those.
+ * `NodeScope` (in `@flareapp/node`) extends this with a `request` bucket
+ * (HTTP method, path, headers). User identity is written to `pendingAttributes`
+ * by `Flare.setUser`, so it needs no dedicated field. Browser does not need `request`.
  */
 declare class Scope {
   glows: Glow[];
@@ -494,6 +553,14 @@ declare class Flare {
   clearGlows(): this;
   addContext(name: string, value: AttributeValue): this;
   addContextGroup(groupName: string, value: Record<string, AttributeValue>): this;
+  /**
+   * Attach an identified user to the active scope. Fields are projected to the
+   * keys the Flare backend reads: `user.id`, `user.email`, `user.full_name`,
+   * and `client.address`. Any extra keys are bundled into `user.attributes`.
+   * Pass `null` to clear the user. Scope-aware: in Node this targets the
+   * per-request scope via the scope provider.
+   */
+  setUser(user: User | null): this;
   setEntryPoint(handler: EntryPointHandler): this;
   setSdkInfo(info: SdkInfo): this;
   setFramework(framework: Framework): this;
@@ -541,4 +608,4 @@ declare class NullFileReader implements FileReader {
 //#region src/stacktrace/createStackTrace.d.ts
 declare function createStackTrace(error: Error, debug: boolean, fileReader: FileReader): Promise<Array<StackFrame>>;
 //#endregion
-export { type AnyValue, Api, type AttributeValue, type Attributes, type BufferedLog, type Config, type ContextCollector, DEFAULT_URL_DENYLIST, type EntryPointHandler, type FileReader, Flare, type FlushFn, type FlushScheduler, type Framework, GlobalScopeProvider, type Glow, type KeyValue, Logger, type LoggerDeps, type LogsEnvelope, type MessageLevel, NoopFlushScheduler, NullFileReader, type OtelLogRecord, type OverriddenGrouping, type Report, Scope, type ScopeProvider, type SdkInfo, type SpanEvent, type StackFrame, assert, assertKey, convertToError, createStackTrace, extractCode, flatJsonStringify, getCodeSnippet, glowsToEvents, now, readLinesFromFile, redactUrlQuery, resolveDenylist };
+export { type AnyValue, Api, type AttributeValue, type Attributes, type BufferedLog, type Config, type ContextCollector, DEFAULT_URL_DENYLIST, type EntryPointHandler, type FileReader, Flare, type FlushFn, type FlushScheduler, type Framework, GlobalScopeProvider, type Glow, type KeyValue, Logger, type LoggerDeps, type LogsEnvelope, type MessageLevel, NoopFlushScheduler, NullFileReader, type OtelLogRecord, type OverriddenGrouping, type RejectionReporter, type Report, Scope, type ScopeProvider, type SdkInfo, type SpanEvent, type StackFrame, USER_IDENTITY_KEYS, type User, assert, assertKey, convertToError, createStackTrace, describeRejectionReason, extractCode, flatJsonStringify, getCodeSnippet, glowsToEvents, now, readLinesFromFile, redactUrlQuery, resolveDenylist, routeRejection, userIdentityAttributes };

package/dist/index.d.mts

@@ -4,6 +4,23 @@ type AttributeValue = string | number | boolean | null | AttributeValue[] | {
   [key: string]: AttributeValue;
 };
 type Attributes = Record<string, AttributeValue>;
+/**
+ * An identified user passed to `Flare.setUser`. The four known fields project to the
+ * report keys the Flare backend reads: `id`→`user.id`, `email`→`user.email`,
+ * `fullName`→`user.full_name`, `ipAddress`→`client.address`. Any OTHER key is bundled
+ * into `user.attributes`.
+ *
+ * Caveat: the open index signature means a misspelled known field (e.g. `fullname` or
+ * `full_name` instead of `fullName`) does NOT raise a type error — it silently lands in
+ * `user.attributes` rather than the identity key. Spell the four known fields exactly.
+ */
+type User = {
+  id?: string | number;
+  email?: string;
+  fullName?: string;
+  ipAddress?: string;
+  [key: string]: AttributeValue | undefined;
+};
 type Config = {
   key: string | null;
   version: string;
@@ -168,6 +185,34 @@ declare const DEFAULT_URL_DENYLIST: RegExp;
 declare function resolveDenylist(custom?: RegExp, replaceDefault?: boolean, defaultDenylist?: RegExp): RegExp;
 declare function redactUrlQuery(fullPath: string, denylist?: RegExp): string;
 //#endregion
+//#region src/util/rejection.d.ts
+/**
+ * Shared unhandled-rejection routing. A rejection "reason" can be anything a
+ * promise was rejected with: an Error, an Error-like object carrying a `.stack`,
+ * a string, or a plain object. The browser `unhandledrejection` listener
+ * (`@flareapp/js`) and the React Native engine rejection tracker
+ * (`@flareapp/react-native`) need the SAME routing so a report looks identical
+ * across SDKs, so it lives here instead of being copy-pasted (and drifting) per
+ * client.
+ */
+type RejectionReporter = {
+  reportSilently: (error: Error) => void;
+  reportUnhandledRejection: (message: string) => unknown;
+};
+/** Best-effort human-readable description of an arbitrary rejection reason. */
+declare function describeRejectionReason(reason: unknown): string;
+/**
+ * Route a rejection reason to the reporter: an Error (or any stack-bearing
+ * object) goes to `reportSilently` so the STACK survives; only a stackless
+ * reason falls back to `reportUnhandledRejection` (string message, empty-stack
+ * `UnhandledRejection` class). Any rejection from `reportUnhandledRejection`'s
+ * returned promise is swallowed so a transport failure cannot itself surface as
+ * an unhandled rejection. `reportSilently` is assumed not to throw synchronously
+ * (core's does its work asynchronously); it is intentionally not wrapped, so a
+ * synchronous throw there would propagate.
+ */
+declare function routeRejection(reporter: RejectionReporter, reason: unknown): void;
+//#endregion
 //#region src/api/Api.d.ts
 declare class Api {
   report(report: Report, url: string, key: string | null, reportBrowserExtensionErrors: boolean, debug?: boolean): Promise<void>;
@@ -236,6 +281,20 @@ declare class Logger {
 }
 //#endregion
 //#region src/Scope.d.ts
+/**
+ * The report attribute keys that `Flare.setUser` owns: the four projected identity
+ * fields plus the `user.attributes` bag for extras. Single source of truth so the
+ * clear pass and the set pass in `setUser` cannot drift, and so consumers that must
+ * stamp identity outside core's report pipeline (Electron's forwarded-renderer path)
+ * pick up the exact same set instead of re-hardcoding it.
+ */
+declare const USER_IDENTITY_KEYS: readonly [...("user.id" | "user.email" | "user.full_name" | "client.address")[], "user.attributes"];
+/**
+ * Pick the user-identity attributes currently set on a scope. Used where identity must
+ * be copied onto a report that does not flow through `Flare.report()` (which would
+ * otherwise spread `pendingAttributes` automatically).
+ */
+declare function userIdentityAttributes(scope: Scope): Attributes;
 /**
  * Holds the per-call mutable state that used to live on the `Flare` instance:
  * breadcrumbs (`glows`), custom attributes (`pendingAttributes`), and the
@@ -253,9 +312,9 @@ declare class Logger {
  * holding the state directly, so the per-request behavior comes from the
  * provider, not from the class itself.
  *
- * `NodeScope` (in `@flareapp/node`) extends this with two more buckets:
- * `request` (HTTP method, path, headers) and `user` (id, email, ...). Browser
- * does not need those.
+ * `NodeScope` (in `@flareapp/node`) extends this with a `request` bucket
+ * (HTTP method, path, headers). User identity is written to `pendingAttributes`
+ * by `Flare.setUser`, so it needs no dedicated field. Browser does not need `request`.
  */
 declare class Scope {
   glows: Glow[];
@@ -494,6 +553,14 @@ declare class Flare {
   clearGlows(): this;
   addContext(name: string, value: AttributeValue): this;
   addContextGroup(groupName: string, value: Record<string, AttributeValue>): this;
+  /**
+   * Attach an identified user to the active scope. Fields are projected to the
+   * keys the Flare backend reads: `user.id`, `user.email`, `user.full_name`,
+   * and `client.address`. Any extra keys are bundled into `user.attributes`.
+   * Pass `null` to clear the user. Scope-aware: in Node this targets the
+   * per-request scope via the scope provider.
+   */
+  setUser(user: User | null): this;
   setEntryPoint(handler: EntryPointHandler): this;
   setSdkInfo(info: SdkInfo): this;
   setFramework(framework: Framework): this;
@@ -541,4 +608,4 @@ declare class NullFileReader implements FileReader {
 //#region src/stacktrace/createStackTrace.d.ts
 declare function createStackTrace(error: Error, debug: boolean, fileReader: FileReader): Promise<Array<StackFrame>>;
 //#endregion
-export { type AnyValue, Api, type AttributeValue, type Attributes, type BufferedLog, type Config, type ContextCollector, DEFAULT_URL_DENYLIST, type EntryPointHandler, type FileReader, Flare, type FlushFn, type FlushScheduler, type Framework, GlobalScopeProvider, type Glow, type KeyValue, Logger, type LoggerDeps, type LogsEnvelope, type MessageLevel, NoopFlushScheduler, NullFileReader, type OtelLogRecord, type OverriddenGrouping, type Report, Scope, type ScopeProvider, type SdkInfo, type SpanEvent, type StackFrame, assert, assertKey, convertToError, createStackTrace, extractCode, flatJsonStringify, getCodeSnippet, glowsToEvents, now, readLinesFromFile, redactUrlQuery, resolveDenylist };
+export { type AnyValue, Api, type AttributeValue, type Attributes, type BufferedLog, type Config, type ContextCollector, DEFAULT_URL_DENYLIST, type EntryPointHandler, type FileReader, Flare, type FlushFn, type FlushScheduler, type Framework, GlobalScopeProvider, type Glow, type KeyValue, Logger, type LoggerDeps, type LogsEnvelope, type MessageLevel, NoopFlushScheduler, NullFileReader, type OtelLogRecord, type OverriddenGrouping, type RejectionReporter, type Report, Scope, type ScopeProvider, type SdkInfo, type SpanEvent, type StackFrame, USER_IDENTITY_KEYS, type User, assert, assertKey, convertToError, createStackTrace, describeRejectionReason, extractCode, flatJsonStringify, getCodeSnippet, glowsToEvents, now, readLinesFromFile, redactUrlQuery, resolveDenylist, routeRejection, userIdentityAttributes };

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import ErrorStackParser from "error-stack-parser";
 
 //#region src/env/index.ts
-const CLIENT_VERSION = typeof process !== "undefined" && true ? "2.5.0" : "?";
+const CLIENT_VERSION = typeof process !== "undefined" && true ? "2.6.0" : "?";
 const KEY = typeof FLARE_JS_KEY === "undefined" ? "" : FLARE_JS_KEY;
 const SOURCEMAP_VERSION = typeof FLARE_SOURCEMAP_VERSION === "undefined" ? "" : FLARE_SOURCEMAP_VERSION;
 
@@ -142,6 +142,49 @@ function safeDecode(value) {
 	}
 }
 
+//#endregion
+//#region src/util/rejection.ts
+/** Best-effort human-readable description of an arbitrary rejection reason. */
+function describeRejectionReason(reason) {
+	if (typeof reason === "string") return reason;
+	if (reason && typeof reason === "object") {
+		const message = reason.message;
+		if (typeof message === "string" && message) return message;
+		try {
+			return JSON.stringify(reason);
+		} catch {
+			return "Unhandled promise rejection (non-serializable reason)";
+		}
+	}
+	return String(reason);
+}
+function hasStack$1(reason) {
+	return !!reason && typeof reason === "object" && typeof reason.stack === "string";
+}
+/**
+* Route a rejection reason to the reporter: an Error (or any stack-bearing
+* object) goes to `reportSilently` so the STACK survives; only a stackless
+* reason falls back to `reportUnhandledRejection` (string message, empty-stack
+* `UnhandledRejection` class). Any rejection from `reportUnhandledRejection`'s
+* returned promise is swallowed so a transport failure cannot itself surface as
+* an unhandled rejection. `reportSilently` is assumed not to throw synchronously
+* (core's does its work asynchronously); it is intentionally not wrapped, so a
+* synchronous throw there would propagate.
+*/
+function routeRejection(reporter, reason) {
+	if (reason instanceof Error) {
+		reporter.reportSilently(reason);
+		return;
+	}
+	if (hasStack$1(reason)) {
+		const error = new Error(describeRejectionReason(reason));
+		error.stack = reason.stack;
+		reporter.reportSilently(error);
+		return;
+	}
+	Promise.resolve(reporter.reportUnhandledRejection(describeRejectionReason(reason))).catch(() => {});
+}
+
 //#endregion
 //#region src/api/Api.ts
 var Api = class {
@@ -471,6 +514,39 @@ function partitionAttributes(attributes) {
 //#endregion
 //#region src/Scope.ts
 /**
+* Maps each `User` identity field to the flat report attribute key it projects to.
+* `Flare.setUser`'s set pass writes through these so the literal key strings live in
+* exactly one place; `USER_IDENTITY_KEYS` (the clear pass) derives from them, so adding
+* a field here can never silently leave the clear pass out of date.
+*/
+const USER_FIELD_KEYS = {
+	id: "user.id",
+	email: "user.email",
+	fullName: "user.full_name",
+	ipAddress: "client.address"
+};
+/**
+* The report attribute keys that `Flare.setUser` owns: the four projected identity
+* fields plus the `user.attributes` bag for extras. Single source of truth so the
+* clear pass and the set pass in `setUser` cannot drift, and so consumers that must
+* stamp identity outside core's report pipeline (Electron's forwarded-renderer path)
+* pick up the exact same set instead of re-hardcoding it.
+*/
+const USER_IDENTITY_KEYS = [...Object.values(USER_FIELD_KEYS), "user.attributes"];
+/**
+* Pick the user-identity attributes currently set on a scope. Used where identity must
+* be copied onto a report that does not flow through `Flare.report()` (which would
+* otherwise spread `pendingAttributes` automatically).
+*/
+function userIdentityAttributes(scope) {
+	const attrs = {};
+	for (const key of USER_IDENTITY_KEYS) {
+		const value = scope.pendingAttributes[key];
+		if (value !== void 0) attrs[key] = value;
+	}
+	return attrs;
+}
+/**
 * Holds the per-call mutable state that used to live on the `Flare` instance:
 * breadcrumbs (`glows`), custom attributes (`pendingAttributes`), and the
 * current entry-point handler.
@@ -487,9 +563,9 @@ function partitionAttributes(attributes) {
 * holding the state directly, so the per-request behavior comes from the
 * provider, not from the class itself.
 *
-* `NodeScope` (in `@flareapp/node`) extends this with two more buckets:
-* `request` (HTTP method, path, headers) and `user` (id, email, ...). Browser
-* does not need those.
+* `NodeScope` (in `@flareapp/node`) extends this with a `request` bucket
+* (HTTP method, path, headers). User identity is written to `pendingAttributes`
+* by `Flare.setUser`, so it needs no dedicated field. Browser does not need `request`.
 */
 var Scope = class {
 	glows = [];
@@ -612,18 +688,24 @@ function createStackTrace(error, debug, fileReader) {
 			return resolve([fallbackFrame("stacktrace could not be parsed")]);
 		}
 		Promise.all(parsedFrames.map((frame) => {
-			return getCodeSnippet(fileReader, frame.fileName, frame.lineNumber, frame.columnNumber).then((snippet) => ({
+			const fileName = normalizeFileName(frame.fileName);
+			return getCodeSnippet(fileReader, fileName, frame.lineNumber, frame.columnNumber).then((snippet) => ({
 				lineNumber: frame.lineNumber || 1,
 				columnNumber: frame.columnNumber || 1,
 				method: frame.functionName || "Anonymous or unknown function",
-				file: frame.fileName || "Unknown file",
+				file: fileName || "Unknown file",
 				codeSnippet: snippet.codeSnippet,
 				class: "",
-				isApplicationFrame: isApplicationFrame(frame.fileName)
+				isApplicationFrame: isApplicationFrame(fileName)
 			}));
 		})).then(resolve);
 	});
 }
+const HERMES_ADDRESS_PREFIX = "address at ";
+function normalizeFileName(fileName) {
+	if (fileName?.startsWith(HERMES_ADDRESS_PREFIX)) return fileName.slice(11);
+	return fileName;
+}
 function fallbackFrame(reason) {
 	return {
 		lineNumber: 0,
@@ -946,6 +1028,26 @@ var Flare = class {
 		this.scopeProvider.active().setAttribute(`context.${groupName}`, value);
 		return this;
 	}
+	/**
+	* Attach an identified user to the active scope. Fields are projected to the
+	* keys the Flare backend reads: `user.id`, `user.email`, `user.full_name`,
+	* and `client.address`. Any extra keys are bundled into `user.attributes`.
+	* Pass `null` to clear the user. Scope-aware: in Node this targets the
+	* per-request scope via the scope provider.
+	*/
+	setUser(user) {
+		const scope = this.scopeProvider.active();
+		for (const key of USER_IDENTITY_KEYS) delete scope.pendingAttributes[key];
+		if (!user) return this;
+		const { id, email, fullName, ipAddress, ...rest } = user;
+		if (id !== void 0 && id !== null) scope.setAttribute(USER_FIELD_KEYS.id, String(id));
+		if (email !== void 0) scope.setAttribute(USER_FIELD_KEYS.email, email);
+		if (fullName !== void 0) scope.setAttribute(USER_FIELD_KEYS.fullName, fullName);
+		if (ipAddress !== void 0) scope.setAttribute(USER_FIELD_KEYS.ipAddress, ipAddress);
+		const extras = Object.fromEntries(Object.entries(rest).filter(([, value]) => value !== void 0));
+		if (Object.keys(extras).length > 0) scope.setAttribute("user.attributes", extras);
+		return this;
+	}
 	setEntryPoint(handler) {
 		this.scopeProvider.active().entryPoint = handler;
 		return this;
@@ -1101,4 +1203,4 @@ var Flare = class {
 };
 
 //#endregion
-export { Api, DEFAULT_URL_DENYLIST, Flare, GlobalScopeProvider, Logger, NoopFlushScheduler, NullFileReader, Scope, assert, assertKey, convertToError, createStackTrace, extractCode, flatJsonStringify, getCodeSnippet, glowsToEvents, now, readLinesFromFile, redactUrlQuery, resolveDenylist };
+export { Api, DEFAULT_URL_DENYLIST, Flare, GlobalScopeProvider, Logger, NoopFlushScheduler, NullFileReader, Scope, USER_IDENTITY_KEYS, assert, assertKey, convertToError, createStackTrace, describeRejectionReason, extractCode, flatJsonStringify, getCodeSnippet, glowsToEvents, now, readLinesFromFile, redactUrlQuery, resolveDenylist, routeRejection, userIdentityAttributes };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@flareapp/core",
-    "version": "2.5.0",
+    "version": "2.6.0",
     "description": "Environment-agnostic core for the Flare JS SDK",
     "homepage": "https://flareapp.io",
     "bugs": {