@stacktrace-lite/core/dist/plugins/enrichEnvPlugin.d.ts

> Parse, filter, and format JavaScript stack traces with plugins for browsers and Node.js.

import type { StackFrame } from '../parser.js';
/**
 * Minimal environment metadata captured alongside parsed stack frames.
 *
 * @remarks
 * Values are detected from the browser (when available) or supplied via {@link enrichEnvPlugin}'s
 * `getEnv` override. `timestamp` is always an ISO-8601 string (UTC) produced by
 * `new Date().toISOString()`. Browser fields use `window.navigator` when present:
 *
 * - `userAgent`: Raw UA string. Useful for debugging, but avoid UA sniffing for feature detection.
 * - `platform`: Platform identifier (e.g., `"Win32"`, `"MacIntel"`).
 * - `language`: The user’s primary UI language (BCP 47 tag, e.g., `"en-US"`).
 *
 * See MDN for details on these properties and their caveats. :contentReference[oaicite:0]{index=0}
 */
export interface EnvMetadata {
    /** ISO-8601 timestamp (UTC) when the metadata was captured. */
    timestamp: string;
    /** Browser user agent string, if available. */
    userAgent?: string;
    /** Platform identifier (e.g., `"Win32"`, `"MacIntel"`), if available. */
    platform?: string;
    /** Preferred UI language (e.g., `"en-US"`), if available. */
    language?: string;
    /** Additional custom fields supplied by your app. */
    [key: string]: any;
}
/**
 * Create a stack post-processor that enriches frames with environment metadata.
 *
 * @param getEnv - Optional provider returning the metadata object to attach. If omitted,
 * a default detector reads from `window.navigator` when present and sets `timestamp`.
 * @returns A function that accepts `StackFrame[]` and returns the same array instance (cloned)
 * with an `env` property attached containing {@link EnvMetadata}.
 *
 * @remarks
 * - This plugin **adds a nonstandard property** `env` on the returned array. This is convenient
 *   for formatters/collectors but means the value is not part of the `StackFrame` elements; it
 *   lives on the array object itself.
 * - In browsers, `navigator.userAgent`, `navigator.platform`, and `navigator.language` may vary
 *   by engine, privacy settings, or client hints. Prefer feature detection where possible.
 *   See MDN guidance and the newer `navigator.userAgentData` API. :contentReference[oaicite:1]{index=1}
 *
 * @example
 * ```ts
 * // Use built-in detection:
 * const withEnv = enrichEnvPlugin();
 * const framesWithEnv = withEnv(frames);
 * console.log(framesWithEnv.env?.timestamp);
 *
 * // Provide custom metadata (e.g., add app/session identifiers):
 * const withCustomEnv = enrichEnvPlugin(() => ({
 *   timestamp: new Date().toISOString(),
 *   appVersion: '1.4.2',
 *   sessionId: getSessionId(),
 * }));
 * ```
 */
export declare function enrichEnvPlugin(getEnv?: () => EnvMetadata): (frames: StackFrame[]) => StackFrame[] & {
    env?: EnvMetadata;
};