@nexly/core 0.3.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,32 @@
+# @nexly/core
+
+Framework-agnostic **Nexly** browser ingest SDK: `Nexly` client, `sendBeacon` helpers, browser context, optional engagement listeners.
+
+For **React**, use **`@nexly/react-web`** (`NexlyProvider` with optional `autoPageView` / `autoEngagement`, `useNexlyClient`).
+
+## Install
+
+```bash
+npm install @nexly/core
+```
+
+## Quick start
+
+```ts
+import { Nexly } from '@nexly/core'
+
+const nexly = new Nexly(options)
+
+nexly.pageview()
+nexly.event({ name: 'click', type: 'engagement', data: { id: 'x' } })
+```
+
+`options` matches the `NexlyInit` type (your host app builds this object).
+
+## API
+
+Published **`.d.ts`** declarations list exports and types (`Nexly`, `sendBeaconCollect`, `collectBrowserMeta`, `startEngagementTracking`, and related).
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/browser-meta.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Collects browser and environment metadata for the ingest `context` object (snake_case keys).
+ * Includes `visitor_id` and `session_id` from session management.
+ * Safe to call only in a browser; returns `{}` on the server or if APIs throw.
+ *
+ * Does not include geo (country/region/city) — that requires server-side IP lookup.
+ */
+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;;;;;;GAMG;AAYH,wBAAgB,kBAAkB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAmG5D"}

package/dist/browser-meta.js

@@ -0,0 +1,101 @@
+/**
+ * Collects browser and environment metadata for the ingest `context` object (snake_case keys).
+ * Includes `visitor_id` and `session_id` from session management.
+ * Safe to call only in a browser; returns `{}` on the server or if APIs throw.
+ *
+ * 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;
+    }
+}
+export function collectBrowserMeta() {
+    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);
+    const ref = safe(() => document.referrer);
+    if (ref) {
+        out.referrer = ref;
+    }
+    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);
+    out.user_agent = safe(() => navigator.userAgent);
+    out.navigator_platform = safe(() => navigator.platform);
+    out.cookie_enabled = safe(() => navigator.cookieEnabled);
+    out.online = safe(() => navigator.onLine);
+    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;
+        }
+    }
+    if (typeof document !== 'undefined' && document.documentElement) {
+        const docW = safe(() => document.documentElement.clientWidth);
+        const docH = safe(() => document.documentElement.clientHeight);
+        if (docW !== undefined) {
+            out.document_client_width = docW;
+        }
+        if (docH !== undefined) {
+            out.document_client_height = docH;
+        }
+    }
+    return Object.fromEntries(Object.entries(out).filter(([, v]) => v !== undefined && v !== '' && !(Array.isArray(v) && v.length === 0)));
+}

package/dist/collect.d.ts

@@ -0,0 +1,35 @@
+/** Auth fields for ingest (no transport URL). */
+export type IngestCredentials = {
+    appId: string;
+    apiToken: string;
+};
+/**
+ * Event envelope:
+ * - `context` — built-in traffic / device / locale (referrer, url, utm_*, os, device, …). Not owner-registered.
+ * - `data` — owner-defined custom properties (later: only keys registered for the app).
+ */
+export type TrackEventInput = {
+    credentials: IngestCredentials;
+    eventName: string;
+    eventType: string;
+    context?: Record<string, unknown>;
+    data?: Record<string, unknown>;
+};
+/** Full send: transport URL + event envelope. */
+export type SendBeaconCollectInput = TrackEventInput & {
+    collectUrl: string;
+};
+/** Flat credentials + URL for small apps and event helpers (maps to {@link TrackEventInput.credentials}). */
+export type CollectCredentials = {
+    collectUrl: string;
+} & IngestCredentials;
+/**
+ * Builds the JSON body for POST /v1/collect (snake_case wire format).
+ * Duplicates `context.path` to top-level `path` when present.
+ */
+export declare function buildCollectPayload(input: TrackEventInput): Record<string, unknown>;
+/**
+ * Packages the payload and sends it via `navigator.sendBeacon` (survives page unload).
+ */
+export declare function sendBeaconCollect(input: SendBeaconCollectInput): boolean;
+//# sourceMappingURL=collect.d.ts.map

package/dist/collect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collect.d.ts","sourceRoot":"","sources":["../src/collect.ts"],"names":[],"mappings":"AAAA,iDAAiD;AACjD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,WAAW,EAAE,iBAAiB,CAAA;IAC9B,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC/B,CAAA;AAED,iDAAiD;AACjD,MAAM,MAAM,sBAAsB,GAAG,eAAe,GAAG;IACrD,UAAU,EAAE,MAAM,CAAA;CACnB,CAAA;AAED,6GAA6G;AAC7G,MAAM,MAAM,kBAAkB,GAAG;IAC/B,UAAU,EAAE,MAAM,CAAA;CACnB,GAAG,iBAAiB,CAAA;AAMrB;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAiBnF;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CASxE"}

package/dist/collect.js

@@ -0,0 +1,38 @@
+function isPlainObject(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+/**
+ * Builds the JSON body for POST /v1/collect (snake_case wire format).
+ * Duplicates `context.path` to top-level `path` when present.
+ */
+export function buildCollectPayload(input) {
+    const context = isPlainObject(input.context) ? input.context : {};
+    const data = isPlainObject(input.data) ? input.data : {};
+    const pathFromContext = typeof context.path === 'string' ? context.path : '';
+    const path = pathFromContext;
+    const body = {
+        app_id: input.credentials.appId,
+        api_token: input.credentials.apiToken,
+        event_name: input.eventName,
+        event_type: input.eventType,
+        context,
+        data,
+    };
+    if (path) {
+        body.path = path;
+    }
+    return body;
+}
+/**
+ * Packages the payload and sends it via `navigator.sendBeacon` (survives page unload).
+ */
+export function sendBeaconCollect(input) {
+    const url = input.collectUrl.trim();
+    if (!url) {
+        return false;
+    }
+    const payload = buildCollectPayload(input);
+    const body = JSON.stringify(payload);
+    const blob = new Blob([body], { type: 'application/json' });
+    return navigator.sendBeacon(url, blob);
+}

package/dist/events/engagement.d.ts

@@ -0,0 +1,9 @@
+import { type CollectCredentials } from '../collect.js';
+type StopFn = () => void;
+/**
+ * Attaches engagement listeners (scroll, click, input focus, visibility, 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":"AACA,OAAO,EAAqB,KAAK,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAqB1E,KAAK,MAAM,GAAG,MAAM,IAAI,CAAA;AAExB;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,kBAAkB,GAAG,MAAM,CA2HzE"}

package/dist/events/engagement.js

@@ -0,0 +1,140 @@
+import { collectBrowserMeta } from '../browser-meta.js';
+import { sendBeaconCollect } from '../collect.js';
+const CLICK_THROTTLE_MS = 500;
+const HEARTBEAT_INTERVAL_MS = 30_000;
+const SCROLL_DEBOUNCE_MS = 300;
+function makeContext() {
+    return collectBrowserMeta();
+}
+function sendEngagement(creds, eventName, eventType, data) {
+    sendBeaconCollect({
+        collectUrl: creds.collectUrl,
+        credentials: { appId: creds.appId, apiToken: creds.apiToken },
+        eventName,
+        eventType,
+        context: makeContext(),
+        data,
+    });
+}
+/**
+ * Attaches engagement listeners (scroll, click, input focus, visibility, 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;
+    // ---- scroll depth ----
+    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 });
+        }
+    }
+    // ---- click ----
+    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 });
+    // ---- input focus (once per element per session) ----
+    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 });
+    // ---- visibility / visit duration ----
+    let visibleSince = document.visibilityState === 'visible' ? Date.now() : 0;
+    let accumulatedVisibleMs = 0;
+    function onVisibilityChange() {
+        if (document.visibilityState === 'hidden') {
+            if (visibleSince > 0) {
+                accumulatedVisibleMs += Date.now() - visibleSince;
+                visibleSince = 0;
+            }
+            flushScrollDepth();
+            const secs = Math.round(accumulatedVisibleMs / 1000);
+            if (secs > 0) {
+                sendEngagement(creds, 'visibility_change', 'lifecycle', { visible_seconds: secs, state: 'hidden' });
+            }
+        }
+        else {
+            visibleSince = Date.now();
+        }
+    }
+    document.addEventListener('visibilitychange', onVisibilityChange, { signal });
+    function onBeforeUnload() {
+        if (visibleSince > 0) {
+            accumulatedVisibleMs += Date.now() - visibleSince;
+            visibleSince = 0;
+        }
+        flushScrollDepth();
+        const secs = Math.round(accumulatedVisibleMs / 1000);
+        sendEngagement(creds, 'visibility_change', 'lifecycle', { visible_seconds: secs, state: 'unload' });
+    }
+    window.addEventListener('beforeunload', onBeforeUnload, { signal });
+    // ---- heartbeat ----
+    const startTime = Date.now();
+    function sendHeartbeat() {
+        if (document.visibilityState !== 'visible')
+            return;
+        const elapsed = Math.round((Date.now() - startTime) / 1000);
+        sendEngagement(creds, 'heartbeat', 'lifecycle', { elapsed_seconds: elapsed });
+    }
+    const heartbeatId = setInterval(sendHeartbeat, HEARTBEAT_INTERVAL_MS);
+    // ---- cleanup ----
+    return () => {
+        ac.abort();
+        if (scrollTimer)
+            clearTimeout(scrollTimer);
+        clearInterval(heartbeatId);
+    };
+}

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 '../collect.js';
+/** Current document path, or `/` outside a browser. */
+export declare function getDefaultPathname(): string;
+/**
+ * Page view: fills `context` with {@link collectBrowserMeta} and sets `path` (overrides pathname from the location snapshot).
+ */
+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":"AACA,OAAO,EAAqB,KAAK,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAE1E,uDAAuD;AACvD,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,kBAAkB,EAAE,IAAI,GAAE,MAA6B,GAAG,OAAO,CAY1G"}

package/dist/events/pageview.js

@@ -0,0 +1,22 @@
+import { collectBrowserMeta } from '../browser-meta.js';
+import { sendBeaconCollect } from '../collect.js';
+/** Current document path, or `/` outside a browser. */
+export function getDefaultPathname() {
+    return typeof window !== 'undefined' ? window.location.pathname : '/';
+}
+/**
+ * Page view: fills `context` with {@link collectBrowserMeta} and sets `path` (overrides pathname from the location snapshot).
+ */
+export function sendPageViewBeacon(creds, path = getDefaultPathname()) {
+    return sendBeaconCollect({
+        collectUrl: creds.collectUrl,
+        credentials: { appId: creds.appId, apiToken: creds.apiToken },
+        eventName: 'pageview',
+        eventType: 'pageview',
+        context: {
+            ...collectBrowserMeta(),
+            path,
+        },
+        data: {},
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Browser event ingest client (public API).
+ */
+export { Nexly, type NexlyEventInput, type NexlyInit } from './nexly.js';
+export { collectBrowserMeta } from './browser-meta.js';
+export { getSessionId, getVisitorId } from './session.js';
+export { buildCollectPayload, sendBeaconCollect, type CollectCredentials, type IngestCredentials, type SendBeaconCollectInput, type TrackEventInput, } from './collect.js';
+export { getDefaultPathname, sendPageViewBeacon, startEngagementTracking } from './events/index.js';
+//# 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,KAAK,eAAe,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAA;AACxE,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AACtD,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AACzD,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,eAAe,GACrB,MAAM,cAAc,CAAA;AACrB,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/index.js

@@ -0,0 +1,8 @@
+/**
+ * Browser event ingest client (public API).
+ */
+export { Nexly } from './nexly.js';
+export { collectBrowserMeta } from './browser-meta.js';
+export { getSessionId, getVisitorId } from './session.js';
+export { buildCollectPayload, sendBeaconCollect, } from './collect.js';
+export { getDefaultPathname, sendPageViewBeacon, startEngagementTracking } from './events/index.js';

package/dist/nexly.d.ts

@@ -0,0 +1,37 @@
+/** Options for {@link Nexly}. `key` is the ingest API token (sent as `api_token` on the wire). */
+export type NexlyInit = {
+    collectUrl: string;
+    appId: string;
+    key: string;
+};
+export type NexlyEventInput = {
+    name: string;
+    type: string;
+    data?: Record<string, unknown>;
+    /** Merged on top of default browser context (see {@link collectBrowserMeta}) and current `path`. */
+    context?: Record<string, unknown>;
+};
+/**
+ * High-level browser client: page views, custom events, optional engagement auto-tracking.
+ */
+export declare class Nexly {
+    readonly collectUrl: string;
+    readonly appId: string;
+    readonly key: string;
+    constructor(init: NexlyInit);
+    private get credentials();
+    private defaultContext;
+    /**
+     * Sends a page view (`event_name` / `event_type`: `pageview`) with full browser context.
+     */
+    pageview(path?: string): boolean;
+    /**
+     * Sends a custom event. Default context is browser meta + path; pass `context` to merge or override fields.
+     */
+    event(input: NexlyEventInput): boolean;
+    /**
+     * Starts scroll, click, focus, visibility, and heartbeat tracking. Returns a stop function.
+     */
+    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":"AAIA,kGAAkG;AAClG,MAAM,MAAM,SAAS,GAAG;IACtB,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;CACZ,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC9B,oGAAoG;IACpG,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAClC,CAAA;AAED;;GAEG;AACH,qBAAa,KAAK;IAChB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;gBAER,IAAI,EAAE,SAAS;IAM3B,OAAO,KAAK,WAAW,GAMtB;IAED,OAAO,CAAC,cAAc;IAOtB;;OAEG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO;IAIhC;;OAEG;IACH,KAAK,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO;IActC;;OAEG;IACH,eAAe,IAAI,MAAM,IAAI;CAG9B"}

package/dist/nexly.js

@@ -0,0 +1,57 @@
+import { collectBrowserMeta } from './browser-meta.js';
+import { sendBeaconCollect } from './collect.js';
+import { getDefaultPathname, sendPageViewBeacon, startEngagementTracking } from './events/index.js';
+/**
+ * High-level browser client: page views, custom events, optional engagement auto-tracking.
+ */
+export class Nexly {
+    collectUrl;
+    appId;
+    key;
+    constructor(init) {
+        this.collectUrl = init.collectUrl.trim();
+        this.appId = init.appId.trim();
+        this.key = init.key.trim();
+    }
+    get credentials() {
+        return {
+            collectUrl: this.collectUrl,
+            appId: this.appId,
+            apiToken: this.key,
+        };
+    }
+    defaultContext() {
+        return {
+            ...collectBrowserMeta(),
+            path: getDefaultPathname(),
+        };
+    }
+    /**
+     * Sends a page view (`event_name` / `event_type`: `pageview`) with full browser context.
+     */
+    pageview(path) {
+        return sendPageViewBeacon(this.credentials, path ?? getDefaultPathname());
+    }
+    /**
+     * Sends a custom event. Default context is browser meta + path; pass `context` to merge or override fields.
+     */
+    event(input) {
+        const context = input.context
+            ? { ...this.defaultContext(), ...input.context }
+            : this.defaultContext();
+        return sendBeaconCollect({
+            collectUrl: this.collectUrl,
+            credentials: { appId: this.appId, apiToken: this.key },
+            eventName: input.name,
+            eventType: input.type,
+            context,
+            data: input.data ?? {},
+        });
+    }
+    /**
+     * Starts scroll, click, focus, visibility, and heartbeat tracking. Returns a stop function.
+     */
+    startEngagement() {
+        return startEngagementTracking(this.credentials);
+    }
+}

package/dist/session.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Persistent anonymous visitor ID (localStorage). One per browser + origin.
+ * Generated on first call, reused after.
+ */
+export declare function getVisitorId(): string;
+/**
+ * Session ID with 30-minute inactivity timeout (sessionStorage for tab scope, localStorage for timestamp).
+ * New tab or > 30 min idle → new session.
+ */
+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;;;GAGG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAUrC;AAED;;;GAGG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAmBrC"}

package/dist/session.js

@@ -0,0 +1,52 @@
+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.
+ * Generated on first call, reused after.
+ */
+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 (sessionStorage for tab scope, localStorage for timestamp).
+ * New tab or > 30 min idle → new session.
+ */
+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,43 @@
+{
+  "name": "@nexly/core",
+  "version": "0.3.0",
+  "description": "Nexly browser ingest core (sendBeacon, Nexly client, context, engagement)",
+  "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"
+  },
+  "devDependencies": {
+    "typescript": "~6.0.2"
+  }
+}