@maple-dev/browser 0.3.0 → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maple Tech Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -31,7 +31,9 @@ That single call:
   ingest (`POST /v1/traces`);
 - records the session with rrweb, chunking events (~5s / 100KB windows),
   gzipping them with the native `CompressionStream`, and uploading to
-  `POST /v1/sessionReplays/blob`;
+  `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;
 - writes session metadata at start (`active`) and on page hide (`ended`),
   including the trace ids observed during the session.
 
@@ -44,16 +46,49 @@ metadata rows and stamped as `user.id` on future browser-created spans.
 ```ts
 MapleBrowser.identify(user.id)
 
+// or the full identity — email, name, and the company/team to group by
+MapleBrowser.identify({
+	id: user.id,
+	email: user.email,
+	groupId: org.id,
+	groupName: org.name,
+	traits: { plan: "pro" },
+})
+
 // after sign-out
 MapleBrowser.identify(null)
 ```
 
+Each call replaces the identity rather than merging it.
+
+## Custom events
+
+`track(name, props)` records a product event as a `session_events` row with
+`Type='custom'`, so it shows up inline in the session transcript rather than in
+a separate analytics silo. Calls before `init()` finishes are queued.
+
+```ts
+MapleBrowser.track("checkout_completed", { plan: "pro", seats: 12 })
+```
+
+## Linking a marketing site to your app
+
+The visitor id lives in localStorage **and** a cookie scoped to your registered
+domain, so `example.com` and `app.example.com` resolve to the same `VisitorId`
+and an anonymous pre-signup visit links to the account it becomes. Session ids
+stay per-origin; `VisitorId` is the join key. Override the scope with
+`privacy.crossSubdomainCookie` / `privacy.cookieDomain`.
+
 ## Privacy
 
 `maskAllInputs` (default **on**) masks every `<input>` value. Use rrweb's
 attribute hooks (`data-rr-block`, `.rr-block`, `.rr-ignore`) to block elements
 or subtrees from capture.
 
+`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.
+
 ## Notes
 
 - Replay event blobs live in object storage; only small, queryable metadata is

package/dist/index.d.mts

@@ -1,3 +1,35 @@
+//#region ../browser-session/src/identity.d.ts
+/**
+ * Who the current visitor is.
+ *
+ * Held in module memory only — never written to localStorage/sessionStorage.
+ * An email at rest in browser storage is a PII surface with no upside here: the
+ * identity is re-attached to every metadata row the SDK posts, so there is
+ * nothing to persist across a reload that the host app won't re-`identify()`.
+ */
+/** Trait values a host app may pass. Coerced to strings before they leave. */
+type TraitValue = string | number | boolean | null | undefined;
+interface MapleIdentity {
+  readonly id?: string;
+  readonly email?: string;
+  readonly username?: string;
+  /** Company / team / tenant — the grouping dimension in the sessions UI. */
+  readonly groupId?: string;
+  readonly groupName?: string;
+  /** Open-ended attributes (plan, role, …). Capped; see `MAX_TRAITS`. */
+  readonly traits?: Readonly<Record<string, TraitValue>>;
+}
+/**
+ * `identify` accepts a bare user id as well as the full object — the string
+ * form is what every existing caller passes, and keeping it means this can ship
+ * without touching them.
+ */
+type IdentifyInput = string | null | undefined | MapleIdentity;
+//#endregion
+//#region ../browser-session/src/track.d.ts
+/** Properties a host app may attach to a custom event. */
+type TrackProps = Readonly<Record<string, unknown>>;
+//#endregion
 //#region src/config.d.ts
 /** Public configuration for `MapleBrowser.init`. */
 interface MapleBrowserConfig {
@@ -16,10 +48,18 @@ interface MapleBrowserConfig {
   readonly serviceVersion?: string;
   /** Deployment environment, e.g. "production". */
   readonly environment?: string;
-  /** Optional user id attached to replay sessions and future browser spans. */
+  /**
+   * Optional user id attached to replay sessions and future browser spans.
+   *
+   * @deprecated Pass `user` instead — it carries email, name, and the
+   * company/team grouping the Sessions UI can filter by.
+   */
   readonly userId?: string | null | undefined;
+  /** End-user identity attached to sessions and browser spans. */
+  readonly user?: MapleIdentity | undefined;
   readonly tracing?: {
-    /** Default true. */readonly enabled?: boolean;
+    /** Default true. */
+    readonly enabled?: boolean;
     /**
      * Auto-instrument `fetch()` to create network spans. Default true. Set
      * false when another tracer (e.g. the Effect client SDK) already
@@ -29,23 +69,52 @@ interface MapleBrowserConfig {
     readonly instrumentFetch?: boolean;
   };
   readonly replay?: {
-    /** Default true. */readonly enabled?: boolean; /** Fraction of sessions to record, 0–1. Default 1. */
+    /** Default true. */
+    readonly enabled?: boolean;
+    /** Fraction of sessions to record, 0–1. Default 1. */
     readonly sampleRate?: number;
   };
   readonly privacy?: {
-    /** Mask all `<input>` values. Default true. */readonly maskAllInputs?: boolean;
+    /** Mask all `<input>` values. Default true. */
+    readonly maskAllInputs?: boolean;
     /**
      * Mask all text in the rrweb recording and omit captured click target
      * text from session events. Default false.
      */
     readonly maskAllText?: boolean;
+    /**
+     * Store a persistent visitor id (localStorage) so unique visitors and
+     * new-vs-returning are measurable. Default true. Turning it off also
+     * purges any id already stored.
+     */
+    readonly persistVisitorId?: boolean;
+    /**
+     * Scope the visitor-id cookie to the registered domain, so a marketing site
+     * and an app on sibling subdomains (`example.com` and `app.example.com`)
+     * resolve to the same visitor and a pre-signup visit links to the account it
+     * becomes. Default true. Set false to keep the cookie host-only.
+     */
+    readonly crossSubdomainCookie?: boolean;
+    /**
+     * Explicit cookie `Domain=` (no leading dot), e.g. `"example.com"`. Defaults
+     * to the broadest domain the browser accepts, discovered by probing. `""`
+     * forces a host-only cookie.
+     */
+    readonly cookieDomain?: string;
+    /** Capture nothing until `MapleBrowser.setConsent(true)`. Default false. */
+    readonly requireConsent?: boolean;
+    /** Send `identify()`'s email to the warehouse. Default true. */
+    readonly captureUserEmail?: boolean;
+    /** Treat `navigator.doNotTrack` like Global Privacy Control. Default false. */
+    readonly respectDoNotTrack?: boolean;
   };
 }
 //#endregion
 //#region src/init.d.ts
 interface MapleBrowserHandle {
+  /** Empty until consent is granted when `requireConsent` is enabled. */
   readonly sessionId: string;
-  /** Tear down tracing + replay (flushing the final chunk). */
+  /** Tear down tracing + session capture, flushing the final buffers. */
   readonly shutdown: () => Promise<void>;
 }
 //#endregion
@@ -62,11 +131,26 @@ interface MapleBrowserHandle {
  *   ingestKey: "maple_pk_...",
  *   serviceName: "acme-web",
  * })
+ *
+ * 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 user id on the active session. Safe to call repeatedly. */
-  identify: (userId?: string | null) => void;
+  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;
 };
 //#endregion
-export { MapleBrowser, type MapleBrowserConfig, type MapleBrowserHandle };
+export { type IdentifyInput, MapleBrowser, type MapleBrowserConfig, type MapleBrowserHandle, type MapleIdentity, type TrackProps, type TraitValue };