@flareapp/core 2.6.0 → 2.8.0

package/dist/urlAttributes-D3gCx23B.mjs

@@ -0,0 +1,383 @@
+//#region src/env/index.ts
+const CLIENT_VERSION = typeof process !== "undefined" && true ? "2.8.0" : "?";
+const KEY = typeof FLARE_JS_KEY === "undefined" ? "" : FLARE_JS_KEY;
+const SOURCEMAP_VERSION = typeof FLARE_SOURCEMAP_VERSION === "undefined" ? "" : FLARE_SOURCEMAP_VERSION;
+
+//#endregion
+//#region src/util/assert.ts
+function assert(value, message, debug) {
+	if (debug && !value) console.error(`Flare JavaScript client v${CLIENT_VERSION}: ${message}`);
+	return !!value;
+}
+
+//#endregion
+//#region src/util/assertKey.ts
+function assertKey(key, debug) {
+	return assert(key, "The client was not yet initialised with an API key. Run client.light('<flare-project-key>') when you initialise your app. If you are running in dev mode and didn't run the light command on purpose, you can ignore this error.", debug);
+}
+
+//#endregion
+//#region src/util/statelessRegExp.ts
+function withoutStatefulFlags(pattern) {
+	if (!pattern) return;
+	return pattern.global || pattern.sticky ? new RegExp(pattern.source, pattern.flags.replace(/[gy]/g, "")) : pattern;
+}
+
+//#endregion
+//#region src/util/componentMatcher.ts
+/**
+* Built once so a mount costs one name resolution and one match. Strings match exactly, regexes by
+* `test()`.
+*/
+function createComponentMatcher(option) {
+	if (option === true) return () => true;
+	if (!option || option.length === 0) return () => false;
+	const names = new Set(option.filter((entry) => typeof entry === "string"));
+	const patterns = option.filter((entry) => entry instanceof RegExp).map((pattern) => withoutStatefulFlags(pattern));
+	return (name) => names.has(name) || patterns.some((pattern) => pattern.test(name));
+}
+
+//#endregion
+//#region src/util/convertToError.ts
+function convertToError(error) {
+	if (error instanceof Error) return error;
+	if (typeof error === "string") return new Error(error);
+	if (typeof error === "object" && error !== null) {
+		const obj = error;
+		const message = typeof obj.message === "string" ? obj.message : String(error);
+		const converted = new Error(message);
+		if (typeof obj.stack === "string") converted.stack = obj.stack;
+		if (typeof obj.name === "string") converted.name = obj.name;
+		return converted;
+	}
+	return new Error(String(error));
+}
+
+//#endregion
+//#region src/util/createIdentityTagger.ts
+/**
+* A per-package SDK/framework identity tagger. Holds its own WeakSet guards, so each Flare instance
+* (singleton or injected renderer) gets each of the two tags at most once.
+*
+* `frameworkName` is `FrameworkName` rather than `string` because those are the exact values the backend
+* recognises, so a first-party package cannot invent one. A host app that needs its own name calls
+* `setFramework` directly.
+*/
+function createIdentityTagger(config) {
+	const sdkTagged = /* @__PURE__ */ new WeakSet();
+	const frameworkTagged = /* @__PURE__ */ new WeakSet();
+	return {
+		registerSdkIdentity(flare) {
+			if (sdkTagged.has(flare)) return;
+			sdkTagged.add(flare);
+			flare.setSdkInfo({
+				name: config.sdkName,
+				version: config.sdkVersion
+			});
+		},
+		tagFramework(flare, frameworkVersion) {
+			if (frameworkTagged.has(flare)) return;
+			frameworkTagged.add(flare);
+			flare.setFramework(frameworkVersion === void 0 ? { name: config.frameworkName } : {
+				name: config.frameworkName,
+				version: frameworkVersion
+			});
+		}
+	};
+}
+
+//#endregion
+//#region src/util/extractCode.ts
+const MAX_CODE_LENGTH = 64;
+function extractCode(error) {
+	const code = error.code;
+	if (typeof code !== "string" || code.length === 0) return;
+	return code.slice(0, MAX_CODE_LENGTH);
+}
+
+//#endregion
+//#region src/util/traversalBudget.ts
+/**
+* Cycle detection only tracks the ancestor path, so a value holding the same child under two keys is not
+* a cycle but still costs 2^depth to walk. Host data (glows, addContext, span attributes) reaches that
+* shape through any object graph shared by reference.
+*
+* The node cap only bounds that walk if EVERY visited node is charged, primitive leaves included. It used
+* to charge containers only, so 15 shared objects over an array of 1000 strings walked ~17M uncharged
+* strings before the cap fired: 1.2s and 1GB. Callers must spend before their leaf branches return, not
+* after. We do not memoize instead: a value shared under two keys is not a cycle and must not read as one.
+*/
+const MAX_TRAVERSAL_DEPTH = 24;
+const MAX_TRAVERSAL_NODES = 5e4;
+function createTraversalBudget(nodes = MAX_TRAVERSAL_NODES) {
+	return { remaining: nodes };
+}
+/** Consumes one node. False once the budget is spent: stop descending. */
+function spendNode(budget) {
+	if (budget.remaining <= 0) return false;
+	budget.remaining--;
+	return true;
+}
+/** Marks where a walk stopped, so a truncated payload does not read as a complete one. */
+const TRUNCATED = "[truncated: too large]";
+
+//#endregion
+//#region src/util/safeClone.ts
+/**
+* One JSON-safe recursive clone shared by flatJsonStringify (json mode) and vue serializeProps
+* (display mode). Cycles become "[Circular]", a BigInt its decimal string, and a throwing getter
+* "[Getter threw]" in both modes. json mode passes functions / symbols / non-plain objects through
+* (so JSON.stringify still drops functions and calls Date.toJSON); display mode replaces them with
+* placeholders and applies the depth / array / key / string caps and the key denylist.
+*/
+function safeClone(value, options) {
+	const seen = /* @__PURE__ */ new WeakSet();
+	const budget = createTraversalBudget();
+	const depthCap = options.mode === "display" ? options.maxDepth : MAX_TRAVERSAL_DEPTH;
+	function walk(node, depth) {
+		if (!spendNode(budget)) return TRUNCATED;
+		if (node === null) return null;
+		const type = typeof node;
+		if (type === "bigint") return node.toString();
+		if (type === "function") return options.mode === "display" ? "[Function]" : node;
+		if (type === "symbol") return options.mode === "display" ? "[Symbol]" : node;
+		if (type === "string") return options.mode === "display" ? truncate(node, options.stringCap) : node;
+		if (type !== "object") return node;
+		if (seen.has(node)) return "[Circular]";
+		if (Array.isArray(node)) {
+			if (depth > depthCap) return options.mode === "display" ? "[Array]" : TRUNCATED;
+			seen.add(node);
+			const cap = options.mode === "display" ? options.arrayCap : Infinity;
+			const result = (node.length > cap ? node.slice(0, cap) : node).map((item) => walk(item, depth + 1));
+			if (node.length > cap) result.push(`[… ${node.length - cap} more items]`);
+			seen.delete(node);
+			return result;
+		}
+		if (!isPlainObject(node)) return options.mode === "display" ? "[Object]" : node;
+		if (depth > depthCap) return options.mode === "display" ? "[Object]" : TRUNCATED;
+		seen.add(node);
+		const result = {};
+		const keys = Object.keys(node);
+		const keyCap = options.mode === "display" ? options.objectKeyCap : Infinity;
+		const limitedKeys = keys.length > keyCap ? keys.slice(0, keyCap) : keys;
+		for (const key of limitedKeys) {
+			if (options.mode === "display" && options.denylist.test(key)) {
+				result[key] = "[redacted]";
+				continue;
+			}
+			try {
+				result[key] = walk(node[key], depth + 1);
+			} catch {
+				result[key] = "[Getter threw]";
+			}
+		}
+		if (keys.length > keyCap) result["…"] = `[${keys.length - keyCap} more keys]`;
+		seen.delete(node);
+		return result;
+	}
+	return walk(value, 0);
+}
+function truncate(value, max) {
+	if (value.length <= max) return value;
+	return `${value.slice(0, max)}…[truncated ${value.length - max} chars]`;
+}
+/**
+* Literal object / null prototypes only. Class instances may have side-effecting getters or
+* non-enumerable internals we should not traverse, so they are left to the caller's mode policy.
+*/
+function isPlainObject(value) {
+	if (value === null || typeof value !== "object") return false;
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+}
+
+//#endregion
+//#region src/util/flatJsonStringify.ts
+/**
+* JSON.stringify hardened for untrusted glow / addContext data: cycles become "[Circular]", a BigInt
+* its decimal string, and a throwing getter "[Getter threw]", each of which would otherwise throw and
+* drop the whole report.
+*/
+function flatJsonStringify(json) {
+	return JSON.stringify(safeClone(json, { mode: "json" }));
+}
+
+//#endregion
+//#region src/util/glowsToEvents.ts
+function glowsToEvents(glows) {
+	return glows.map((glow) => ({
+		type: "php_glow",
+		startTimeUnixNano: Math.round(glow.microtime * 1e9),
+		endTimeUnixNano: null,
+		attributes: {
+			"glow.name": String(glow.name),
+			"glow.level": glow.messageLevel,
+			"glow.context": glow.metaData ?? {}
+		}
+	}));
+}
+
+//#endregion
+//#region src/util/now.ts
+function now() {
+	return Math.round(Date.now() / 1e3);
+}
+
+//#endregion
+//#region src/util/redactUrl.ts
+const DEFAULT_URL_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, defaultDenylist = DEFAULT_URL_DENYLIST) {
+	if (!custom) return defaultDenylist;
+	if (replaceDefault) {
+		const safeFlags = custom.flags.replace(/[gy]/g, "");
+		return new RegExp(custom.source, safeFlags);
+	}
+	const flags = unionFlags(defaultDenylist.flags, custom.flags);
+	return new RegExp(`(?:${defaultDenylist.source})|(?:${custom.source})`, flags);
+}
+function unionFlags(a, b) {
+	const merged = /* @__PURE__ */ new Set();
+	for (const flag of a + b) {
+		if (flag === "g" || flag === "y") continue;
+		merged.add(flag);
+	}
+	return [...merged].join("");
+}
+/**
+* Strips userinfo (`user:pass@`) from an absolute URL and replaces query-string values whose key
+* matches `denylist` with `[redacted]`. Path segments are left untouched.
+*/
+function redactUrlQuery(fullPath, denylist = DEFAULT_URL_DENYLIST) {
+	const url = stripUserinfo(fullPath);
+	const queryStart = url.indexOf("?");
+	if (queryStart === -1) return url;
+	const hashStart = url.indexOf("#", queryStart);
+	const queryEnd = hashStart === -1 ? url.length : hashStart;
+	const prefix = url.slice(0, queryStart + 1);
+	const queryString = url.slice(queryStart + 1, queryEnd);
+	const suffix = url.slice(queryEnd);
+	return `${prefix}${queryString.split("&").map((pair) => {
+		if (pair === "") return pair;
+		const eq = pair.indexOf("=");
+		const rawKey = eq === -1 ? pair : pair.slice(0, eq);
+		const decodedKey = safeDecode(rawKey);
+		if (!denylist.test(decodedKey)) return pair;
+		return eq === -1 ? rawKey : `${rawKey}=[redacted]`;
+	}).join("&")}${suffix}`;
+}
+/**
+* Value-side mirror of `redactUrlQuery`: a new object where any value whose key matches `denylist`
+* becomes `[redacted]`. Null-prototype result so a `__proto__` key is stored, not swallowed.
+*/
+function redactObjectValues(obj, denylist = DEFAULT_URL_DENYLIST) {
+	const result = Object.create(null);
+	for (const key of Object.keys(obj)) result[key] = denylist.test(key) ? "[redacted]" : obj[key];
+	return result;
+}
+/**
+* Removes userinfo (`user:pass@`) from an absolute URL's authority only. A path or query can legally
+* contain `@`, so only the authority (after `scheme://`, up to the first `/`, `?`, `#`) is inspected.
+*/
+function stripUserinfo(url) {
+	const schemeMatch = /^[a-z][a-z0-9+.-]*:\/\//i.exec(url);
+	if (!schemeMatch) return url;
+	const authorityStart = schemeMatch[0].length;
+	const rest = url.slice(authorityStart);
+	const delimiter = /[/?#]/.exec(rest);
+	const authorityEnd = delimiter ? authorityStart + delimiter.index : url.length;
+	const authority = url.slice(authorityStart, authorityEnd);
+	const at = authority.lastIndexOf("@");
+	if (at === -1) return url;
+	return url.slice(0, authorityStart) + authority.slice(at + 1) + url.slice(authorityEnd);
+}
+/**
+* decodeURIComponent throws on malformed escape sequences (`%E0`, lone `%`, etc). Falls back to the
+* raw key in that case rather than aborting the whole redaction pass.
+*/
+function safeDecode(value) {
+	try {
+		return decodeURIComponent(value);
+	} catch {
+		return 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(reason) {
+	return !!reason && typeof reason === "object" && typeof reason.stack === "string";
+}
+/**
+* Routes by whether `reason` carries a stack: stack-bearing reasons go to `reportSilently`, stackless
+* ones to `reportUnhandledRejection`.
+* The `.catch` is what stops a transport failure from surfacing as a second unhandled rejection.
+* `reportSilently` is assumed async and left unwrapped, so a synchronous throw there still propagates.
+*/
+function routeRejection(reporter, reason) {
+	if (reason instanceof Error) {
+		reporter.reportSilently(reason);
+		return;
+	}
+	if (hasStack(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/util/toCustomContext.ts
+/** Wraps a framework payload as the `context.custom` attribute a report expects. */
+function toCustomContext(framework, payload) {
+	return { "context.custom": { [framework]: payload } };
+}
+
+//#endregion
+//#region src/util/urlAttributes.ts
+/** Well past any routable URL, but short enough that an inline `data:` payload cannot ride along. */
+const MAX_URL_LENGTH = 2048;
+function truncateUrl(url) {
+	return url.length <= MAX_URL_LENGTH ? url : `${url.slice(0, MAX_URL_LENGTH)}…[truncated]`;
+}
+/**
+* Builds the OTel `url.*` attributes for one absolute URL.
+*
+* Redacts the URL first and splits it after, so `url.full` and `url.query` always show the same
+* redacted values.
+*
+* Leaves out `url.query` when there is no query string. Returns only `url.full` when the URL cannot
+* be parsed, for example a relative one.
+*/
+function urlAttributes(url, denylist = DEFAULT_URL_DENYLIST) {
+	const full = truncateUrl(redactUrlQuery(url, denylist));
+	const attributes = { "url.full": full };
+	let parsed;
+	try {
+		parsed = new URL(full);
+	} catch {
+		return attributes;
+	}
+	attributes["url.scheme"] = parsed.protocol.slice(0, -1);
+	attributes["url.path"] = parsed.pathname;
+	if (parsed.search) attributes["url.query"] = parsed.search.slice(1);
+	return attributes;
+}
+
+//#endregion
+export { withoutStatefulFlags as C, KEY as D, CLIENT_VERSION as E, SOURCEMAP_VERSION as O, createComponentMatcher as S, assert as T, createTraversalBudget as _, routeRejection as a, createIdentityTagger as b, redactUrlQuery as c, now as d, glowsToEvents as f, TRUNCATED as g, MAX_TRAVERSAL_DEPTH as h, describeRejectionReason as i, resolveDenylist as l, safeClone as m, urlAttributes as n, DEFAULT_URL_DENYLIST as o, flatJsonStringify as p, toCustomContext as r, redactObjectValues as s, MAX_URL_LENGTH as t, safeDecode as u, spendNode as v, assertKey as w, convertToError as x, extractCode as y };

package/dist/util/index.cjs

@@ -0,0 +1,24 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_urlAttributes = require('../urlAttributes-CNGTgOJp.cjs');
+
+exports.DEFAULT_URL_DENYLIST = require_urlAttributes.DEFAULT_URL_DENYLIST;
+exports.MAX_URL_LENGTH = require_urlAttributes.MAX_URL_LENGTH;
+exports.assert = require_urlAttributes.assert;
+exports.assertKey = require_urlAttributes.assertKey;
+exports.convertToError = require_urlAttributes.convertToError;
+exports.createComponentMatcher = require_urlAttributes.createComponentMatcher;
+exports.createIdentityTagger = require_urlAttributes.createIdentityTagger;
+exports.describeRejectionReason = require_urlAttributes.describeRejectionReason;
+exports.extractCode = require_urlAttributes.extractCode;
+exports.flatJsonStringify = require_urlAttributes.flatJsonStringify;
+exports.glowsToEvents = require_urlAttributes.glowsToEvents;
+exports.now = require_urlAttributes.now;
+exports.redactObjectValues = require_urlAttributes.redactObjectValues;
+exports.redactUrlQuery = require_urlAttributes.redactUrlQuery;
+exports.resolveDenylist = require_urlAttributes.resolveDenylist;
+exports.routeRejection = require_urlAttributes.routeRejection;
+exports.safeClone = require_urlAttributes.safeClone;
+exports.safeDecode = require_urlAttributes.safeDecode;
+exports.toCustomContext = require_urlAttributes.toCustomContext;
+exports.urlAttributes = require_urlAttributes.urlAttributes;
+exports.withoutStatefulFlags = require_urlAttributes.withoutStatefulFlags;

package/dist/util/index.d.cts

@@ -0,0 +1,2 @@
+import { C as createComponentMatcher, S as ProfileComponentsOption, T as assert, _ as flatJsonStringify, a as SafeCloneOptions, b as createIdentityTagger, c as describeRejectionReason, d as redactObjectValues, f as redactUrlQuery, g as glowsToEvents, h as now, i as withoutStatefulFlags, l as routeRejection, m as safeDecode, n as urlAttributes, o as safeClone, p as resolveDenylist, r as toCustomContext, s as RejectionReporter, t as MAX_URL_LENGTH, u as DEFAULT_URL_DENYLIST, v as extractCode, w as assertKey, x as convertToError, y as SdkTaggable } from "../urlAttributes-CvOw6tU3.cjs";
+export { DEFAULT_URL_DENYLIST, MAX_URL_LENGTH, ProfileComponentsOption, RejectionReporter, SafeCloneOptions, SdkTaggable, assert, assertKey, convertToError, createComponentMatcher, createIdentityTagger, describeRejectionReason, extractCode, flatJsonStringify, glowsToEvents, now, redactObjectValues, redactUrlQuery, resolveDenylist, routeRejection, safeClone, safeDecode, toCustomContext, urlAttributes, withoutStatefulFlags };

package/dist/util/index.d.mts

@@ -0,0 +1,2 @@
+import { C as createComponentMatcher, S as ProfileComponentsOption, T as assert, _ as flatJsonStringify, a as SafeCloneOptions, b as createIdentityTagger, c as describeRejectionReason, d as redactObjectValues, f as redactUrlQuery, g as glowsToEvents, h as now, i as withoutStatefulFlags, l as routeRejection, m as safeDecode, n as urlAttributes, o as safeClone, p as resolveDenylist, r as toCustomContext, s as RejectionReporter, t as MAX_URL_LENGTH, u as DEFAULT_URL_DENYLIST, v as extractCode, w as assertKey, x as convertToError, y as SdkTaggable } from "../urlAttributes-B9BlkrfW.mjs";
+export { DEFAULT_URL_DENYLIST, MAX_URL_LENGTH, ProfileComponentsOption, RejectionReporter, SafeCloneOptions, SdkTaggable, assert, assertKey, convertToError, createComponentMatcher, createIdentityTagger, describeRejectionReason, extractCode, flatJsonStringify, glowsToEvents, now, redactObjectValues, redactUrlQuery, resolveDenylist, routeRejection, safeClone, safeDecode, toCustomContext, urlAttributes, withoutStatefulFlags };

package/dist/util/index.mjs

@@ -0,0 +1,3 @@
+import { C as withoutStatefulFlags, S as createComponentMatcher, T as assert, a as routeRejection, b as createIdentityTagger, c as redactUrlQuery, d as now, f as glowsToEvents, i as describeRejectionReason, l as resolveDenylist, m as safeClone, n as urlAttributes, o as DEFAULT_URL_DENYLIST, p as flatJsonStringify, r as toCustomContext, s as redactObjectValues, t as MAX_URL_LENGTH, u as safeDecode, w as assertKey, x as convertToError, y as extractCode } from "../urlAttributes-D3gCx23B.mjs";
+
+export { DEFAULT_URL_DENYLIST, MAX_URL_LENGTH, assert, assertKey, convertToError, createComponentMatcher, createIdentityTagger, describeRejectionReason, extractCode, flatJsonStringify, glowsToEvents, now, redactObjectValues, redactUrlQuery, resolveDenylist, routeRejection, safeClone, safeDecode, toCustomContext, urlAttributes, withoutStatefulFlags };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@flareapp/core",
-    "version": "2.6.0",
+    "version": "2.8.0",
     "description": "Environment-agnostic core for the Flare JS SDK",
     "homepage": "https://flareapp.io",
     "bugs": {
@@ -15,6 +15,9 @@
         "name": "Spatie",
         "email": "info@spatie.be"
     },
+    "contributors": [
+        "Dries Heyninck <dries@spatie.be>"
+    ],
     "files": [
         "dist"
     ],
@@ -31,11 +34,21 @@
                 "types": "./dist/index.d.cts",
                 "default": "./dist/index.cjs"
             }
+        },
+        "./util": {
+            "import": {
+                "types": "./dist/util/index.d.mts",
+                "default": "./dist/util/index.mjs"
+            },
+            "require": {
+                "types": "./dist/util/index.d.cts",
+                "default": "./dist/util/index.cjs"
+            }
         }
     },
     "scripts": {
         "prepublishOnly": "npm run build",
-        "build": "tsdown src/index.ts --format cjs,esm --dts --env.FLARE_JS_CLIENT_VERSION=$(node -p \"require('./package.json').version\") --clean",
+        "build": "tsdown src/index.ts src/util/index.ts --format cjs,esm --dts --env.FLARE_JS_CLIENT_VERSION=$(node -p \"require('./package.json').version\") --clean",
         "test": "vitest run",
         "typescript": "tsc --noEmit",
         "release": "release-it"
@@ -44,6 +57,7 @@
         "error-stack-parser": "^2.0.2"
     },
     "devDependencies": {
+        "@flareapp/test-helpers": "*",
         "jsdom": "^26.1.0",
         "tsdown": "^0.20.3",
         "typescript": "^5.7.0",