@flareapp/core 2.5.0 → 2.5.1

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.5.1" : "?";
 const KEY = typeof FLARE_JS_KEY === "undefined" ? "" : FLARE_JS_KEY;
 const SOURCEMAP_VERSION = typeof FLARE_SOURCEMAP_VERSION === "undefined" ? "" : FLARE_SOURCEMAP_VERSION;
 
@@ -500,6 +500,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 +549,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 = [];
@@ -975,6 +1008,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,6 +1191,7 @@ 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;
@@ -1149,4 +1203,5 @@ exports.glowsToEvents = glowsToEvents;
 exports.now = now;
 exports.readLinesFromFile = readLinesFromFile;
 exports.redactUrlQuery = redactUrlQuery;
-exports.resolveDenylist = resolveDenylist;
+exports.resolveDenylist = resolveDenylist;
+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;
@@ -236,6 +253,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 +284,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 +525,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 +580,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 Report, Scope, type ScopeProvider, type SdkInfo, type SpanEvent, type StackFrame, USER_IDENTITY_KEYS, type User, assert, assertKey, convertToError, createStackTrace, extractCode, flatJsonStringify, getCodeSnippet, glowsToEvents, now, readLinesFromFile, redactUrlQuery, resolveDenylist, 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;
@@ -236,6 +253,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 +284,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 +525,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 +580,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 Report, Scope, type ScopeProvider, type SdkInfo, type SpanEvent, type StackFrame, USER_IDENTITY_KEYS, type User, assert, assertKey, convertToError, createStackTrace, extractCode, flatJsonStringify, getCodeSnippet, glowsToEvents, now, readLinesFromFile, redactUrlQuery, resolveDenylist, 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.5.1" : "?";
 const KEY = typeof FLARE_JS_KEY === "undefined" ? "" : FLARE_JS_KEY;
 const SOURCEMAP_VERSION = typeof FLARE_SOURCEMAP_VERSION === "undefined" ? "" : FLARE_SOURCEMAP_VERSION;
 
@@ -471,6 +471,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 +520,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 = [];
@@ -946,6 +979,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 +1154,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, extractCode, flatJsonStringify, getCodeSnippet, glowsToEvents, now, readLinesFromFile, redactUrlQuery, resolveDenylist, userIdentityAttributes };

package/package.json

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