@nexly/web 0.13.0 → 0.15.0

package/README.md

@@ -25,6 +25,18 @@ const stopEngagement = client.startEngagement()
 // stopEngagement() on SPA unmount / route change if needed
 ```
 
+`startEngagement()` is idempotent — calling it again stops the previous subscription first, so HMR or double-mounts can't produce duplicate listeners.
+
+### Opting elements out of auto-capture
+
+Auto-click and auto-focus listeners skip any element (or descendant of an element) marked with `data-nexly-ignore`. Use it on elements where you already emit your own `event(...)` to avoid semantic duplicates:
+
+```tsx
+<button data-nexly-ignore onClick={() => client.event({ name: 'signup_clicked', type: 'custom' })}>
+  Sign up
+</button>
+```
+
 ## What you get
 
 - `Nexly` — browser client (auto session + visitor IDs via `localStorage`/`sessionStorage`).
@@ -55,3 +67,7 @@ await fetch('/api/link-visitor', {
 `getVisitorId()` reads the persistent anonymous id Nexly stores in `localStorage`; `getSessionId()` reads the 30-minute tab session id from `sessionStorage`. Both are plain strings, safe to call from anywhere.
 
 See the full recipe (backend storage + emitting linked events) in the [`@nexly/node` README](https://www.npmjs.com/package/@nexly/node).
+
+## Bot detection
+
+Bots and AI crawlers are classified server-side from the HTTP `User-Agent` header at ingest — do **not** try to compute or send an `is_bot` flag from your page code. Every event is stored (bots are not filtered out); the dashboard surfaces them in the dedicated "AI & Crawler activity" section and excludes them from standard visitor metrics.

package/dist/events/engagement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engagement.d.ts","sourceRoot":"","sources":["../../src/events/engagement.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AA4BrD,KAAK,MAAM,GAAG,MAAM,IAAI,CAAA;AAExB;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,kBAAkB,GAAG,MAAM,CA8GzE"}
+{"version":3,"file":"engagement.d.ts","sourceRoot":"","sources":["../../src/events/engagement.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AA4BrD,KAAK,MAAM,GAAG,MAAM,IAAI,CAAA;AAExB;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,kBAAkB,GAAG,MAAM,CAgHzE"}

package/dist/events/engagement.js

@@ -68,10 +68,12 @@ export function startEngagementTracking(creds) {
         const now = Date.now();
         if (now - lastClickTs < CLICK_THROTTLE_MS)
             return;
-        lastClickTs = now;
         const el = e.target;
         if (!el)
             return;
+        if (el.closest('[data-nexly-ignore]'))
+            return;
+        lastClickTs = now;
         const tag = el.tagName?.toLowerCase() ?? '';
         const rawText = el.innerText ?? '';
         const text = rawText.slice(0, 80).trim();
@@ -86,6 +88,8 @@ export function startEngagementTracking(creds) {
         const el = e.target;
         if (!el)
             return;
+        if (el.closest('[data-nexly-ignore]'))
+            return;
         const tag = el.tagName?.toLowerCase() ?? '';
         if (tag !== 'input' && tag !== 'textarea' && tag !== 'select')
             return;

package/dist/events/index.d.ts

@@ -1,3 +1,4 @@
 export { startEngagementTracking } from './engagement.js';
+export { startOutboundLinkTracking } from './outbound-links.js';
 export { getDefaultPathname, sendPageViewBeacon } from './pageview.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/events/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/events/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAA;AACzD,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/events/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAA;AACzD,OAAO,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAA;AAC/D,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA"}

package/dist/events/index.js

@@ -1,2 +1,3 @@
 export { startEngagementTracking } from './engagement.js';
+export { startOutboundLinkTracking } from './outbound-links.js';
 export { getDefaultPathname, sendPageViewBeacon } from './pageview.js';

package/dist/events/outbound-links.d.ts

@@ -0,0 +1,17 @@
+import type { CollectCredentials } from '@nexly/core';
+type StopFn = () => void;
+/**
+ * Attaches a delegated listener that auto-tracks four navigation cases on
+ * `<a>` elements:
+ * - external `http(s)` links — `outbound_link_clicked`
+ * - file downloads (by `download` attr or known extension) — `file_downloaded`
+ * - `mailto:` links — `mailto_clicked`
+ * - `tel:` links — `tel_clicked`
+ *
+ * All events use `type: 'navigation'`. Listens to both `click` and `auxclick`
+ * (middle-click). Skips elements (or their ancestors) marked with
+ * `[data-nexly-ignore]`. Returns a cleanup function.
+ */
+export declare function startOutboundLinkTracking(creds: CollectCredentials): StopFn;
+export {};
+//# sourceMappingURL=outbound-links.d.ts.map

package/dist/events/outbound-links.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbound-links.d.ts","sourceRoot":"","sources":["../../src/events/outbound-links.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAkKrD,KAAK,MAAM,GAAG,MAAM,IAAI,CAAA;AAExB;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,kBAAkB,GAAG,MAAM,CA0C3E"}

package/dist/events/outbound-links.js

@@ -0,0 +1,188 @@
+import { sendBeaconCollect } from '../beacon.js';
+import { collectEventMeta } from '../browser-meta.js';
+/**
+ * File extensions treated as downloadable assets when no explicit `download`
+ * attribute is present on the link. Mirrors the defaults used by Plausible's
+ * `fileDownloads` extension, with a few common additions.
+ */
+const DEFAULT_DOWNLOAD_EXTENSIONS = new Set([
+    '7z',
+    'avi',
+    'csv',
+    'dmg',
+    'doc',
+    'docx',
+    'exe',
+    'gz',
+    'key',
+    'mkv',
+    'mp3',
+    'mp4',
+    'mov',
+    'msi',
+    'numbers',
+    'odp',
+    'ods',
+    'odt',
+    'pages',
+    'pdf',
+    'pkg',
+    'ppt',
+    'pptx',
+    'rar',
+    'rtf',
+    'tar',
+    'tgz',
+    'txt',
+    'wav',
+    'webm',
+    'wma',
+    'xls',
+    'xlsx',
+    'xz',
+    'zip',
+]);
+const LINK_TEXT_MAX = 80;
+const CLICK_THROTTLE_MS = 300;
+function sendOutbound(creds, eventName, data) {
+    sendBeaconCollect({
+        collectUrl: creds.collectUrl,
+        credentials: { appId: creds.appId, apiToken: creds.apiToken },
+        client: creds.client,
+        eventName,
+        eventType: 'navigation',
+        context: collectEventMeta(),
+        data,
+    });
+}
+function getLinkText(link) {
+    const raw = link.innerText ?? link.textContent ?? '';
+    const trimmed = raw.replace(/\s+/g, ' ').trim().slice(0, LINK_TEXT_MAX);
+    return trimmed || undefined;
+}
+function getFileExtension(pathname) {
+    const lastSlash = pathname.lastIndexOf('/');
+    const fileName = lastSlash >= 0 ? pathname.slice(lastSlash + 1) : pathname;
+    const dot = fileName.lastIndexOf('.');
+    if (dot <= 0 || dot === fileName.length - 1)
+        return undefined;
+    return fileName.slice(dot + 1).toLowerCase();
+}
+function categorizeLink(link, hrefAttr, currentHost) {
+    let url;
+    try {
+        url = new URL(hrefAttr, window.location.href);
+    }
+    catch {
+        return null;
+    }
+    const linkText = getLinkText(link);
+    if (url.protocol === 'mailto:') {
+        const address = decodeURIComponent(url.pathname || hrefAttr.replace(/^mailto:/i, ''));
+        return {
+            eventName: 'mailto_clicked',
+            data: {
+                url: hrefAttr,
+                ...(address ? { address } : {}),
+                ...(linkText ? { link_text: linkText } : {}),
+            },
+        };
+    }
+    if (url.protocol === 'tel:') {
+        const number = decodeURIComponent(url.pathname || hrefAttr.replace(/^tel:/i, ''));
+        return {
+            eventName: 'tel_clicked',
+            data: {
+                url: hrefAttr,
+                ...(number ? { number } : {}),
+                ...(linkText ? { link_text: linkText } : {}),
+            },
+        };
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        return null;
+    }
+    const isExternal = url.host !== currentHost;
+    const hasDownloadAttr = link.hasAttribute('download');
+    const ext = getFileExtension(url.pathname);
+    const isDownload = hasDownloadAttr || (ext !== undefined && DEFAULT_DOWNLOAD_EXTENSIONS.has(ext));
+    if (isDownload) {
+        const fileName = url.pathname.split('/').filter(Boolean).pop();
+        return {
+            eventName: 'file_downloaded',
+            data: {
+                url: url.href,
+                host: url.host,
+                ...(fileName ? { file_name: fileName } : {}),
+                ...(ext ? { file_extension: ext } : {}),
+                external: isExternal,
+                ...(linkText ? { link_text: linkText } : {}),
+            },
+        };
+    }
+    if (isExternal) {
+        return {
+            eventName: 'outbound_link_clicked',
+            data: {
+                url: url.href,
+                host: url.host,
+                ...(linkText ? { link_text: linkText } : {}),
+                ...(link.target ? { target: link.target } : {}),
+            },
+        };
+    }
+    return null;
+}
+/**
+ * Attaches a delegated listener that auto-tracks four navigation cases on
+ * `<a>` elements:
+ * - external `http(s)` links — `outbound_link_clicked`
+ * - file downloads (by `download` attr or known extension) — `file_downloaded`
+ * - `mailto:` links — `mailto_clicked`
+ * - `tel:` links — `tel_clicked`
+ *
+ * All events use `type: 'navigation'`. Listens to both `click` and `auxclick`
+ * (middle-click). Skips elements (or their ancestors) marked with
+ * `[data-nexly-ignore]`. Returns a cleanup function.
+ */
+export function startOutboundLinkTracking(creds) {
+    if (typeof window === 'undefined' || typeof document === 'undefined') {
+        return () => { };
+    }
+    const ac = new AbortController();
+    const { signal } = ac;
+    let lastDispatch = { href: '', ts: 0 };
+    function handle(e) {
+        if (e.defaultPrevented)
+            return;
+        if (e.type === 'click' && e.button !== 0 && e.button !== 1)
+            return;
+        if (e.type === 'auxclick' && e.button !== 1)
+            return;
+        const target = e.target;
+        if (!target)
+            return;
+        const link = target.closest('a');
+        if (!link)
+            return;
+        if (link.closest('[data-nexly-ignore]'))
+            return;
+        const hrefAttr = link.getAttribute('href');
+        if (!hrefAttr)
+            return;
+        const category = categorizeLink(link, hrefAttr, window.location.host);
+        if (!category)
+            return;
+        const now = Date.now();
+        if (lastDispatch.href === hrefAttr && now - lastDispatch.ts < CLICK_THROTTLE_MS) {
+            return;
+        }
+        lastDispatch = { href: hrefAttr, ts: now };
+        sendOutbound(creds, category.eventName, category.data);
+    }
+    document.addEventListener('click', handle, { signal, capture: true });
+    document.addEventListener('auxclick', handle, { signal, capture: true });
+    return () => {
+        ac.abort();
+    };
+}

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export type { NexlyEventInput, NexlyEventType, NexlyInit } from '@nexly/core';
 export { collectBrowserMeta, collectSessionMeta, collectEventMeta } from './browser-meta.js';
 export { getSessionId, getVisitorId } from './session.js';
 export { sendBeaconCollect, type SendBeaconCollectInput } from './beacon.js';
-export { getDefaultPathname, sendPageViewBeacon, startEngagementTracking } from './events/index.js';
+export { getDefaultPathname, sendPageViewBeacon, startEngagementTracking, startOutboundLinkTracking, } from './events/index.js';
 export type { CollectCredentials, IngestCredentials, TrackEventInput } from '@nexly/core';
 export { buildCollectPayload } from '@nexly/core';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAC7E,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AAC5F,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AACzD,OAAO,EAAE,iBAAiB,EAAE,KAAK,sBAAsB,EAAE,MAAM,aAAa,CAAA;AAC5E,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAA;AACnG,YAAY,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AACzF,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAC7E,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AAC5F,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AACzD,OAAO,EAAE,iBAAiB,EAAE,KAAK,sBAAsB,EAAE,MAAM,aAAa,CAAA;AAC5E,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,uBAAuB,EACvB,yBAAyB,GAC1B,MAAM,mBAAmB,CAAA;AAC1B,YAAY,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AACzF,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA"}

package/dist/index.js

@@ -5,5 +5,5 @@ export { Nexly } from './nexly.js';
 export { collectBrowserMeta, collectSessionMeta, collectEventMeta } from './browser-meta.js';
 export { getSessionId, getVisitorId } from './session.js';
 export { sendBeaconCollect } from './beacon.js';
-export { getDefaultPathname, sendPageViewBeacon, startEngagementTracking } from './events/index.js';
+export { getDefaultPathname, sendPageViewBeacon, startEngagementTracking, startOutboundLinkTracking, } from './events/index.js';
 export { buildCollectPayload } from '@nexly/core';

package/dist/nexly.d.ts

@@ -4,6 +4,8 @@ import { NexlyBase, type NexlyInit } from '@nexly/core';
  * and metadata via DOM/Navigator APIs.
  */
 export declare class Nexly extends NexlyBase {
+    private engagementStop;
+    private outboundLinksStop;
     /** Creates (or replaces) the browser singleton. Default `client` is `NexlyClient.Web`. */
     static init(options: NexlyInit): Nexly;
     /** Returns the browser singleton, or `null` if not yet initialized. */
@@ -13,6 +15,17 @@ export declare class Nexly extends NexlyBase {
     protected collectEventContext(): Record<string, unknown>;
     protected collectSessionContext(): Record<string, unknown>;
     getDefaultPath(): string;
+    /**
+     * Attaches engagement listeners. Idempotent: calling again stops the previous
+     * subscription first, so HMR / double-mounts can't produce duplicate listeners.
+     * Returns a cleanup function.
+     */
     startEngagement(): () => void;
+    /**
+     * Attaches a delegated click listener that auto-tracks outbound links,
+     * file downloads, `mailto:` and `tel:` clicks. Idempotent: re-calling stops
+     * the previous subscription first. Returns a cleanup function.
+     */
+    startOutboundLinks(): () => void;
 }
 //# sourceMappingURL=nexly.d.ts.map

package/dist/nexly.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nexly.d.ts","sourceRoot":"","sources":["../src/nexly.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAe,KAAK,SAAS,EAAE,MAAM,aAAa,CAAA;AAMpE;;;GAGG;AACH,qBAAa,KAAM,SAAQ,SAAS;IAClC,0FAA0F;IAC1F,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,GAAG,KAAK;IAMtC,uEAAuE;IACvE,MAAM,CAAC,WAAW,IAAI,KAAK,GAAG,IAAI;gBAItB,IAAI,EAAE,SAAS;cAIR,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO;cAKpD,mBAAmB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;cAI9C,qBAAqB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAI1D,cAAc,IAAI,MAAM;IAIxB,eAAe,IAAI,MAAM,IAAI;CASvC"}
+{"version":3,"file":"nexly.d.ts","sourceRoot":"","sources":["../src/nexly.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAe,KAAK,SAAS,EAAE,MAAM,aAAa,CAAA;AAOpE;;;GAGG;AACH,qBAAa,KAAM,SAAQ,SAAS;IAClC,OAAO,CAAC,cAAc,CAA4B;IAClD,OAAO,CAAC,iBAAiB,CAA4B;IAErD,0FAA0F;IAC1F,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,GAAG,KAAK;IAMtC,uEAAuE;IACvE,MAAM,CAAC,WAAW,IAAI,KAAK,GAAG,IAAI;gBAItB,IAAI,EAAE,SAAS;cAIR,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO;cAKpD,mBAAmB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;cAI9C,qBAAqB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAI1D,cAAc,IAAI,MAAM;IAIjC;;;;OAIG;IACH,eAAe,IAAI,MAAM,IAAI;IAgB7B;;;;OAIG;IACH,kBAAkB,IAAI,MAAM,IAAI;CAejC"}

package/dist/nexly.js

@@ -2,12 +2,15 @@ import { NexlyBase, NexlyClient } from '@nexly/core';
 import { sendPayloadBeacon } from './beacon.js';
 import { collectEventMeta, collectSessionMeta } from './browser-meta.js';
 import { startEngagementTracking } from './events/engagement.js';
+import { startOutboundLinkTracking } from './events/outbound-links.js';
 import { getDefaultPathname } from './events/pageview.js';
 /**
  * Browser-specific Nexly client. Implements transport via `navigator.sendBeacon`
  * and metadata via DOM/Navigator APIs.
  */
 export class Nexly extends NexlyBase {
+    engagementStop = null;
+    outboundLinksStop = null;
     /** Creates (or replaces) the browser singleton. Default `client` is `NexlyClient.Web`. */
     static init(options) {
         const instance = new Nexly({ ...options, client: options.client ?? NexlyClient.Web });
@@ -35,14 +38,48 @@ export class Nexly extends NexlyBase {
     getDefaultPath() {
         return getDefaultPathname();
     }
+    /**
+     * Attaches engagement listeners. Idempotent: calling again stops the previous
+     * subscription first, so HMR / double-mounts can't produce duplicate listeners.
+     * Returns a cleanup function.
+     */
     startEngagement() {
         if (this.disabled)
             return () => { };
-        return startEngagementTracking({
+        this.engagementStop?.();
+        const stop = startEngagementTracking({
             collectUrl: this.collectUrl,
             appId: this.appId,
             apiToken: this.key,
             client: this.client,
         });
+        this.engagementStop = stop;
+        return () => {
+            stop();
+            if (this.engagementStop === stop)
+                this.engagementStop = null;
+        };
+    }
+    /**
+     * Attaches a delegated click listener that auto-tracks outbound links,
+     * file downloads, `mailto:` and `tel:` clicks. Idempotent: re-calling stops
+     * the previous subscription first. Returns a cleanup function.
+     */
+    startOutboundLinks() {
+        if (this.disabled)
+            return () => { };
+        this.outboundLinksStop?.();
+        const stop = startOutboundLinkTracking({
+            collectUrl: this.collectUrl,
+            appId: this.appId,
+            apiToken: this.key,
+            client: this.client,
+        });
+        this.outboundLinksStop = stop;
+        return () => {
+            stop();
+            if (this.outboundLinksStop === stop)
+                this.outboundLinksStop = null;
+        };
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nexly/web",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Nexly browser ingest SDK: sendBeacon transport, DOM metadata, engagement listeners on top of @nexly/core",
   "license": "MIT",
   "keywords": [
@@ -38,7 +38,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@nexly/core": "0.13.0"
+    "@nexly/core": "0.15.0"
   },
   "devDependencies": {
     "typescript": "~6.0.2"