@nexly/web 0.14.0 → 0.15.1

package/README.md

@@ -67,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/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

@@ -5,6 +5,7 @@ import { NexlyBase, type NexlyInit } from '@nexly/core';
  */
 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. */
@@ -20,5 +21,11 @@ export declare class Nexly extends NexlyBase {
      * 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,OAAO,CAAC,cAAc,CAA4B;IAElD,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;CAe9B"}
+{"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,6 +2,7 @@ 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`
@@ -9,6 +10,7 @@ import { getDefaultPathname } from './events/pageview.js';
  */
 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 });
@@ -58,4 +60,26 @@ export class Nexly extends NexlyBase {
                 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/dist/session.d.ts

@@ -4,6 +4,10 @@
 export declare function getVisitorId(): string;
 /**
  * Session ID with 30-minute inactivity timeout.
+ *
+ * Stored in `localStorage` (not `sessionStorage`) so the same session is shared
+ * across tabs and survives tab/window close. The 30-minute inactivity window is
+ * enforced via `SESSION_TS_KEY`, matching Plausible's visit definition.
  */
 export declare function getSessionId(): string;
 //# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAoBA;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAUrC;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAkBrC"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAoBA;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAUrC;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAkBrC"}

package/dist/session.js

@@ -30,12 +30,16 @@ export function getVisitorId() {
 }
 /**
  * Session ID with 30-minute inactivity timeout.
+ *
+ * Stored in `localStorage` (not `sessionStorage`) so the same session is shared
+ * across tabs and survives tab/window close. The 30-minute inactivity window is
+ * enforced via `SESSION_TS_KEY`, matching Plausible's visit definition.
  */
 export function getSessionId() {
-    if (typeof sessionStorage === 'undefined') {
+    if (typeof localStorage === 'undefined') {
         return generateId();
     }
-    const existing = sessionStorage.getItem(SESSION_KEY);
+    const existing = localStorage.getItem(SESSION_KEY);
     const tsRaw = localStorage.getItem(SESSION_TS_KEY);
     const lastTs = tsRaw ? Number(tsRaw) : 0;
     const now = nowMs();
@@ -44,7 +48,7 @@ export function getSessionId() {
         return existing;
     }
     const id = generateId();
-    sessionStorage.setItem(SESSION_KEY, id);
+    localStorage.setItem(SESSION_KEY, id);
     localStorage.setItem(SESSION_TS_KEY, String(now));
     return id;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nexly/web",
-  "version": "0.14.0",
+  "version": "0.15.1",
   "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.14.0"
+    "@nexly/core": "0.15.1"
   },
   "devDependencies": {
     "typescript": "~6.0.2"