@maple-dev/browser 0.9.0 → 0.10.0

package/dist/index.d.mts

@@ -1,3 +1,4 @@
+import "@opentelemetry/api";
 //#region ../browser-session/src/identity/identity.d.ts
 /**
  * Who the current visitor is.
@@ -34,11 +35,131 @@ type TrackProps = Readonly<Record<string, unknown>>;
 /** A Maple hosting region. Each is a separate instance with its own ingest keys. */
 type MapleRegion = "us" | "eu";
 //#endregion
+//#region ../sdk-core/src/http-status.d.ts
+/** A status code, or an inclusive `[from, to]` range. */
+type HttpStatusRange = number | readonly [number, number];
+//#endregion
+//#region ../sdk-core/src/error-filters.d.ts
+type ErrorSource = "captureException" | "window.onerror" | "unhandledrejection";
+interface ErrorFilterHint {
+  readonly source: ErrorSource;
+  /** What was thrown, before it was normalized into an `Error`. */
+  readonly originalError: unknown;
+}
+interface ErrorFilterOptions {
+  /** Drop errors whose `Name: message` contains a string or matches a RegExp. */
+  readonly ignore?: ReadonlyArray<string | RegExp>;
+  /** Report only errors whose top frame's script URL matches one of these. Errors with no frames are kept. */
+  readonly allowUrls?: ReadonlyArray<string | RegExp>;
+  /** Drop errors whose top frame's script URL matches one of these. */
+  readonly denyUrls?: ReadonlyArray<string | RegExp>;
+  /** Return `false` to drop the error. Runs after the lists; if it throws, the error is kept. */
+  readonly beforeCapture?: (error: Error, hint: ErrorFilterHint) => boolean;
+  /**
+   * HTTP response statuses that make a client request span an error (and so an
+   * issue), e.g. `[[500, 599]]`. Default none: a response status alone is not
+   * an error, and a network failure always is.
+   */
+  readonly captureHttpStatus?: ReadonlyArray<HttpStatusRange>;
+  /**
+   * Drop errors thrown from browser extensions and the benign `ResizeObserver
+   * loop` notices. Default true.
+   */
+  readonly defaultFilters?: boolean;
+}
+//#endregion
+//#region ../sdk-core/src/http-headers.d.ts
+interface HeaderCaptureOptions {
+  readonly request?: ReadonlyArray<string>;
+  readonly response?: ReadonlyArray<string>;
+}
+//#endregion
+//#region ../sdk-core/src/log-record.d.ts
+type LogAttributeValue = string | number | boolean;
+//#endregion
+//#region ../sdk-core/src/options.d.ts
+type ConsoleLevel = "debug" | "log" | "info" | "warn" | "error";
+interface TracingSignalOptions {
+  /**
+   * Fraction of sessions whose traces are exported, 0–1. Default 1. Decided
+   * once per session, so a sampled session keeps every trace. Error spans are
+   * always exported.
+   */
+  readonly sampleRate?: number;
+  /**
+   * Request and response headers to record on HTTP client spans, as
+   * `http.request.header.<name>` / `http.response.header.<name>`. Default none.
+   * Credential headers (`authorization`, `cookie`, `set-cookie`, ...) are never recorded.
+   */
+  readonly captureHeaders?: HeaderCaptureOptions;
+  /** Span main-thread frames of 100ms or more. Default false. */
+  readonly longFrames?: boolean;
+  /** Span interactions of 200ms or more, split into input delay, processing and presentation. Default false. */
+  readonly slowInteractions?: boolean;
+}
+interface ReplayOptions {
+  /** Record session replays. Default true. */
+  readonly enabled?: boolean;
+  /** Fraction of sessions to record, 0–1. Default 1. */
+  readonly sampleRate?: number;
+  /**
+   * Fraction of the sessions not recorded that keep the last minute in memory,
+   * and upload it and record the rest of the session only if an error happens.
+   * 0–1, default 0.
+   */
+  readonly onErrorSampleRate?: number;
+  /**
+   * Record `<canvas>` content at this many frames per second. Off by default,
+   * and never with `maskAllText`: canvas pixels can hold text.
+   */
+  readonly canvasFps?: number;
+  /**
+   * Keep text bodies on the replay's network events for these full URLs, cut to
+   * `maxLength` characters (at most and by default 1,000). Nothing with
+   * `maskAllText`; request bodies only with `maskAllInputs` off.
+   */
+  readonly networkBodies?: {
+    readonly urls: ReadonlyArray<string | RegExp>;
+    readonly maxLength?: number;
+  };
+}
+/** The signal options shared verbatim by `MapleBrowser.init` and the Effect client presets. */
+interface SignalOptions {
+  readonly tracing?: TracingSignalOptions;
+  /** Which captured errors to drop, and which HTTP statuses count as errors. */
+  readonly errors?: ErrorFilterOptions;
+  /** Report Core Web Vitals as `browser.web_vital` log events. Default true. */
+  readonly webVitals?: boolean;
+  /** Keep the last clicks, inputs, navigations and console lines, and export them with the next error. Default true. */
+  readonly breadcrumbs?: boolean;
+  readonly logs?: {
+    /** Console levels exported as logs as they happen, e.g. `["warn", "error"]`. Default none. */
+    readonly captureConsole?: ReadonlyArray<ConsoleLevel>;
+  };
+  readonly reporting?: {
+    /** Content Security Policy violations as `maple.browser.csp_violation` WARN logs. Default true. */
+    readonly csp?: boolean;
+    /** Browser deprecation and intervention reports as `maple.browser.report` WARN logs. Default false. */
+    readonly browserReports?: boolean;
+  };
+  readonly transport?: {
+    /**
+     * Keep batches that could not be sent in IndexedDB for up to 24 hours and
+     * send them once the browser is back online or on the next page load. Default false.
+     */
+    readonly offline?: boolean;
+  };
+}
+//#endregion
 //#region src/config.d.ts
-/** Public configuration for `MapleBrowser.init`. */
-interface MapleBrowserConfig {
-  /** Public ingest key (`maple_pk_...`). */
-  readonly ingestKey: string;
+/** Public configuration for `MapleBrowser.init`. The signal groups are shared with the Effect SDK. */
+interface MapleBrowserConfig extends SignalOptions {
+  /**
+   * Public ingest key (`maple_pk_...`), sent as `Authorization: Bearer …` and
+   * nothing else. Leave it unset when a proxy at `endpoint` adds auth: tracing
+   * and replay still run, sending without the header.
+   */
+  readonly ingestKey?: string;
   /** Service name reported on traces and stored on replay sessions. */
   readonly serviceName: string;
   /**
@@ -67,7 +188,7 @@ interface MapleBrowserConfig {
   readonly userId?: string | null | undefined;
   /** End-user identity attached to sessions and browser spans. */
   readonly user?: MapleIdentity | undefined;
-  readonly tracing?: {
+  readonly tracing?: TracingSignalOptions & {
     /** Default true. */
     readonly enabled?: boolean;
     /**
@@ -77,6 +198,11 @@ interface MapleBrowserConfig {
      * sink, and disabling this avoids redundant duplicate network spans.
      */
     readonly instrumentFetch?: boolean;
+    /**
+     * Auto-instrument `XMLHttpRequest` (axios and older clients) the same way.
+     * Default true. Turn it off for the same reason as `instrumentFetch`.
+     */
+    readonly instrumentXhr?: boolean;
     /**
      * Capture uncaught errors and unhandled promise rejections as error
      * spans. Default true. Turn off only when another tracker already owns
@@ -91,12 +217,7 @@ interface MapleBrowserConfig {
      */
     readonly propagateTraceHeaderCorsUrls?: ReadonlyArray<string | RegExp>;
   };
-  readonly replay?: {
-    /** Default true. */
-    readonly enabled?: boolean;
-    /** Fraction of sessions to record, 0–1. Default 1. */
-    readonly sampleRate?: number;
-  };
+  readonly replay?: ReplayOptions;
   readonly privacy?: {
     /** Mask all `<input>` values. Default true. */
     readonly maskAllInputs?: boolean;
@@ -157,9 +278,24 @@ interface MapleBrowserHandle {
   readonly shutdown: () => Promise<void>;
 }
 //#endregion
+//#region src/logger.d.ts
+type LogMethod = (message: string, attributes?: Readonly<Record<string, LogAttributeValue>>) => void;
+interface MapleLogger {
+  readonly debug: LogMethod;
+  readonly info: LogMethod;
+  readonly warn: LogMethod;
+  readonly error: LogMethod;
+}
+//#endregion
+//#region src/navigation.d.ts
+interface TracedOptions {
+  /** Return `false` for throws that aren't errors, like redirects or not-found. Default: every throw is an error. */
+  readonly isFailure?: ((error: unknown) => boolean) | undefined;
+}
+//#endregion
 //#region src/index.d.ts
 /** The `MapleBrowser` namespace object. */
-interface MapleBrowserApi {
+export interface MapleBrowserApi {
   init: (config: MapleBrowserConfig) => MapleBrowserHandle;
   /**
    * Attach, replace, or clear the end-user identity on the active session.
@@ -185,6 +321,20 @@ interface MapleBrowserApi {
   captureException: (error: unknown, options?: CaptureExceptionOptions) => void;
   /** Grant or revoke consent when `privacy.requireConsent` is on. */
   setConsent: (granted: boolean) => void;
+  /** Call when a route change starts, with the new path. The first call in a page is the page load. */
+  startNavigation: (path: string) => void;
+  /** Call when the new route is ready, with its route pattern (`/projects/:id`), not the URL. */
+  endNavigation: (route?: string) => void;
+  /**
+   * Run data loading, like a route loader, in a span under the current navigation.
+   * Errors are recorded once and rethrown. Only requests started before `fn`'s first `await` nest under the span.
+   */
+  traced: <T>(name: string, fn: () => Promise<T>, options?: TracedOptions) => Promise<T>;
+  /**
+   * Structured logs, exported as OpenTelemetry log records linked to the active
+   * span and the session. Safe before `init`: records queue until it runs.
+   */
+  logger: MapleLogger;
 }
 /**
  * Maple browser SDK. One call wires up OpenTelemetry tracing and rrweb session
@@ -204,6 +354,6 @@ interface MapleBrowserApi {
  * MapleBrowser.track("checkout_completed", { plan: "pro", seats: 5 })
  * ```
  */
-declare const MapleBrowser: MapleBrowserApi;
+export declare const MapleBrowser: MapleBrowserApi;
 //#endregion
-export { type CaptureExceptionOptions, type IdentifyInput, MapleBrowser, MapleBrowserApi, type MapleBrowserConfig, type MapleBrowserHandle, type MapleIdentity, type MapleRegion, type TrackProps, type TraitValue };
+export type { CaptureExceptionOptions, ConsoleLevel, ErrorFilterHint, ErrorFilterOptions, ErrorSource, HttpStatusRange, IdentifyInput, LogAttributeValue, MapleBrowserConfig, MapleBrowserHandle, MapleIdentity, MapleLogger, MapleRegion, ReplayOptions, SignalOptions, TracedOptions, TracingSignalOptions, TrackProps, TraitValue };