@maple-dev/browser 0.4.0 → 0.9.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Maple Tech Labs
+Copyright (c) 2026 Makisuo, Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -19,6 +19,7 @@ import { MapleBrowser } from "@maple-dev/browser"
 MapleBrowser.init({
 	ingestKey: "maple_pk_...", // public ingest key
 	serviceName: "acme-web",
+	region: "eu", // "us" (default) or "eu"; must match your organization's region
 	environment: "production",
 	replay: { enabled: true, sampleRate: 1.0 },
 	privacy: { maskAllInputs: true },
@@ -33,9 +34,55 @@ That single call:
   gzipping them with the native `CompressionStream`, and uploading to
   `POST /v1/sessionReplays/blob`. rrweb ships in a lazy code-split chunk loaded
   only once a session is sampled in, so a `sampleRate` below 1 costs the
-  unsampled visitors nothing beyond the ~8 kB gzipped base SDK;
+  unsampled visitors nothing beyond the base SDK (see [Bundle size](#bundle-size));
 - writes session metadata at start (`active`) and on page hide (`ended`),
-  including the trace ids observed during the session.
+  including the trace ids observed during the session;
+- captures uncaught errors and unhandled promise rejections as error spans, so
+  browser crashes reach Maple's error tracking.
+
+## Errors
+
+Every uncaught error and unhandled rejection becomes a span with status `Error`
+and an `exception` event, which is the shape Maple fingerprints — so browser
+crashes group beside your server-side errors instead of in a silo.
+
+Errors your app _catches_ never reach the global handlers, because catching them
+is what stops them. Report those explicitly:
+
+```ts
+try {
+	render()
+} catch (error) {
+	MapleBrowser.captureException(error, { name: "browser.render_error" })
+}
+```
+
+Opt out of the global handlers with `tracing: { captureErrors: false }` — worth
+doing only when another tracker already owns them, or the same crash is recorded
+twice.
+
+A cross-origin script reports to the browser as a bare `"Script error."` with no
+stack and no filename. Those are dropped rather than recorded: they all
+fingerprint to one contentless issue that buries the real ones. Add
+`crossorigin` to the script tag to get the real error instead.
+
+## Bundle size
+
+Bundled, minified and gzipped, as your bundler would ship it:
+
+|                  | gzipped | what it is                                                |
+| ---------------- | ------- | --------------------------------------------------------- |
+| **eager**        | ~36 kB  | every page load, before any sampling decision             |
+| ↳ our code alone | ~13 kB  | the marginal cost if your app already ships OpenTelemetry |
+| **lazy**         | ~61 kB  | rrweb — downloaded only by sessions sampled into replay   |
+
+The eager figure is ~90% OpenTelemetry. If your app already uses the OTel web
+SDK, your bundler should dedupe it and you pay closer to the second row; if it
+doesn't dedupe, you will ship two copies, so pin matching versions.
+
+Run `bun run size` in this package for the current numbers. It fails past a
+budget, so a regression has to be argued for in review rather than discovered
+in production.
 
 ## Identifying users
 
@@ -71,6 +118,26 @@ a separate analytics silo. Calls before `init()` finishes are queued.
 MapleBrowser.track("checkout_completed", { plan: "pro", seats: 12 })
 ```
 
+## Regions
+
+Maple runs separate US and EU instances, and an ingest key only works in the
+region it was created in. Set `region: "eu"` for an organization on
+`app.eu.maple.dev`; the SDK then sends to `https://ingest.eu.maple.dev`. An
+explicit `endpoint` (a proxy, or self-hosted ingest) always wins over `region`.
+
+## Tracing across origins
+
+`fetch` spans carry the W3C `traceparent` header to same-origin requests only.
+When your API lives on another origin, list it so browser and backend spans
+join one trace, and allow the `traceparent` header in the API's CORS policy:
+
+```ts
+MapleBrowser.init({
+	// ...
+	tracing: { propagateTraceHeaderCorsUrls: [/^https:\/\/api\.example\.com\//] },
+})
+```
+
 ## Linking a marketing site to your app
 
 The visitor id lives in localStorage **and** a cookie scoped to your registered
@@ -85,6 +152,18 @@ stay per-origin; `VisitorId` is the join key. Override the scope with
 attribute hooks (`data-rr-block`, `.rr-block`, `.rr-ignore`) to block elements
 or subtrees from capture.
 
+URLs are redacted before they leave the page: the values of credential-shaped
+query and fragment parameters (`token`, `code`, `access_token`, `password`, …)
+become `REDACTED` in session rows, events, network events, replay meta events
+and span attributes. Add your own rewriting with `privacy.sanitizeUrl`, for
+example to collapse ids in paths:
+
+```ts
+privacy: {
+	sanitizeUrl: (url) => url.replace(/\/users\/\d+/, "/users/:id")
+}
+```
+
 `privacy.requireConsent` holds all capture until `MapleBrowser.setConsent(true)`.
 Global Privacy Control is honored by default and suppresses the persistent
 visitor id; `doNotTrack` is not, unless `privacy.respectDoNotTrack` is set.

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-//#region ../browser-session/src/identity.d.ts
+//#region ../browser-session/src/identity/identity.d.ts
 /**
  * Who the current visitor is.
  *
@@ -26,10 +26,14 @@ interface MapleIdentity {
  */
 type IdentifyInput = string | null | undefined | MapleIdentity;
 //#endregion
-//#region ../browser-session/src/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 src/config.d.ts
 /** Public configuration for `MapleBrowser.init`. */
 interface MapleBrowserConfig {
@@ -37,7 +41,13 @@ interface MapleBrowserConfig {
   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
@@ -67,6 +77,19 @@ interface MapleBrowserConfig {
      * sink, and disabling this avoids redundant duplicate network spans.
      */
     readonly instrumentFetch?: 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. */
@@ -107,9 +130,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. */
@@ -119,6 +158,34 @@ interface MapleBrowserHandle {
 }
 //#endregion
 //#region src/index.d.ts
+/** The `MapleBrowser` namespace object. */
+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;
+}
 /**
  * Maple browser SDK. One call wires up OpenTelemetry tracing and rrweb session
  * replay, both tagged with a shared session id.
@@ -130,27 +197,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;
-};
+declare const MapleBrowser: MapleBrowserApi;
 //#endregion
-export { type IdentifyInput, MapleBrowser, type MapleBrowserConfig, type MapleBrowserHandle, type MapleIdentity, type TrackProps, type TraitValue };
+export { type CaptureExceptionOptions, type IdentifyInput, MapleBrowser, MapleBrowserApi, type MapleBrowserConfig, type MapleBrowserHandle, type MapleIdentity, type MapleRegion, type TrackProps, type TraitValue };