@maple-dev/browser 0.8.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.
@@ -26,18 +27,148 @@ interface MapleIdentity {
  */
 type IdentifyInput = string | null | undefined | MapleIdentity;
 //#endregion
-//#region ../browser-session/src/events/track.d.ts
+//#region ../browser-session/src/events/props.d.ts
 /** Properties a host app may attach to a custom event. */
 type TrackProps = Readonly<Record<string, unknown>>;
 //#endregion
+//#region ../browser-session/src/platform/region.d.ts
+/** 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;
-  /** Maple ingest base URL. Defaults to `https://ingest.maple.dev`. */
+  /**
+   * Region your Maple organization lives in: `"us"` (default,
+   * `https://ingest.maple.dev`) or `"eu"` (`https://ingest.eu.maple.dev`).
+   * Ingest keys belong to one region. Ignored when `endpoint` is set.
+   */
+  readonly region?: MapleRegion;
+  /** Maple ingest base URL. Overrides `region`; use it for a proxy or self-hosted ingest. */
   readonly endpoint?: string;
   /**
    * Logical group this service belongs to, emitted as the OTel
@@ -57,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;
     /**
@@ -67,13 +198,26 @@ 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
+     * the page's global error handlers, or the same crash lands twice.
+     */
+    readonly captureErrors?: boolean;
+    /**
+     * Cross-origin URLs whose `fetch()` requests carry the W3C `traceparent`
+     * header, so the browser span and your backend's span join one trace.
+     * Same-origin requests always carry it. Your API must allow the
+     * `traceparent` header in CORS. Example: `[/^https:\/\/api\.example\.com\//]`.
+     */
+    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;
@@ -107,9 +251,25 @@ interface MapleBrowserConfig {
     readonly captureUserEmail?: boolean;
     /** Treat `navigator.doNotTrack` like Global Privacy Control. Default false. */
     readonly respectDoNotTrack?: boolean;
+    /**
+     * Rewrite every URL before it leaves the page: session entry and exit
+     * URLs, event rows, network events, replay meta events, and span
+     * attributes. Runs after the built-in redaction, which already replaces
+     * the values of credential-shaped query and fragment parameters
+     * (`token`, `code`, `access_token`, `password`, …).
+     */
+    readonly sanitizeUrl?: (url: string) => string;
   };
 }
 //#endregion
+//#region src/errors.d.ts
+interface CaptureExceptionOptions {
+  /** Span name. Default `"exception"`. */
+  readonly name?: string | undefined;
+  /** Extra span attributes. */
+  readonly attributes?: Record<string, string | number | boolean> | undefined;
+}
+//#endregion
 //#region src/init.d.ts
 interface MapleBrowserHandle {
   /** Empty until consent is granted when `requireConsent` is enabled. */
@@ -118,7 +278,64 @@ 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. */
+export interface MapleBrowserApi {
+  init: (config: MapleBrowserConfig) => MapleBrowserHandle;
+  /**
+   * Attach, replace, or clear the end-user identity on the active session.
+   * Accepts a bare user id or the full identity object. Safe to call repeatedly,
+   * and before `init` (the latest call is applied when `init` runs).
+   */
+  identify: (input?: IdentifyInput) => void;
+  /**
+   * Record a custom product event against the active session. Safe to call
+   * before `init` — events are queued (capped) and drained once the session
+   * starts.
+   */
+  track: (name: string, props?: TrackProps) => void;
+  /**
+   * Report an error your app already caught — the case the global handlers
+   * cannot see, because catching it is what stops it reaching them. A
+   * framework error boundary is the canonical caller. The same error object
+   * is recorded once, even if it is rethrown afterwards.
+   *
+   * BOUNDARY: a thrown value is unparsed by definition — JavaScript can throw
+   * anything. `captureException` narrows it before it reaches a span.
+   */
+  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
  * replay, both tagged with a shared session id.
@@ -130,27 +347,13 @@ interface MapleBrowserHandle {
  * MapleBrowser.init({
  *   ingestKey: "maple_pk_...",
  *   serviceName: "acme-web",
+ *   region: "eu", // omit for the US region
  * })
  *
  * MapleBrowser.identify({ id: user.id, email: user.email, groupId: org.id, groupName: org.name })
  * MapleBrowser.track("checkout_completed", { plan: "pro", seats: 5 })
  * ```
  */
-declare const MapleBrowser: {
-  init: (config: MapleBrowserConfig) => MapleBrowserHandle;
-  /**
-   * Attach, replace, or clear the end-user identity on the active session.
-   * Accepts a bare user id or the full identity object. Safe to call repeatedly.
-   */
-  identify: (input?: IdentifyInput) => void;
-  /**
-   * Record a custom product event against the active session. Safe to call
-   * before `init` — events are queued (capped) and drained once the session
-   * starts.
-   */
-  track: (name: string, props?: TrackProps) => void;
-  /** Grant or revoke consent when `privacy.requireConsent` is on. */
-  setConsent: (granted: boolean) => void;
-};
+export declare const MapleBrowser: MapleBrowserApi;
 //#endregion
-export { type IdentifyInput, MapleBrowser, type MapleBrowserConfig, type MapleBrowserHandle, type MapleIdentity, 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 };