@flareapp/core 2.6.0 → 2.8.0

package/dist/urlAttributes-B9BlkrfW.d.mts

@@ -0,0 +1,452 @@
+//#region src/framework.d.ts
+/**
+ * Framework names the Flare backend recognises. Wire format, so the values never change: they ship as
+ * `flare.framework.name` and (lowercased) as `context.custom.framework`.
+ *
+ * `Js` and `Node` are the base SDKs' fallback claim, overwritten when a framework package tags its
+ * own name. `NodeElectron` is an Electron main process; its renderers report their own.
+ */
+declare const FrameworkName: {
+  readonly Js: "js";
+  readonly Node: "node";
+  readonly NodeElectron: "node-electron";
+  readonly React: "react";
+  readonly Vue: "vue";
+  readonly Svelte: "svelte";
+  readonly SvelteKit: "sveltekit";
+  readonly ReactNative: "react-native";
+};
+type FrameworkName = (typeof FrameworkName)[keyof typeof FrameworkName];
+//#endregion
+//#region src/spanTypes.d.ts
+/**
+ * Span types the Flare backend recognises. Wire format, so the values never change: they ship as the
+ * `flare.span_type` attribute and the backend groups performance data by them.
+ *
+ * These are the browser client's set. They live in core because core's `SpanOptions.spanType` needs
+ * to name them and core cannot import from `@flareapp/js`.
+ */
+declare const BrowserSpanType: {
+  readonly Pageload: "browser_pageload";
+  readonly Navigation: "browser_navigation";
+  readonly Fetch: "browser_fetch";
+  readonly Xhr: "browser_xhr";
+  readonly Component: "browser_component";
+  readonly WebVital: "browser_web_vital";
+};
+type BrowserSpanType = (typeof BrowserSpanType)[keyof typeof BrowserSpanType];
+/** Any other value stays legal, so a host SDK can stamp its own without a core release. */
+type SpanTypeName = BrowserSpanType | (string & {});
+//#endregion
+//#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>;
+/**
+ * An identified user passed to `Flare.setUser`. Known fields map to the backend keys: `id`->`user.id`,
+ * `email`->`user.email`, `fullName`->`user.full_name`, `ipAddress`->`client.address`. Any other key lands in
+ * `user.attributes`. Caveat: the open index signature means a misspelled known field (e.g. `full_name` for `fullName`)
+ * silently lands in `user.attributes` with no type error. 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;
+  sourcemapVersionId: string;
+  stage: string;
+  maxGlowsPerReport: number;
+  reportBrowserExtensionErrors: boolean;
+  ingestUrl: string;
+  debug: boolean;
+  urlDenylist: RegExp;
+  replaceDefaultUrlDenylist: boolean;
+  sampleRate: number;
+  enableLogs: boolean;
+  logsIngestUrl: string;
+  minimumLogLevel?: MessageLevel;
+  serviceName?: string;
+  maxLogBufferSize: number;
+  logFlushIntervalMs: number;
+  logFlushMaxBytes: number;
+  keepaliveMaxBytes: number;
+  enableTracing: boolean;
+  tracesIngestUrl: string;
+  tracesSampleRate: number;
+  tracesSampler?: TracesSampler;
+  /**
+   * URLs a W3C `traceparent` header may be attached to on outgoing requests. Default (unset): same-origin + relative
+   * only; `[]` disables all injection. Each entry matches by String.includes (string) or RegExp.test. Attaching
+   * cross-origin forces a CORS preflight; the target server must allow the `traceparent` request header.
+   */
+  tracePropagationTargets?: (string | RegExp)[]; /** Idle-span: ms of no open child spans before a pageload/navigation root closes. Browser default 1000. */
+  idleTimeout?: number; /** Idle-span: hard cap in ms from root start before it closes regardless of activity. Browser default 30000. */
+  finalTimeout?: number; /** Idle-span: if a child span stays open this many ms, the root closes anyway. Browser default 15000. */
+  childSpanTimeout?: number;
+  maxSpanBufferSize: number;
+  spanFlushIntervalMs: number;
+  spanFlushMaxBytes: number;
+  maxSpansPerTrace: number;
+  maxAttributesPerSpan: number;
+  maxEventsPerSpan: number;
+  maxAttributesPerSpanEvent: 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>[];
+};
+/** The values the backend accepts for `flare.entry_point.type`. Anything else is dropped. */
+type EntryPointType = 'web' | 'queue' | 'cli';
+type EntryPointHandler = {
+  identifier?: string;
+  name?: string;
+  type?: string;
+};
+type SdkInfo = {
+  name: string;
+  version: string;
+};
+/**
+ * The framework identity an SDK reports. `name` is wire format, not a display string: first-party
+ * SDKs use a `FrameworkName`. A host app may call `setFramework` with its own value (e.g. `express`),
+ * which the backend treats as unknown rather than rejecting, so the type stays open.
+ */
+type Framework = {
+  name: FrameworkName | (string & {});
+  version?: string;
+};
+type AnyValue = {
+  stringValue: string;
+} | {
+  boolValue: boolean;
+} | {
+  intValue: number;
+} | {
+  doubleValue: number;
+} | {
+  arrayValue: {
+    values: AnyValue[];
+  };
+} | {
+  kvlistValue: {
+    values: KeyValue[];
+  };
+};
+type KeyValue = {
+  key: string;
+  value: AnyValue;
+};
+type OtelResource = {
+  attributes: KeyValue[];
+  droppedAttributesCount: number;
+};
+type OtelScope = {
+  name: string;
+  version: string;
+  attributes: KeyValue[];
+  droppedAttributesCount: number;
+};
+type OtelLogRecord = {
+  timeUnixNano: string;
+  observedTimeUnixNano: string;
+  severityNumber: number;
+  severityText: string;
+  body: AnyValue;
+  attributes: KeyValue[];
+  flags: number;
+  droppedAttributesCount: number;
+};
+type LogsEnvelope = {
+  resourceLogs: Array<{
+    resource: OtelResource;
+    scopeLogs: Array<{
+      scope: OtelScope;
+      logRecords: OtelLogRecord[];
+    }>;
+  }>;
+};
+type BufferedLog = {
+  timeUnixNano: string;
+  severityNumber: number;
+  severityText: string;
+  message: string;
+  recordAttributes: KeyValue[];
+  resourceAttributes: Attributes;
+};
+/** OTel status codes. Wire format: these numbers ship in the span envelope, so the values never change. */
+declare const SpanStatusCode: {
+  readonly Unset: 0;
+  readonly Ok: 1;
+  readonly Error: 2;
+};
+type SpanStatusCode = (typeof SpanStatusCode)[keyof typeof SpanStatusCode];
+type SpanStatus = {
+  code: SpanStatusCode;
+  message?: string;
+};
+type SpanOptions = {
+  parent?: Span | {
+    traceId: string;
+    spanId: string;
+  };
+  attributes?: Attributes;
+  startTimeUnixNano?: number;
+  spanType?: SpanTypeName;
+  /**
+   * Start this span as a new trace root, ignoring any ambient active span, so a
+   * root opened inside `withSpan(...)` does not become a mid-trace child.
+   */
+  forceRoot?: boolean; /** Use this exact span id instead of generating one (manual span stitching). */
+  spanId?: string; /** This span's slot against `maxSpansPerTrace` was already taken by `Tracer.claimSpanSlot`. */
+  claimed?: boolean;
+};
+interface Span {
+  readonly traceId: string;
+  readonly spanId: string;
+  readonly parentSpanId: string | null;
+  name: string;
+  readonly isRecording: boolean;
+  readonly endTimeUnixNano: number;
+  setAttribute(key: string, value: AttributeValue): this;
+  setStatus(status: SpanStatus): this;
+  addEvent(name: string, attributes?: Attributes): this;
+  end(endTimeUnixNano?: number): void;
+}
+type SamplingContext = {
+  name: string;
+  parentSampled?: boolean;
+  attributes: Attributes;
+  spanType?: SpanTypeName;
+};
+type TracesSampler = (ctx: SamplingContext) => number | boolean;
+type BufferedSpanEvent = {
+  name: string;
+  timeUnixNano: number;
+  attributes: KeyValue[];
+  droppedAttributesCount: number;
+};
+type BufferedSpan = {
+  traceId: string;
+  spanId: string;
+  parentSpanId: string | null;
+  name: string;
+  startTimeUnixNano: number;
+  endTimeUnixNano: number;
+  status: SpanStatus;
+  recordAttributes: KeyValue[];
+  droppedAttributesCount: number;
+  droppedEventsCount: number;
+  events: BufferedSpanEvent[];
+};
+type OtelSpan = {
+  traceId: string;
+  spanId: string;
+  parentSpanId: string | null;
+  name: string;
+  startTimeUnixNano: number;
+  endTimeUnixNano: number;
+  status: SpanStatus;
+  attributes: KeyValue[];
+  events: BufferedSpanEvent[];
+  droppedAttributesCount: number;
+  droppedEventsCount: number;
+  links: never[];
+  droppedLinksCount: number;
+};
+type TracesEnvelope = {
+  resourceSpans: Array<{
+    resource: OtelResource;
+    scopeSpans: Array<{
+      scope: OtelScope;
+      spans: OtelSpan[];
+    }>;
+  }>;
+};
+//#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/componentMatcher.d.ts
+/** What a framework integration's `profileComponents` option accepts. */
+type ProfileComponentsOption = boolean | (string | RegExp)[];
+/**
+ * Built once so a mount costs one name resolution and one match. Strings match exactly, regexes by
+ * `test()`.
+ */
+declare function createComponentMatcher(option: ProfileComponentsOption): (name: string) => boolean;
+//#endregion
+//#region src/util/convertToError.d.ts
+declare function convertToError(error: unknown): Error;
+//#endregion
+//#region src/util/createIdentityTagger.d.ts
+/** Minimal surface the tagger needs; the browser Flare and any subclass satisfy it structurally. */
+interface SdkTaggable {
+  setSdkInfo(info: SdkInfo): unknown;
+  setFramework(framework: Framework): unknown;
+}
+/**
+ * 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.
+ */
+declare function createIdentityTagger(config: {
+  sdkName: string;
+  sdkVersion: string;
+  frameworkName: FrameworkName;
+}): {
+  registerSdkIdentity(flare: SdkTaggable): void;
+  tagFramework(flare: SdkTaggable, frameworkVersion?: string): void;
+};
+//#endregion
+//#region src/util/extractCode.d.ts
+declare function extractCode(error: Error): string | undefined;
+//#endregion
+//#region src/util/flatJsonStringify.d.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.
+ */
+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;
+/**
+ * Strips userinfo (`user:pass@`) from an absolute URL and replaces query-string values whose key
+ * matches `denylist` with `[redacted]`. Path segments are left untouched.
+ */
+declare function redactUrlQuery(fullPath: string, denylist?: RegExp): string;
+/**
+ * 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.
+ */
+declare function redactObjectValues(obj: Record<string, unknown>, denylist?: RegExp): Record<string, unknown>;
+/**
+ * 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.
+ */
+declare function safeDecode(value: string): string;
+//#endregion
+//#region src/util/rejection.d.ts
+type RejectionReporter = {
+  /** Error / stack-bearing reasons: preserve the stack. */reportSilently: (error: Error) => void; /** Stackless reasons. May return a promise; `routeRejection` swallows any rejection from it. */
+  reportUnhandledRejection: (message: string) => unknown;
+};
+/** Best-effort human-readable description of an arbitrary rejection reason. */
+declare function describeRejectionReason(reason: unknown): 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.
+ */
+declare function routeRejection(reporter: RejectionReporter, reason: unknown): void;
+//#endregion
+//#region src/util/safeClone.d.ts
+type SafeCloneOptions = {
+  mode: 'json';
+} | {
+  mode: 'display';
+  maxDepth: number;
+  arrayCap: number;
+  objectKeyCap: number;
+  stringCap: number;
+  denylist: RegExp;
+};
+/**
+ * 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.
+ */
+declare function safeClone(value: unknown, options: SafeCloneOptions): unknown;
+//#endregion
+//#region src/util/statelessRegExp.d.ts
+/**
+ * A `/g` or `/y` regex carries `lastIndex` between `test()` calls, so every other call misses. Returns
+ * a copy rather than mutating what the caller handed us.
+ */
+declare function withoutStatefulFlags(pattern: RegExp): RegExp;
+declare function withoutStatefulFlags(pattern: RegExp | undefined): RegExp | undefined;
+//#endregion
+//#region src/util/toCustomContext.d.ts
+/** Wraps a framework payload as the `context.custom` attribute a report expects. */
+declare function toCustomContext(framework: string, payload: AttributeValue): Attributes;
+//#endregion
+//#region src/util/urlAttributes.d.ts
+/** Well past any routable URL, but short enough that an inline `data:` payload cannot ride along. */
+declare const MAX_URL_LENGTH = 2048;
+/**
+ * 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.
+ */
+declare function urlAttributes(url: string, denylist?: RegExp): Attributes;
+//#endregion
+export { User as $, BufferedSpan as A, OtelSpan as B, createComponentMatcher as C, AttributeValue as D, AnyValue as E, Glow as F, Span as G, Report as H, KeyValue as I, SpanStatus as J, SpanEvent as K, LogsEnvelope as L, EntryPointHandler as M, EntryPointType as N, Attributes as O, Framework as P, TracesSampler as Q, MessageLevel as R, ProfileComponentsOption as S, assert as T, SamplingContext as U, OverriddenGrouping as V, SdkInfo as W, StackFrame as X, SpanStatusCode as Y, TracesEnvelope as Z, flatJsonStringify as _, SafeCloneOptions as a, createIdentityTagger as b, describeRejectionReason as c, redactObjectValues as d, BrowserSpanType as et, redactUrlQuery as f, glowsToEvents as g, now as h, withoutStatefulFlags as i, Config as j, BufferedLog as k, routeRejection as l, safeDecode as m, urlAttributes as n, FrameworkName as nt, safeClone as o, resolveDenylist as p, SpanOptions as q, toCustomContext as r, RejectionReporter as s, MAX_URL_LENGTH as t, SpanTypeName as tt, DEFAULT_URL_DENYLIST as u, extractCode as v, assertKey as w, convertToError as x, SdkTaggable as y, OtelLogRecord as z };