@nexly/web 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nexly
+
+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

@@ -0,0 +1,35 @@
+# @nexly/web
+
+Browser ingest SDK for Nexly: `sendBeacon` transport, DOM metadata, engagement listeners. Implements the abstract [`NexlyBase`](https://www.npmjs.com/package/@nexly/core) from `@nexly/core` for the browser runtime.
+
+## Install
+
+```bash
+npm install @nexly/web
+```
+
+## Usage
+
+```ts
+import { Nexly } from '@nexly/web'
+
+const client = Nexly.init({
+  appId: 'your-app-id',
+  key: 'your-ingest-key',
+})
+
+client.pageview()
+client.event({ name: 'cta_clicked', type: 'custom', data: { placement: 'hero' } })
+
+const stopEngagement = client.startEngagement()
+// stopEngagement() on SPA unmount / route change if needed
+```
+
+## What you get
+
+- `Nexly` — browser client (auto session + visitor IDs via `localStorage`/`sessionStorage`).
+- `collectSessionMeta()`, `collectEventMeta()`, `collectBrowserMeta()` — reusable metadata collectors.
+- `startEngagementTracking(creds)` — standalone engagement attach (scroll / click / focus / visibility / keepalive).
+- `sendBeaconCollect(input)` — raw `sendBeacon` helper.
+
+For React bindings use [`@nexly/react-web`](https://www.npmjs.com/package/@nexly/react-web); for Next.js App Router use [`@nexly/next`](https://www.npmjs.com/package/@nexly/next); for React Native use [`@nexly/react-native`](https://www.npmjs.com/package/@nexly/react-native).

package/dist/beacon.d.ts

@@ -0,0 +1,13 @@
+import { type CollectCredentials, type TrackEventInput } from '@nexly/core';
+export type SendBeaconCollectInput = TrackEventInput & {
+    collectUrl: string;
+};
+/**
+ * Serializes the payload and dispatches it via `navigator.sendBeacon`
+ * (survives page unload). Returns the beacon queue acceptance flag.
+ */
+export declare function sendBeaconCollect(input: SendBeaconCollectInput): boolean;
+/** Internal helper: send a pre-built payload via sendBeacon. */
+export declare function sendPayloadBeacon(url: string, payload: Record<string, unknown>): boolean;
+export type { CollectCredentials };
+//# sourceMappingURL=beacon.d.ts.map

package/dist/beacon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"beacon.d.ts","sourceRoot":"","sources":["../src/beacon.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAA;AAEhG,MAAM,MAAM,sBAAsB,GAAG,eAAe,GAAG;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,CAAA;AAE7E;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAKxE;AAED,gEAAgE;AAChE,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAIxF;AAED,YAAY,EAAE,kBAAkB,EAAE,CAAA"}

package/dist/beacon.js

@@ -0,0 +1,18 @@
+import { buildCollectPayload } from '@nexly/core';
+/**
+ * Serializes the payload and dispatches it via `navigator.sendBeacon`
+ * (survives page unload). Returns the beacon queue acceptance flag.
+ */
+export function sendBeaconCollect(input) {
+    const url = (input.collectUrl ?? '').trim();
+    if (!url)
+        return false;
+    const payload = buildCollectPayload(input);
+    return sendPayloadBeacon(url, payload);
+}
+/** Internal helper: send a pre-built payload via sendBeacon. */
+export function sendPayloadBeacon(url, payload) {
+    const body = JSON.stringify(payload);
+    const blob = new Blob([body], { type: 'text/plain' });
+    return navigator.sendBeacon(url, blob);
+}

package/dist/browser-meta.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Browser metadata collection, split into session-stable and per-event fields.
+ *
+ * Does not include geo (country/region/city) — that requires server-side IP lookup.
+ */
+/** Session-stable metadata: user agent, screen, language, timezone, etc. */
+export declare function collectSessionMeta(): Record<string, unknown>;
+/** Per-event volatile metadata: visitor/session IDs, current URL/pathname. */
+export declare function collectEventMeta(): Record<string, unknown>;
+/** Legacy: full browser metadata (session + event merged). */
+export declare function collectBrowserMeta(): Record<string, unknown>;
+//# sourceMappingURL=browser-meta.d.ts.map

package/dist/browser-meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-meta.d.ts","sourceRoot":"","sources":["../src/browser-meta.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAkBH,4EAA4E;AAC5E,wBAAgB,kBAAkB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAmE5D;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAW1D;AAED,8DAA8D;AAC9D,wBAAgB,kBAAkB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE5D"}

package/dist/browser-meta.js

@@ -0,0 +1,98 @@
+/**
+ * Browser metadata collection, split into session-stable and per-event fields.
+ *
+ * Does not include geo (country/region/city) — that requires server-side IP lookup.
+ */
+import { getSessionId, getVisitorId } from './session.js';
+function safe(fn) {
+    try {
+        return fn();
+    }
+    catch {
+        return undefined;
+    }
+}
+function filterEmpty(obj) {
+    return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined && v !== '' && !(Array.isArray(v) && v.length === 0)));
+}
+/** Session-stable metadata: user agent, screen, language, timezone, etc. */
+export function collectSessionMeta() {
+    if (typeof window === 'undefined' || typeof navigator === 'undefined') {
+        return {};
+    }
+    const out = {};
+    out.language = safe(() => navigator.language);
+    const langs = safe(() => navigator.languages);
+    if (langs?.length) {
+        out.languages = [...langs];
+    }
+    out.timezone = safe(() => Intl.DateTimeFormat().resolvedOptions().timeZone);
+    out.screen_width = safe(() => window.screen.width);
+    out.screen_height = safe(() => window.screen.height);
+    out.avail_screen_width = safe(() => window.screen.availWidth);
+    out.avail_screen_height = safe(() => window.screen.availHeight);
+    out.color_depth = safe(() => window.screen.colorDepth);
+    out.viewport_width = safe(() => window.innerWidth);
+    out.viewport_height = safe(() => window.innerHeight);
+    out.device_pixel_ratio = safe(() => window.devicePixelRatio);
+    const ref = safe(() => document.referrer);
+    if (ref) {
+        out.referrer = ref;
+    }
+    out.online = safe(() => navigator.onLine);
+    out.user_agent = safe(() => navigator.userAgent);
+    out.navigator_platform = safe(() => navigator.platform);
+    out.cookie_enabled = safe(() => navigator.cookieEnabled);
+    out.hardware_concurrency = safe(() => navigator.hardwareConcurrency);
+    out.max_touch_points = safe(() => navigator.maxTouchPoints);
+    const conn = safe(() => navigator.connection);
+    if (conn) {
+        const downlink = safe(() => conn.downlink);
+        const effectiveType = safe(() => conn.effectiveType);
+        const rtt = safe(() => conn.rtt);
+        if (downlink !== undefined)
+            out.network_downlink_mbps = downlink;
+        if (effectiveType !== undefined)
+            out.network_effective_type = effectiveType;
+        if (rtt !== undefined)
+            out.network_rtt_ms = rtt;
+    }
+    const ud = safe(() => navigator.userAgentData);
+    if (ud) {
+        const mobile = safe(() => ud.mobile);
+        const platform = safe(() => ud.platform);
+        if (mobile !== undefined)
+            out.ua_mobile = mobile;
+        if (platform)
+            out.ua_platform = platform;
+        const brands = safe(() => ud.brands);
+        if (brands?.length) {
+            out.ua_brands = brands.map((b) => `${b.brand} ${b.version}`).join(', ');
+        }
+    }
+    if (typeof window.matchMedia === 'function') {
+        const dark = safe(() => window.matchMedia('(prefers-color-scheme: dark)').matches);
+        if (dark !== undefined)
+            out.prefers_color_scheme = dark ? 'dark' : 'light';
+        const reduced = safe(() => window.matchMedia('(prefers-reduced-motion: reduce)').matches);
+        if (reduced !== undefined)
+            out.prefers_reduced_motion = reduced;
+    }
+    return filterEmpty(out);
+}
+/** Per-event volatile metadata: visitor/session IDs, current URL/pathname. */
+export function collectEventMeta() {
+    if (typeof window === 'undefined' || typeof navigator === 'undefined') {
+        return {};
+    }
+    const out = {};
+    out.visitor_id = safe(() => getVisitorId());
+    out.session_id = safe(() => getSessionId());
+    out.url = safe(() => window.location.href);
+    out.pathname = safe(() => window.location.pathname);
+    return filterEmpty(out);
+}
+/** Legacy: full browser metadata (session + event merged). */
+export function collectBrowserMeta() {
+    return { ...collectSessionMeta(), ...collectEventMeta() };
+}

package/dist/events/engagement.d.ts

@@ -0,0 +1,9 @@
+import type { CollectCredentials } from '@nexly/core';
+type StopFn = () => void;
+/**
+ * Attaches engagement listeners (scroll, click, input focus, visibility, keepalive heartbeat).
+ * Returns a cleanup function that removes all listeners and timers.
+ */
+export declare function startEngagementTracking(creds: CollectCredentials): StopFn;
+export {};
+//# sourceMappingURL=engagement.d.ts.map

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

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

package/dist/events/engagement.js

@@ -0,0 +1,129 @@
+import { sendBeaconCollect } from '../beacon.js';
+import { collectEventMeta, collectSessionMeta } from '../browser-meta.js';
+const CLICK_THROTTLE_MS = 500;
+const KEEPALIVE_INTERVAL_MS = 60_000;
+const SCROLL_DEBOUNCE_MS = 300;
+const ACTIVE_TICK_MS = 1_000;
+function sendEngagement(creds, eventName, eventType, data, sessionContext) {
+    sendBeaconCollect({
+        collectUrl: creds.collectUrl,
+        credentials: { appId: creds.appId, apiToken: creds.apiToken },
+        eventName,
+        eventType,
+        context: collectEventMeta(),
+        data,
+        sessionContext,
+    });
+}
+/**
+ * Attaches engagement listeners (scroll, click, input focus, visibility, keepalive heartbeat).
+ * Returns a cleanup function that removes all listeners and timers.
+ */
+export function startEngagementTracking(creds) {
+    if (typeof window === 'undefined' || typeof document === 'undefined') {
+        return () => { };
+    }
+    const ac = new AbortController();
+    const { signal } = ac;
+    let sessionContextSent = false;
+    function getSessionContextOnce() {
+        if (sessionContextSent)
+            return undefined;
+        sessionContextSent = true;
+        return collectSessionMeta();
+    }
+    let activeSeconds = 0;
+    const activeTickId = setInterval(() => {
+        if (document.visibilityState === 'visible')
+            activeSeconds++;
+    }, ACTIVE_TICK_MS);
+    let maxScrollPercent = 0;
+    let scrollTimer = null;
+    function updateScrollPercent() {
+        const docH = document.documentElement.scrollHeight;
+        const viewH = window.innerHeight;
+        if (docH <= viewH) {
+            maxScrollPercent = 100;
+            return;
+        }
+        const pct = Math.round((window.scrollY / (docH - viewH)) * 100);
+        if (pct > maxScrollPercent)
+            maxScrollPercent = pct;
+    }
+    function onScroll() {
+        if (scrollTimer)
+            clearTimeout(scrollTimer);
+        scrollTimer = setTimeout(updateScrollPercent, SCROLL_DEBOUNCE_MS);
+    }
+    window.addEventListener('scroll', onScroll, { passive: true, signal });
+    function flushScrollDepth() {
+        updateScrollPercent();
+        if (maxScrollPercent > 0) {
+            sendEngagement(creds, 'scroll_depth', 'engagement', { max_percent: maxScrollPercent });
+        }
+    }
+    let lastClickTs = 0;
+    function onClick(e) {
+        const now = Date.now();
+        if (now - lastClickTs < CLICK_THROTTLE_MS)
+            return;
+        lastClickTs = now;
+        const el = e.target;
+        if (!el)
+            return;
+        const tag = el.tagName?.toLowerCase() ?? '';
+        const rawText = el.innerText ?? '';
+        const text = rawText.slice(0, 80).trim();
+        sendEngagement(creds, 'click', 'engagement', {
+            tag,
+            ...(text ? { text } : {}),
+        });
+    }
+    document.addEventListener('click', onClick, { signal });
+    const focusedElements = new WeakSet();
+    function onFocusIn(e) {
+        const el = e.target;
+        if (!el)
+            return;
+        const tag = el.tagName?.toLowerCase() ?? '';
+        if (tag !== 'input' && tag !== 'textarea' && tag !== 'select')
+            return;
+        if (focusedElements.has(el))
+            return;
+        focusedElements.add(el);
+        sendEngagement(creds, 'input_focus', 'engagement', {
+            tag,
+            ...(el.name ? { name: el.name } : {}),
+            ...(el.type ? { type: el.type } : {}),
+        });
+    }
+    document.addEventListener('focusin', onFocusIn, { signal });
+    function onVisibilityChange() {
+        if (document.visibilityState === 'hidden') {
+            flushScrollDepth();
+            if (activeSeconds > 0) {
+                sendEngagement(creds, 'session_ping', 'lifecycle', { active_seconds: activeSeconds });
+            }
+        }
+    }
+    document.addEventListener('visibilitychange', onVisibilityChange, { signal });
+    function onBeforeUnload() {
+        flushScrollDepth();
+        sendEngagement(creds, 'session_end', 'lifecycle', { active_seconds: activeSeconds });
+    }
+    window.addEventListener('beforeunload', onBeforeUnload, { signal });
+    function sendKeepalive() {
+        if (document.visibilityState !== 'visible')
+            return;
+        sendEngagement(creds, 'heartbeat', 'lifecycle', { active_seconds: activeSeconds }, getSessionContextOnce());
+    }
+    sendKeepalive();
+    const keepaliveId = setInterval(sendKeepalive, KEEPALIVE_INTERVAL_MS);
+    return () => {
+        ac.abort();
+        if (scrollTimer)
+            clearTimeout(scrollTimer);
+        clearInterval(activeTickId);
+        clearInterval(keepaliveId);
+    };
+}

package/dist/events/index.d.ts

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

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

@@ -0,0 +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"}

package/dist/events/index.js

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

package/dist/events/pageview.d.ts

@@ -0,0 +1,8 @@
+import type { CollectCredentials } from '@nexly/core';
+/** Current document path, or `/` outside a browser. */
+export declare function getDefaultPathname(): string;
+/**
+ * Page view: sends slim per-event context plus session context (upserted server-side).
+ */
+export declare function sendPageViewBeacon(creds: CollectCredentials, path?: string): boolean;
+//# sourceMappingURL=pageview.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pageview.d.ts","sourceRoot":"","sources":["../../src/events/pageview.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAIrD,uDAAuD;AACvD,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,kBAAkB,EAAE,IAAI,GAAE,MAA6B,GAAG,OAAO,CAU1G"}

package/dist/events/pageview.js

@@ -0,0 +1,20 @@
+import { sendBeaconCollect } from '../beacon.js';
+import { collectEventMeta, collectSessionMeta } from '../browser-meta.js';
+/** Current document path, or `/` outside a browser. */
+export function getDefaultPathname() {
+    return typeof window !== 'undefined' ? window.location.pathname : '/';
+}
+/**
+ * Page view: sends slim per-event context plus session context (upserted server-side).
+ */
+export function sendPageViewBeacon(creds, path = getDefaultPathname()) {
+    return sendBeaconCollect({
+        collectUrl: creds.collectUrl,
+        credentials: { appId: creds.appId, apiToken: creds.apiToken },
+        eventName: 'pageview',
+        eventType: 'pageview',
+        context: { ...collectEventMeta(), path },
+        data: {},
+        sessionContext: collectSessionMeta(),
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Browser Nexly SDK (public API).
+ */
+export { Nexly } from './nexly.js';
+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 type { CollectCredentials, IngestCredentials, TrackEventInput } from '@nexly/core';
+export { buildCollectPayload } from '@nexly/core';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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"}

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * Browser Nexly SDK (public API).
+ */
+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 { buildCollectPayload } from '@nexly/core';

package/dist/nexly.d.ts

@@ -0,0 +1,18 @@
+import { NexlyBase, type NexlyInit } from '@nexly/core';
+/**
+ * Browser-specific Nexly client. Implements transport via `navigator.sendBeacon`
+ * and metadata via DOM/Navigator APIs.
+ */
+export declare class Nexly extends NexlyBase {
+    /** Creates (or replaces) the browser singleton. */
+    static init(options: NexlyInit): Nexly;
+    /** Returns the browser singleton, or `null` if not yet initialized. */
+    static getInstance(): Nexly | null;
+    constructor(init: NexlyInit);
+    protected transport(payload: Record<string, unknown>): boolean;
+    protected collectEventContext(): Record<string, unknown>;
+    protected collectSessionContext(): Record<string, unknown>;
+    getDefaultPath(): string;
+    startEngagement(): () => void;
+}
+//# sourceMappingURL=nexly.d.ts.map

package/dist/nexly.d.ts.map

@@ -0,0 +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;AAMvD;;;GAGG;AACH,qBAAa,KAAM,SAAQ,SAAS;IAClC,mDAAmD;IACnD,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;CAQvC"}

package/dist/nexly.js

@@ -0,0 +1,47 @@
+import { NexlyBase } from '@nexly/core';
+import { sendPayloadBeacon } from './beacon.js';
+import { collectEventMeta, collectSessionMeta } from './browser-meta.js';
+import { startEngagementTracking } from './events/engagement.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 {
+    /** Creates (or replaces) the browser singleton. */
+    static init(options) {
+        const instance = new Nexly(options);
+        Nexly.setInstance(instance);
+        return instance;
+    }
+    /** Returns the browser singleton, or `null` if not yet initialized. */
+    static getInstance() {
+        return NexlyBase.getInstance() ?? null;
+    }
+    constructor(init) {
+        super(init);
+    }
+    transport(payload) {
+        if (!this.collectUrl)
+            return false;
+        return sendPayloadBeacon(this.collectUrl, payload);
+    }
+    collectEventContext() {
+        return collectEventMeta();
+    }
+    collectSessionContext() {
+        return collectSessionMeta();
+    }
+    getDefaultPath() {
+        return getDefaultPathname();
+    }
+    startEngagement() {
+        if (this.disabled)
+            return () => { };
+        return startEngagementTracking({
+            collectUrl: this.collectUrl,
+            appId: this.appId,
+            apiToken: this.key,
+        });
+    }
+}

package/dist/session.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Persistent anonymous visitor ID (localStorage). One per browser + origin.
+ */
+export declare function getVisitorId(): string;
+/**
+ * Session ID with 30-minute inactivity timeout.
+ */
+export declare function getSessionId(): string;
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +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"}

package/dist/session.js

@@ -0,0 +1,50 @@
+const VISITOR_KEY = 'trk_visitor_id';
+const SESSION_KEY = 'trk_session_id';
+const SESSION_TS_KEY = 'trk_session_ts';
+const SESSION_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+function generateId() {
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+        return crypto.randomUUID();
+    }
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        return (c === 'x' ? r : (r & 0x3) | 0x8).toString(16);
+    });
+}
+function nowMs() {
+    return Date.now();
+}
+/**
+ * Persistent anonymous visitor ID (localStorage). One per browser + origin.
+ */
+export function getVisitorId() {
+    if (typeof localStorage === 'undefined') {
+        return generateId();
+    }
+    let id = localStorage.getItem(VISITOR_KEY);
+    if (!id) {
+        id = generateId();
+        localStorage.setItem(VISITOR_KEY, id);
+    }
+    return id;
+}
+/**
+ * Session ID with 30-minute inactivity timeout.
+ */
+export function getSessionId() {
+    if (typeof sessionStorage === 'undefined') {
+        return generateId();
+    }
+    const existing = sessionStorage.getItem(SESSION_KEY);
+    const tsRaw = localStorage.getItem(SESSION_TS_KEY);
+    const lastTs = tsRaw ? Number(tsRaw) : 0;
+    const now = nowMs();
+    if (existing && lastTs && now - lastTs < SESSION_TIMEOUT_MS) {
+        localStorage.setItem(SESSION_TS_KEY, String(now));
+        return existing;
+    }
+    const id = generateId();
+    sessionStorage.setItem(SESSION_KEY, id);
+    localStorage.setItem(SESSION_TS_KEY, String(now));
+    return id;
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@nexly/web",
+  "version": "0.9.0",
+  "description": "Nexly browser ingest SDK: sendBeacon transport, DOM metadata, engagement listeners on top of @nexly/core",
+  "license": "MIT",
+  "keywords": [
+    "nexly",
+    "analytics",
+    "tracking",
+    "sendBeacon",
+    "browser",
+    "ingest"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@nexly/core": "0.9.0"
+  },
+  "devDependencies": {
+    "typescript": "~6.0.2"
+  }
+}