@flareapp/core 2.2.0 → 2.2.1

package/dist/index.d.mts

@@ -0,0 +1,411 @@
+//#region src/types.d.ts
+type MessageLevel = 'debug' | 'info' | 'notice' | 'warning' | 'error' | 'critical' | 'alert' | 'emergency';
+type AttributeValue = string | number | boolean | null | AttributeValue[] | {
+  [key: string]: AttributeValue;
+};
+type Attributes = Record<string, AttributeValue>;
+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>;
+};
+type StackFrame = {
+  file: string;
+  lineNumber: number;
+  columnNumber?: number;
+  method?: string;
+  class?: string;
+  codeSnippet?: {
+    [line: number]: string;
+  };
+  isApplicationFrame?: boolean;
+  arguments?: unknown[];
+};
+type SpanEvent = {
+  type: string;
+  startTimeUnixNano: number;
+  endTimeUnixNano: number | null;
+  attributes: Attributes;
+};
+type OverriddenGrouping = 'exception_class' | 'exception_message' | 'exception_message_and_class' | 'full_stacktrace_and_exception_class_and_code';
+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;
+};
+type Glow = {
+  time: number;
+  microtime: number;
+  name: string;
+  messageLevel: MessageLevel;
+  metaData: Record<string, unknown> | Record<string, unknown>[];
+};
+type EntryPointHandler = {
+  identifier?: string;
+  name?: string;
+  type?: string;
+};
+type SdkInfo = {
+  name: string;
+  version: string;
+};
+type Framework = {
+  name: string;
+  version?: string;
+};
+//#endregion
+//#region src/util/assert.d.ts
+declare function assert(value: unknown, message: string, debug: boolean): boolean;
+//#endregion
+//#region src/util/assertKey.d.ts
+declare function assertKey(key: unknown, debug: boolean): boolean;
+//#endregion
+//#region src/util/convertToError.d.ts
+declare function convertToError(error: unknown): Error;
+//#endregion
+//#region src/util/extractCode.d.ts
+declare function extractCode(error: Error): string | undefined;
+//#endregion
+//#region src/util/flatJsonStringify.d.ts
+declare function flatJsonStringify(json: object): string;
+//#endregion
+//#region src/util/glowsToEvents.d.ts
+declare function glowsToEvents(glows: Glow[]): SpanEvent[];
+//#endregion
+//#region src/util/now.d.ts
+declare function now(): number;
+//#endregion
+//#region src/util/redactUrl.d.ts
+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/api/Api.d.ts
+declare class Api {
+  report(report: Report, url: string, key: string | null, reportBrowserExtensionErrors: boolean, debug?: boolean): Promise<void>;
+}
+//#endregion
+//#region src/Scope.d.ts
+/**
+ * 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.
+ */
+declare class Scope {
+  glows: Glow[];
+  pendingAttributes: Attributes;
+  entryPoint: EntryPointHandler | 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;
+  clearGlows(): void;
+  /**
+   * Set a single attribute on this scope. Called from `Flare.addContext` and
+   * `Flare.addContextGroup`. Last write wins.
+   */
+  setAttribute(key: string, value: AttributeValue): void;
+  /**
+   * 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;
+}
+/**
+ * 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.
+ */
+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.
+ */
+declare class GlobalScopeProvider implements ScopeProvider {
+  private scope;
+  active(): Scope;
+}
+//#endregion
+//#region src/stacktrace/fileReader.d.ts
+interface FileReader {
+  read(url: string): Promise<string | null>;
+}
+type CodeSnippet = {
+  [key: number]: string;
+};
+type ReaderResponse = {
+  codeSnippet: CodeSnippet;
+  trimmedColumnNumber: number | null;
+};
+declare function getCodeSnippet(fileReader: FileReader, url?: string, lineNumber?: number, columnNumber?: number): Promise<ReaderResponse>;
+declare function readLinesFromFile(fileText: string, lineNumber: number, columnNumber?: number, maxSnippetLineLength?: number, maxSnippetLines?: number): ReaderResponse;
+//#endregion
+//#region src/Flare.d.ts
+type ContextCollector = (config: Readonly<Config>) => Attributes;
+declare class Flare {
+  api: Api;
+  private contextCollector;
+  private fileReader;
+  private scopeProvider;
+  private inflight;
+  private _config;
+  private sdkInfo;
+  private framework;
+  /**
+   * @param api              sends the report over HTTP.
+   * @param contextCollector returns per-report attributes (browser DOM info, Node
+   *                         process info, etc). Default is a no-op.
+   * @param fileReader       reads source files for stack-trace snippets. Default
+   *                         returns null (no snippets); `@flareapp/js` injects a
+   *                         fetch-based reader, `@flareapp/node` injects a disk reader.
+   * @param scopeProvider    returns the current `Scope` (per-call mutable state:
+   *                         glows, pendingAttributes, entryPoint). Browser uses a
+   *                         single global scope; Node uses an AsyncLocalStorage-
+   *                         backed provider so each request gets its own.
+   */
+  constructor(api?: Api, contextCollector?: ContextCollector, fileReader?: FileReader, scopeProvider?: ScopeProvider);
+  /**
+   * Register an in-flight report so `flush()` can wait for it. Called by
+   * every public report entry point (`report`, `reportSilently`,
+   * `reportMessage`, `reportUnhandledRejection`, `test`); each wraps its
+   * full async pipeline (beforeEvaluate -> stack trace + source snippets ->
+   * beforeSubmit -> `api.report()`) so the entire roundtrip is what's
+   * tracked, not just the HTTP send at the end.
+   *
+   * Two problems this method solves at once.
+   *
+   * Problem 1: hold a reference to the work without leaking rejections.
+   *
+   *   `p` is the real report pipeline; it can reject (network failure,
+   *   `beforeSubmit` throws, etc). If we stored `p` directly in `inflight`
+   *   and no caller attached a `.catch` (the global error listeners use
+   *   `reportSilently` which DOES catch, but the path is still subtle), an
+   *   eventual rejection would surface as an unhandled-rejection warning
+   *   on Node and a console error in the browser. Bad citizen.
+   *
+   *   So we build a SHADOW promise that mirrors `p`'s timing but cannot
+   *   reject:
+   *
+   *     p.then(
+   *         () => undefined,   // on fulfilment, value is undefined
+   *         () => undefined,   // on rejection, ALSO resolve with undefined
+   *     )
+   *
+   *   Providing the second argument means we have "handled" any rejection
+   *   from `p`. The shadow always resolves with `undefined`, and `p`'s
+   *   rejection is consumed at the boundary. From the runtime's point of
+   *   view, the shadow is well-behaved.
+   *
+   * Problem 2: self-cleaning entry.
+   *
+   *   `tracked.finally(() => this.inflight.delete(tracked))`. `finally`
+   *   fires whether the shadow resolves or rejects, but the shadow can no
+   *   longer reject (problem 1 normalized it), so this is effectively
+   *   "when the underlying report has settled, remove me from the Set."
+   *   No GC magic, no external cleanup, no race window.
+   *
+   *   Note that `.finally` itself returns a new promise that we drop on
+   *   the floor. If the cleanup callback ever throws, that would surface
+   *   as an unhandled rejection on the dropped promise; `delete` does not
+   *   throw so we are safe today, but anything more elaborate added here
+   *   should be wrapped in try/catch.
+   *
+   * The return value is the ORIGINAL `p`. The caller awaits real success
+   * or failure; the tracking is completely invisible to them. This is why
+   * `await flare.report(err)` inside a fatal handler observes network
+   * errors the same as before tracking was added.
+   */
+  private track;
+  /**
+   * Wait until every in-flight report settles, or until `timeoutMs`
+   * elapses, whichever comes first. Always resolves; never rejects.
+   *
+   * The main consumer is `@flareapp/node`'s fatal handler:
+   *
+   *     process.on('uncaughtException', async (err) => {
+   *         process.exitCode = 1;
+   *         try { await flare.report(err); } catch {}
+   *         await flare.flush(shutdownTimeoutMs);
+   *         process.exit(1);
+   *     });
+   *
+   * The fatal `report` is awaited explicitly; `flush` then drains any
+   * OTHER reports that were already in flight (a request handler that
+   * fired `flare.report(...)` concurrently with the crash). The timeout
+   * caps the wait so a hung HTTP request cannot indefinitely block
+   * shutdown.
+   *
+   * Walking the implementation:
+   *
+   *   const pending = [...this.inflight];
+   *
+   *     Spread takes a SNAPSHOT of the Set at this instant. Reports that
+   *     start AFTER this line are not included in `pending`, so they are
+   *     not awaited by THIS flush call. This is intentional: it bounds
+   *     the wait. Without the snapshot, a handler that kept emitting
+   *     reports during shutdown could keep flush alive forever and block
+   *     the process from exiting.
+   *
+   *   if (pending.length === 0) return Promise.resolve();
+   *
+   *     Fast path. No timer scheduled, no promise constructor needed.
+   *     Resolves on the microtask queue. Cheap.
+   *
+   *   return new Promise<void>((resolve) => {
+   *       const timer = setTimeout(resolve, timeoutMs);
+   *       Promise.allSettled(pending).then(() => {
+   *           clearTimeout(timer);
+   *           resolve();
+   *       });
+   *   });
+   *
+   *     The race between two outcomes, both calling the same `resolve`:
+   *
+   *     1. `setTimeout(resolve, timeoutMs)` schedules a "give up" call.
+   *        After `timeoutMs` it fires, calling `resolve()` from the
+   *        timer-queue side. The outer promise resolves immediately,
+   *        even if reports are still pending. Those reports are abandoned
+   *        (they continue running but the process is about to die).
+   *
+   *     2. `Promise.allSettled(pending)` returns a promise that resolves
+   *        when every promise in `pending` has either fulfilled or
+   *        rejected. It NEVER rejects on its own. We use `allSettled`
+   *        rather than `Promise.all` because `all` short-circuits on the
+   *        first rejection -- we want to wait for everyone regardless of
+   *        whether their HTTP calls succeed or fail. (Our shadows cannot
+   *        reject anyway because `track` normalized them, but using
+   *        `allSettled` documents the intent and survives future changes
+   *        to shadow construction.) When it resolves, we call
+   *        `clearTimeout(timer)` to cancel the pending timer (so it does
+   *        not fire later and call `resolve` a second time -- a no-op,
+   *        but wasted work) and then `resolve()` ourselves.
+   *
+   *   Resolve can only meaningfully fire once. Subsequent calls to the
+   *   same `resolve` are silently ignored by the Promise spec, so the
+   *   race is safe even if for some reason both branches fired together.
+   *
+   * Things flush() deliberately does NOT do:
+   *
+   *   - It does not reject. Even if every report failed, allSettled
+   *     resolves. Callers do not need a `.catch`.
+   *   - It does not retry. One pipeline attempt per report, then move on.
+   *   - It does not stop new reports from starting. The Flare instance
+   *     is still usable after flush resolves. flush is "wait for what is
+   *     in flight," not "freeze the SDK."
+   *   - It does not drain reports started after the snapshot. Call flush
+   *     again if you need to wait for those too.
+   */
+  flush(timeoutMs?: number): Promise<void>;
+  get config(): Readonly<Config>;
+  get glows(): readonly Glow[];
+  light(key?: string, debug?: boolean): this;
+  configure(config: Partial<Config>): this;
+  test(): Promise<void>;
+  private testInternal;
+  glow(name: string, level?: MessageLevel, data?: Record<string, unknown> | Record<string, unknown>[]): this;
+  clearGlows(): this;
+  addContext(name: string, value: AttributeValue): this;
+  addContextGroup(groupName: string, value: Record<string, AttributeValue>): this;
+  setEntryPoint(handler: EntryPointHandler): this;
+  setSdkInfo(info: SdkInfo): this;
+  setFramework(framework: Framework): this;
+  report(error: Error, attributes?: Attributes): Promise<void>;
+  private reportInternal;
+  reportSilently(error: Error, attributes?: Attributes): void;
+  reportUnhandledRejection(message: string, attributes?: Attributes): Promise<void>;
+  private reportUnhandledRejectionInternal;
+  reportMessage(message: string, level?: MessageLevel, attributes?: Attributes): Promise<void>;
+  private reportMessageInternal;
+  createReportFromError(error: Error, attributes?: Attributes, seenAtUnixNano?: number): Promise<Report | false>;
+  private buildReport;
+  sendReport(report: Report): Promise<void>;
+}
+//#endregion
+//#region src/stacktrace/NullFileReader.d.ts
+/**
+ * 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.
+ */
+declare class NullFileReader implements FileReader {
+  read(_url: string): Promise<string | null>;
+}
+//#endregion
+//#region src/stacktrace/createStackTrace.d.ts
+declare function createStackTrace(error: Error, debug: boolean, fileReader: FileReader): Promise<Array<StackFrame>>;
+//#endregion
+export { Api, type AttributeValue, type Attributes, type Config, type ContextCollector, DEFAULT_URL_DENYLIST, type EntryPointHandler, type FileReader, Flare, type Framework, GlobalScopeProvider, type Glow, type MessageLevel, NullFileReader, 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 };