@flareapp/core 2.2.0

package/src/Scope.ts

@@ -0,0 +1,96 @@
+import type { Attributes, AttributeValue, EntryPointHandler, Glow } from './types';
+
+/**
+ * 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.
+ *
+ * Why this exists as its own class: in the browser there is one `Flare` per
+ * page and one user at a time, so a single shared bag of state is fine. In
+ * Node, a single `Flare` instance serves many concurrent requests, and each
+ * request wants its own breadcrumbs and its own custom context that do NOT
+ * leak into other requests. Splitting this state out of `Flare` lets the
+ * consumer choose: one global `Scope` (browser) or one `Scope` per request
+ * via AsyncLocalStorage (Node).
+ *
+ * `Flare` reads and writes this through `scopeProvider.active()` instead of
+ * 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.
+ */
+export class Scope {
+    glows: Glow[] = [];
+    pendingAttributes: Attributes = {};
+    entryPoint: EntryPointHandler | null = null;
+
+    /**
+     * Append a breadcrumb. Caps the list at `maxGlowsPerReport` by dropping the
+     * OLDEST entries when the limit is exceeded; this keeps reports below a
+     * payload-size threshold while preserving the most recent events leading
+     * up to an error.
+     *
+     * `slice(length - max)` returns the trailing `max` items, which is the
+     * shortest way to drop from the front and keep insertion order.
+     */
+    addGlow(glow: Glow, maxGlowsPerReport: number): void {
+        this.glows.push(glow);
+        if (this.glows.length > maxGlowsPerReport) {
+            this.glows = this.glows.slice(this.glows.length - maxGlowsPerReport);
+        }
+    }
+
+    clearGlows(): void {
+        this.glows = [];
+    }
+
+    /**
+     * Set a single attribute on this scope. Called from `Flare.addContext` and
+     * `Flare.addContextGroup`. Last write wins.
+     */
+    setAttribute(key: string, value: AttributeValue): void {
+        this.pendingAttributes[key] = value;
+    }
+
+    /**
+     * Shallow-merge a bag of attributes into this scope. Used by Node's
+     * AsyncLocalStorage provider when patching the live request context via
+     * `flare.mergeContext({ ... })`. Last write wins per key; nested objects
+     * are NOT deep-merged.
+     */
+    mergeAttributes(partial: Attributes): void {
+        Object.assign(this.pendingAttributes, partial);
+    }
+}
+
+/**
+ * The seam through which `Flare` reaches its current `Scope`. Implementations
+ * decide what "current" means.
+ *
+ * - `GlobalScopeProvider` always returns the same `Scope` instance (browser).
+ * - `AsyncLocalStorageScopeProvider` in `@flareapp/node` returns the per-request
+ *   `NodeScope` stored in `node:async_hooks` for the in-flight async chain,
+ *   falling back to a single shared scope when called outside any
+ *   `runWithContext(...)` callback.
+ *
+ * Any consumer of `@flareapp/core` can supply its own provider to plug in
+ * different "current scope" semantics.
+ */
+export interface ScopeProvider {
+    active(): Scope;
+}
+
+/**
+ * The simplest provider: one `Scope` for the lifetime of the provider, shared
+ * by every caller. This is the right default for environments with a single
+ * logical context (browser tab, CLI script, etc.) and is the default that
+ * `Flare`'s constructor falls back to when no provider is supplied.
+ */
+export class GlobalScopeProvider implements ScopeProvider {
+    private scope = new Scope();
+    active(): Scope {
+        return this.scope;
+    }
+}

package/src/api/Api.ts

@@ -0,0 +1,35 @@
+import { Report } from '../types';
+import { flatJsonStringify } from '../util';
+
+export class Api {
+    report(
+        report: Report,
+        url: string,
+        key: string | null,
+        reportBrowserExtensionErrors: boolean,
+        debug: boolean = false,
+    ): Promise<void> {
+        return fetch(url, {
+            method: 'POST',
+            headers: {
+                'Accept': 'application/json',
+                'Content-Type': 'application/json',
+                'X-Api-Token': key ?? '',
+                'X-Report-Browser-Extension-Errors': JSON.stringify(reportBrowserExtensionErrors),
+                'X-Flare-Client-Version': '2',
+            },
+            body: flatJsonStringify(report),
+        }).then(
+            (response) => {
+                if (debug && response.status !== 201) {
+                    console.error(`Received response with status ${response.status} from Flare`);
+                }
+            },
+            (error) => {
+                if (debug) {
+                    console.error(error);
+                }
+            },
+        );
+    }
+}

package/src/api/index.ts

@@ -0,0 +1 @@
+export { Api } from './Api';

package/src/env/index.ts

@@ -0,0 +1,14 @@
+declare const FLARE_JS_KEY: string | undefined;
+declare const FLARE_SOURCEMAP_VERSION: string | undefined;
+
+// Injected during build
+export const CLIENT_VERSION =
+    typeof process !== 'undefined' && typeof process.env?.FLARE_JS_CLIENT_VERSION !== 'undefined'
+        ? process.env.FLARE_JS_CLIENT_VERSION
+        : '?';
+
+// Injected by flare-vite-plugin-sourcemap-uploader (optional)
+export const KEY = typeof FLARE_JS_KEY === 'undefined' ? '' : FLARE_JS_KEY;
+
+// Injected by flare-vite-plugin-sourcemap-uploader (optional)
+export const SOURCEMAP_VERSION = typeof FLARE_SOURCEMAP_VERSION === 'undefined' ? '' : FLARE_SOURCEMAP_VERSION;

package/src/index.ts

@@ -0,0 +1,41 @@
+export type {
+    AttributeValue,
+    Attributes,
+    Config,
+    EntryPointHandler,
+    Framework,
+    Glow,
+    MessageLevel,
+    OverriddenGrouping,
+    Report,
+    SdkInfo,
+    SpanEvent,
+    StackFrame,
+} from './types';
+
+export {
+    assert,
+    assertKey,
+    convertToError,
+    DEFAULT_URL_DENYLIST,
+    extractCode,
+    flatJsonStringify,
+    glowsToEvents,
+    now,
+    redactUrlQuery,
+    resolveDenylist,
+} from './util';
+
+export { Api } from './api';
+
+export { Flare } from './Flare';
+export type { ContextCollector } from './Flare';
+
+export { Scope, GlobalScopeProvider } from './Scope';
+export type { ScopeProvider } from './Scope';
+
+export { NullFileReader } from './stacktrace/NullFileReader';
+export type { FileReader } from './stacktrace/fileReader';
+
+export { createStackTrace } from './stacktrace/createStackTrace';
+export { getCodeSnippet, readLinesFromFile } from './stacktrace/fileReader';

package/src/stacktrace/NullFileReader.ts

@@ -0,0 +1,28 @@
+import type { FileReader } from './fileReader';
+
+/**
+ * No-op `FileReader` that returns `null` for every URL it is asked to read.
+ *
+ * Used as the default for `Flare`'s `fileReader` constructor parameter so the
+ * class is usable without picking a side: instantiated bare (`new Flare()`),
+ * reports still build, but stack frames omit source-code snippets — which is
+ * the correct, safe behavior in an environment we know nothing about.
+ *
+ * The two real implementations live in the consumer packages and take their
+ * place once the right environment is established:
+ *
+ * - `@flareapp/js` injects `FetchFileReader`, which `fetch()`s source maps
+ *   and original files over HTTP for browser stack frames.
+ * - `@flareapp/node` injects `DiskFileReader`, which reads files from disk
+ *   via `node:fs/promises` for server stack frames.
+ *
+ * The interface (`read(url) -> Promise<string | null>`) lets the stack-trace
+ * builder treat all three the same way: ask for a URL, render the snippet
+ * when text comes back, gracefully skip it when `null` does. No environment
+ * checks anywhere in core.
+ */
+export class NullFileReader implements FileReader {
+    read(_url: string): Promise<string | null> {
+        return Promise.resolve(null);
+    }
+}

package/src/stacktrace/createStackTrace.ts

@@ -0,0 +1,74 @@
+import ErrorStackParser from 'error-stack-parser';
+
+import { StackFrame } from '../types';
+import { assert } from '../util';
+import type { FileReader } from './fileReader';
+import { getCodeSnippet } from './fileReader';
+
+export function createStackTrace(error: Error, debug: boolean, fileReader: FileReader): Promise<Array<StackFrame>> {
+    return new Promise((resolve) => {
+        if (!hasStack(error)) {
+            return resolve([fallbackFrame('stacktrace missing')]);
+        }
+
+        let parsedFrames;
+        try {
+            parsedFrames = ErrorStackParser.parse(error);
+        } catch (parseError) {
+            assert(false, "Couldn't parse stacktrace of below error:", debug);
+            if (debug) {
+                console.error(parseError);
+                console.error(error);
+            }
+            return resolve([fallbackFrame('stacktrace could not be parsed')]);
+        }
+
+        Promise.all(
+            parsedFrames.map((frame) => {
+                return getCodeSnippet(fileReader, frame.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',
+                        codeSnippet: snippet.codeSnippet,
+                        class: '',
+                        isApplicationFrame: isApplicationFrame(frame.fileName),
+                    }),
+                );
+            }),
+        ).then(resolve);
+    });
+}
+
+function fallbackFrame(reason: string): StackFrame {
+    return {
+        lineNumber: 0,
+        columnNumber: 0,
+        method: 'unknown',
+        file: 'unknown',
+        codeSnippet: { 0: `Could not read from file: ${reason}` },
+        class: 'unknown',
+    };
+}
+
+// Some engines populate `err.stack` with just `"<Name>: <message>"` (no frames) when an Error is
+// constructed but never thrown. Treat that as "no stack" so we fall back instead of parsing garbage.
+// Also accepts the legacy `stacktrace` and Opera `opera#sourceloc` properties.
+function hasStack(err: unknown): boolean {
+    if (!err || typeof err !== 'object') return false;
+    const e = err as Record<string, unknown>;
+    const stack = e.stack ?? e.stacktrace ?? e['opera#sourceloc'];
+    return (
+        typeof stack === 'string' &&
+        stack !== `${(e as { name?: string }).name}: ${(e as { message?: string }).message}`
+    );
+}
+
+function isApplicationFrame(fileName: string | undefined): boolean {
+    if (!fileName) return true;
+    // node_modules and webpack-style vendor chunks should not count as application code
+    if (/[/\\]node_modules[/\\]/.test(fileName)) return false;
+    if (/(^|[/\\])(vendor|vendors)[.~-][^/\\]*\.js/i.test(fileName)) return false;
+    return true;
+}

package/src/stacktrace/fileReader.ts

@@ -0,0 +1,96 @@
+export interface FileReader {
+    read(url: string): Promise<string | null>;
+}
+
+const cachedFiles: { [key: string]: string } = {};
+
+type CodeSnippet = { [key: number]: string };
+
+type ReaderResponse = {
+    codeSnippet: CodeSnippet;
+    trimmedColumnNumber: number | null;
+};
+
+export function getCodeSnippet(
+    fileReader: FileReader,
+    url?: string,
+    lineNumber?: number,
+    columnNumber?: number,
+): Promise<ReaderResponse> {
+    return new Promise((resolve) => {
+        if (!url || !lineNumber) {
+            return resolve({
+                codeSnippet: {
+                    0: `Could not read from file: missing file URL or line number. URL: ${url} lineNumber: ${lineNumber}`,
+                },
+                trimmedColumnNumber: null,
+            });
+        }
+
+        readFile(fileReader, url).then((fileText) => {
+            if (!fileText) {
+                return resolve({
+                    codeSnippet: {
+                        0: `Could not read from file: Error while opening file at URL ${url}`,
+                    },
+                    trimmedColumnNumber: null,
+                });
+            }
+            return resolve(readLinesFromFile(fileText, lineNumber, columnNumber));
+        });
+    });
+}
+
+function readFile(fileReader: FileReader, url: string): Promise<string | null> {
+    if (cachedFiles[url] !== undefined) {
+        return Promise.resolve(cachedFiles[url]);
+    }
+    return fileReader.read(url).then((text) => {
+        if (text !== null) {
+            cachedFiles[url] = text;
+        }
+        return text;
+    });
+}
+
+export function readLinesFromFile(
+    fileText: string,
+    lineNumber: number,
+    columnNumber?: number,
+    maxSnippetLineLength = 1000,
+    maxSnippetLines = 40,
+): ReaderResponse {
+    const codeSnippet: CodeSnippet = {};
+    let trimmedColumnNumber = null;
+
+    const lines = fileText.split('\n');
+    const errorLineIndex = lineNumber - 1;
+    const half = Math.floor(maxSnippetLines / 2);
+
+    for (let i = -half; i <= half; i++) {
+        const currentLineIndex = errorLineIndex + i;
+        if (currentLineIndex < 0 || !lines[currentLineIndex]) continue;
+        const displayLine = currentLineIndex + 1;
+        const line = lines[currentLineIndex];
+        if (line.length > maxSnippetLineLength) {
+            if (columnNumber && columnNumber > maxSnippetLineLength / 2) {
+                const start = columnNumber - Math.round(maxSnippetLineLength / 2);
+                codeSnippet[displayLine] = line.slice(start, start + maxSnippetLineLength);
+                if (displayLine === lineNumber) {
+                    trimmedColumnNumber = Math.round(maxSnippetLineLength / 2);
+                }
+                continue;
+            }
+            codeSnippet[displayLine] = line.slice(0, maxSnippetLineLength) + '…';
+            continue;
+        }
+        codeSnippet[displayLine] = line;
+    }
+
+    return { codeSnippet, trimmedColumnNumber };
+}
+
+// Clearing the cache is useful in tests.
+export function __clearFileReaderCacheForTests(): void {
+    for (const key of Object.keys(cachedFiles)) delete cachedFiles[key];
+}

package/src/stacktrace/index.ts

@@ -0,0 +1,4 @@
+export { createStackTrace } from './createStackTrace';
+export { getCodeSnippet, readLinesFromFile, __clearFileReaderCacheForTests } from './fileReader';
+export type { FileReader } from './fileReader';
+export { NullFileReader } from './NullFileReader';

package/src/types.ts

@@ -0,0 +1,81 @@
+export type MessageLevel = 'debug' | 'info' | 'notice' | 'warning' | 'error' | 'critical' | 'alert' | 'emergency';
+
+export type AttributeValue = string | number | boolean | null | AttributeValue[] | { [key: string]: AttributeValue };
+
+export type Attributes = Record<string, AttributeValue>;
+
+export type Config = {
+    key: string | null;
+    version: string;
+    sourcemapVersionId: string;
+    stage: string;
+    maxGlowsPerReport: number;
+    reportBrowserExtensionErrors: boolean;
+    ingestUrl: string;
+    debug: boolean;
+    urlDenylist: RegExp;
+    replaceDefaultUrlDenylist: boolean;
+    sampleRate: number;
+    beforeEvaluate: (error: Error) => Error | false | null | Promise<Error | false | null>;
+    beforeSubmit: (report: Report) => Report | false | null | Promise<Report | false | null>;
+};
+
+export type StackFrame = {
+    file: string;
+    lineNumber: number;
+    columnNumber?: number;
+    method?: string;
+    class?: string;
+    codeSnippet?: { [line: number]: string };
+    isApplicationFrame?: boolean;
+    arguments?: unknown[];
+};
+
+export type SpanEvent = {
+    type: string;
+    startTimeUnixNano: number;
+    endTimeUnixNano: number | null;
+    attributes: Attributes;
+};
+
+export type OverriddenGrouping =
+    | 'exception_class'
+    | 'exception_message'
+    | 'exception_message_and_class'
+    | 'full_stacktrace_and_exception_class_and_code';
+
+export type Report = {
+    exceptionClass?: string | null;
+    message?: string | null;
+    code?: string;
+    seenAtUnixNano: number;
+    isLog?: boolean;
+    level?: MessageLevel;
+    sourcemapVersionId?: string;
+    trackingUuid?: string;
+    handled?: boolean;
+    openFrameIndex?: number;
+    applicationPath?: string;
+    overriddenGrouping?: OverriddenGrouping | null;
+    stacktrace: StackFrame[];
+    events: SpanEvent[];
+    attributes: Attributes;
+};
+
+export type Glow = {
+    time: number;
+    microtime: number;
+    name: string;
+    messageLevel: MessageLevel;
+    metaData: Record<string, unknown> | Record<string, unknown>[];
+};
+
+export type EntryPointHandler = {
+    identifier?: string;
+    name?: string;
+    type?: string;
+};
+
+export type SdkInfo = { name: string; version: string };
+
+export type Framework = { name: string; version?: string };

package/src/util/assert.ts

@@ -0,0 +1,9 @@
+import { CLIENT_VERSION } from '../env';
+
+export function assert(value: unknown, message: string, debug: boolean) {
+    if (debug && !value) {
+        console.error(`Flare JavaScript client v${CLIENT_VERSION}: ${message}`);
+    }
+
+    return !!value;
+}

package/src/util/assertKey.ts

@@ -0,0 +1,11 @@
+import { assert } from './assert';
+
+export function assertKey(key: unknown, debug: boolean): boolean {
+    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,
+    );
+}

package/src/util/convertToError.ts

@@ -0,0 +1,22 @@
+export function convertToError(error: unknown): Error {
+    if (error instanceof Error) {
+        return error;
+    }
+    if (typeof error === 'string') {
+        return new Error(error);
+    }
+    if (typeof error === 'object' && error !== null) {
+        const obj = error as Record<string, unknown>;
+        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));
+}

package/src/util/extractCode.ts

@@ -0,0 +1,11 @@
+const MAX_CODE_LENGTH = 64;
+
+export function extractCode(error: Error): string | undefined {
+    const code = (error as { code?: unknown }).code;
+
+    if (typeof code !== 'string' || code.length === 0) {
+        return undefined;
+    }
+
+    return code.slice(0, MAX_CODE_LENGTH);
+}

package/src/util/flatJsonStringify.ts

@@ -0,0 +1,45 @@
+// JSON.stringify throws on circular references. User-supplied glow data and addContext values can
+// realistically contain cycles (e.g. Vue/React component instances), so we walk the tree first and
+// replace any back-edges with the sentinel "[Circular]" before serialising.
+export function flatJsonStringify(json: object): string {
+    return JSON.stringify(decycle(json));
+}
+
+// Restricted to literal object/null prototypes on purpose: class instances may have getters with
+// side effects or non-enumerable internals that we shouldn't traverse. They're left to JSON.stringify
+// to handle (typically by calling toJSON or returning {}).
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+    if (typeof value !== 'object' || value === null) return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+
+function decycle(root: unknown): unknown {
+    // `inPath` tracks ancestors on the current branch only (added on enter, removed on exit). Using a
+    // global "seen" set would mis-flag the same object referenced twice in different branches as
+    // circular, even though no cycle exists.
+    const inPath = new WeakSet<object>();
+
+    function clone(node: unknown): unknown {
+        if (Array.isArray(node)) {
+            if (inPath.has(node)) return '[Circular]';
+            inPath.add(node);
+            const result = node.map(clone);
+            inPath.delete(node);
+            return result;
+        }
+        if (isPlainObject(node)) {
+            if (inPath.has(node)) return '[Circular]';
+            inPath.add(node);
+            const result: Record<string, unknown> = {};
+            for (const [k, v] of Object.entries(node)) {
+                result[k] = clone(v);
+            }
+            inPath.delete(node);
+            return result;
+        }
+        return node;
+    }
+
+    return clone(root);
+}

package/src/util/glowsToEvents.ts

@@ -0,0 +1,16 @@
+import { AttributeValue, Glow, SpanEvent } from '../types';
+
+// glow.microtime is seconds since epoch (see util/now.ts).
+// SpanEvent.startTimeUnixNano is unix nanoseconds.
+export function glowsToEvents(glows: Glow[]): SpanEvent[] {
+    return glows.map((glow) => ({
+        type: 'php_glow',
+        startTimeUnixNano: Math.round(glow.microtime * 1_000_000_000),
+        endTimeUnixNano: null,
+        attributes: {
+            'glow.name': String(glow.name),
+            'glow.level': glow.messageLevel,
+            'glow.context': (glow.metaData ?? {}) as AttributeValue,
+        },
+    }));
+}

package/src/util/index.ts

@@ -0,0 +1,8 @@
+export * from './assert';
+export * from './assertKey';
+export * from './convertToError';
+export * from './extractCode';
+export * from './flatJsonStringify';
+export * from './glowsToEvents';
+export * from './now';
+export * from './redactUrl';

package/src/util/now.ts

@@ -0,0 +1,3 @@
+export function now(): number {
+    return Math.round(Date.now() / 1000);
+}