@nexly/core 0.8.1 → 0.9.0

package/dist/collect.d.ts

@@ -1,13 +1,23 @@
+/**
+ * Platform-agnostic event envelope types and payload builder.
+ *
+ * This module is safe to import from any runtime (browser, React Native, Node).
+ * Transport (beacon / fetch / native) lives in platform-specific packages.
+ */
 /** Auth fields for ingest (no transport URL). */
 export type IngestCredentials = {
     appId: string;
     apiToken: string;
 };
+/** Flat credentials + URL for small apps and event helpers. */
+export type CollectCredentials = {
+    collectUrl: string;
+} & IngestCredentials;
 /**
  * Event envelope:
- * - `context` — per-event volatile metadata (url, pathname, viewport, etc.).
- * - `data` — owner-defined custom properties (later: only keys registered for the app).
- * - `session_context` — session-stable metadata (UA, screen, language), sent once per session.
+ * - `context` — per-event volatile metadata (path, screen, viewport, visitor_id, session_id, …).
+ * - `data` — owner-defined custom properties.
+ * - `session_context` — session-stable metadata (OS, locale, screen), sent once per session.
  */
 export type TrackEventInput = {
     credentials: IngestCredentials;
@@ -17,22 +27,10 @@ export type TrackEventInput = {
     data?: Record<string, unknown>;
     sessionContext?: 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.
+ * Duplicates `context.path` to the top-level `path` when present.
  * Includes `session_context` when provided (first event of a session).
  */
 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

@@ -1 +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;;;;;GAKG;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;IAC9B,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACzC,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;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAqBnF;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CASxE"}
+{"version":3,"file":"collect.d.ts","sourceRoot":"","sources":["../src/collect.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,iDAAiD;AACjD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,+DAA+D;AAC/D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,UAAU,EAAE,MAAM,CAAA;CACnB,GAAG,iBAAiB,CAAA;AAErB;;;;;GAKG;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;IAC9B,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACzC,CAAA;AAMD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAoBnF"}

package/dist/collect.js

@@ -1,16 +1,21 @@
+/**
+ * Platform-agnostic event envelope types and payload builder.
+ *
+ * This module is safe to import from any runtime (browser, React Native, Node).
+ * Transport (beacon / fetch / native) lives in platform-specific packages.
+ */
 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.
+ * Duplicates `context.path` to the top-level `path` when present.
  * Includes `session_context` when provided (first event of a session).
  */
 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,
@@ -19,8 +24,8 @@ export function buildCollectPayload(input) {
         context,
         data,
     };
-    if (path) {
-        body.path = path;
+    if (pathFromContext) {
+        body.path = pathFromContext;
     }
     const sc = isPlainObject(input.sessionContext) ? input.sessionContext : null;
     if (sc && Object.keys(sc).length > 0) {
@@ -28,16 +33,3 @@ export function buildCollectPayload(input) {
     }
     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/index.d.ts

@@ -1,9 +1,10 @@
 /**
- * Browser event ingest client (public API).
+ * Platform-agnostic Nexly ingest core: types, payload builder, and the {@link NexlyBase} abstract class.
+ *
+ * Platform-specific transports and metadata live in sibling packages:
+ * - `@nexly/web` — browser (sendBeacon, DOM meta, engagement listeners).
+ * - `@nexly/react-native` — React Native (fetch, AsyncStorage, AppState).
  */
-export { Nexly, type NexlyEventInput, type NexlyEventType, type NexlyInit } from './nexly.js';
-export { collectBrowserMeta, collectSessionMeta, collectEventMeta } 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';
+export { buildCollectPayload, type CollectCredentials, type IngestCredentials, type TrackEventInput, } from './collect.js';
+export { NexlyBase, DEFAULT_COLLECT_URL, type NexlyEventInput, type NexlyEventType, type NexlyInit, } from './nexly-base.js';
 //# 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,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAA;AAC7F,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AAC5F,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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,mBAAmB,EACnB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,eAAe,GACrB,MAAM,cAAc,CAAA;AACrB,OAAO,EACL,SAAS,EACT,mBAAmB,EACnB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,SAAS,GACf,MAAM,iBAAiB,CAAA"}

package/dist/index.js

@@ -1,8 +1,9 @@
 /**
- * Browser event ingest client (public API).
+ * Platform-agnostic Nexly ingest core: types, payload builder, and the {@link NexlyBase} abstract class.
+ *
+ * Platform-specific transports and metadata live in sibling packages:
+ * - `@nexly/web` — browser (sendBeacon, DOM meta, engagement listeners).
+ * - `@nexly/react-native` — React Native (fetch, AsyncStorage, AppState).
  */
-export { Nexly } from './nexly.js';
-export { collectBrowserMeta, collectSessionMeta, collectEventMeta } from './browser-meta.js';
-export { getSessionId, getVisitorId } from './session.js';
-export { buildCollectPayload, sendBeaconCollect, } from './collect.js';
-export { getDefaultPathname, sendPageViewBeacon, startEngagementTracking } from './events/index.js';
+export { buildCollectPayload, } from './collect.js';
+export { NexlyBase, DEFAULT_COLLECT_URL, } from './nexly-base.js';

package/dist/nexly-base.d.ts

@@ -0,0 +1,60 @@
+import { type IngestCredentials } from './collect.js';
+export declare const DEFAULT_COLLECT_URL = "https://gate.nexly.to/v1/collect";
+/** Options for {@link NexlyBase}. `key` is the ingest API token (sent as `api_token` on the wire). */
+export type NexlyInit = {
+    /** Override the ingest endpoint. Defaults to the Nexly production gateway. */
+    collectUrl?: string;
+    appId: string;
+    key: string;
+};
+/** Allowed event types. The backend rejects any other value. */
+export type NexlyEventType = 'pageview' | 'engagement' | 'custom';
+export type NexlyEventInput = {
+    name: string;
+    type: NexlyEventType | string;
+    data?: Record<string, unknown>;
+    /** Merged on top of default platform context (see {@link NexlyBase.collectEventContext}). */
+    context?: Record<string, unknown>;
+};
+/**
+ * Platform-agnostic base class: session state, payload assembly, disabled-state logic.
+ *
+ * Subclasses implement:
+ * - {@link transport} — how bytes reach the collector (beacon / fetch / native bridge).
+ * - {@link collectEventContext} — per-event volatile metadata (path, visitor/session IDs, viewport).
+ * - {@link collectSessionContext} — session-stable metadata (OS, locale, screen).
+ * - {@link getDefaultPath} — current path / screen name.
+ * - {@link startEngagement} — platform-specific engagement listeners. Returns a stop function.
+ */
+export declare abstract class NexlyBase {
+    private static _instance;
+    /** Shared singleton access. Each concrete class's `init()` should write here. */
+    static getInstance(): NexlyBase | null;
+    protected static setInstance(instance: NexlyBase | null): void;
+    readonly collectUrl: string;
+    readonly appId: string;
+    readonly key: string;
+    protected constructor(init: NexlyInit);
+    protected get disabled(): boolean;
+    protected get credentials(): IngestCredentials;
+    /** Platform-specific byte transport. Must be fire-and-forget (return quickly). */
+    protected abstract transport(payload: Record<string, unknown>): boolean;
+    /** Per-event volatile metadata merged into `context`. */
+    protected abstract collectEventContext(): Record<string, unknown>;
+    /** Session-stable metadata sent as `session_context`. */
+    protected abstract collectSessionContext(): Record<string, unknown>;
+    /** Current path (web) or screen name (native). */
+    abstract getDefaultPath(): string;
+    /** Start platform-specific engagement tracking. Returns a cleanup function. */
+    abstract startEngagement(): () => void;
+    /**
+     * Sends a page view (`event_name` / `event_type`: `pageview`) with full context.
+     */
+    pageview(path?: string): boolean;
+    /**
+     * Sends a custom event. Pass `context` to merge or override default fields.
+     */
+    event(input: NexlyEventInput): boolean;
+    private dispatch;
+}
+//# sourceMappingURL=nexly-base.d.ts.map

package/dist/nexly-base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nexly-base.d.ts","sourceRoot":"","sources":["../src/nexly-base.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAI1E,eAAO,MAAM,mBAAmB,qCAAqC,CAAA;AAErE,sGAAsG;AACtG,MAAM,MAAM,SAAS,GAAG;IACtB,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;CACZ,CAAA;AAED,gEAAgE;AAChE,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,YAAY,GAAG,QAAQ,CAAA;AAEjE,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,cAAc,GAAG,MAAM,CAAA;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC9B,6FAA6F;IAC7F,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAClC,CAAA;AAED;;;;;;;;;GASG;AACH,8BAAsB,SAAS;IAC7B,OAAO,CAAC,MAAM,CAAC,SAAS,CAAyB;IAEjD,iFAAiF;IACjF,MAAM,CAAC,WAAW,IAAI,SAAS,GAAG,IAAI;IAItC,SAAS,CAAC,MAAM,CAAC,WAAW,CAAC,QAAQ,EAAE,SAAS,GAAG,IAAI,GAAG,IAAI;IAI9D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IAEpB,SAAS,aAAa,IAAI,EAAE,SAAS;IAQrC,SAAS,KAAK,QAAQ,IAAI,OAAO,CAEhC;IAED,SAAS,KAAK,WAAW,IAAI,iBAAiB,CAE7C;IAED,kFAAkF;IAClF,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO;IAEvE,yDAAyD;IACzD,SAAS,CAAC,QAAQ,CAAC,mBAAmB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAEjE,yDAAyD;IACzD,SAAS,CAAC,QAAQ,CAAC,qBAAqB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAEnE,kDAAkD;IAClD,QAAQ,CAAC,cAAc,IAAI,MAAM;IAEjC,+EAA+E;IAC/E,QAAQ,CAAC,eAAe,IAAI,MAAM,IAAI;IAEtC;;OAEG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO;IAYhC;;OAEG;IACH,KAAK,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO;IAatC,OAAO,CAAC,QAAQ;CAiBjB"}

package/dist/nexly-base.js

@@ -0,0 +1,82 @@
+import { buildCollectPayload } from './collect.js';
+export const DEFAULT_COLLECT_URL = 'https://gate.nexly.to/v1/collect';
+/**
+ * Platform-agnostic base class: session state, payload assembly, disabled-state logic.
+ *
+ * Subclasses implement:
+ * - {@link transport} — how bytes reach the collector (beacon / fetch / native bridge).
+ * - {@link collectEventContext} — per-event volatile metadata (path, visitor/session IDs, viewport).
+ * - {@link collectSessionContext} — session-stable metadata (OS, locale, screen).
+ * - {@link getDefaultPath} — current path / screen name.
+ * - {@link startEngagement} — platform-specific engagement listeners. Returns a stop function.
+ */
+export class NexlyBase {
+    static _instance = null;
+    /** Shared singleton access. Each concrete class's `init()` should write here. */
+    static getInstance() {
+        return NexlyBase._instance;
+    }
+    static setInstance(instance) {
+        NexlyBase._instance = instance;
+    }
+    collectUrl;
+    appId;
+    key;
+    constructor(init) {
+        this.collectUrl = (init.collectUrl ?? DEFAULT_COLLECT_URL).trim();
+        this.appId = (init.appId ?? '').trim();
+        this.key = (init.key ?? '').trim();
+        if (!this.appId)
+            console.warn('[Nexly] Missing appId — tracking will be disabled.');
+        if (!this.key)
+            console.warn('[Nexly] Missing key — tracking will be disabled.');
+    }
+    get disabled() {
+        return !this.appId || !this.key;
+    }
+    get credentials() {
+        return { appId: this.appId, apiToken: this.key };
+    }
+    /**
+     * Sends a page view (`event_name` / `event_type`: `pageview`) with full context.
+     */
+    pageview(path) {
+        if (this.disabled)
+            return false;
+        const resolvedPath = path ?? this.getDefaultPath();
+        return this.dispatch({
+            eventName: 'pageview',
+            eventType: 'pageview',
+            context: { ...this.collectEventContext(), path: resolvedPath },
+            data: {},
+            sessionContext: this.collectSessionContext(),
+        });
+    }
+    /**
+     * Sends a custom event. Pass `context` to merge or override default fields.
+     */
+    event(input) {
+        if (this.disabled)
+            return false;
+        const defaultContext = { ...this.collectEventContext(), path: this.getDefaultPath() };
+        const context = input.context ? { ...defaultContext, ...input.context } : defaultContext;
+        return this.dispatch({
+            eventName: input.name,
+            eventType: input.type,
+            context,
+            data: input.data ?? {},
+            sessionContext: this.collectSessionContext(),
+        });
+    }
+    dispatch(args) {
+        const payload = buildCollectPayload({
+            credentials: this.credentials,
+            eventName: args.eventName,
+            eventType: args.eventType,
+            context: args.context,
+            data: args.data,
+            sessionContext: args.sessionContext,
+        });
+        return this.transport(payload);
+    }
+}

package/package.json

@@ -1,14 +1,12 @@
 {
   "name": "@nexly/core",
-  "version": "0.8.1",
-  "description": "Nexly browser ingest core (sendBeacon, Nexly client, context, engagement)",
+  "version": "0.9.0",
+  "description": "Nexly ingest core (platform-agnostic): types, payload builder, abstract NexlyBase client",
   "license": "MIT",
   "keywords": [
     "nexly",
     "analytics",
     "tracking",
-    "sendBeacon",
-    "browser",
     "ingest"
   ],
   "type": "module",

package/dist/browser-meta.d.ts

@@ -1,26 +0,0 @@
-/**
- * Browser metadata collection, split into session-stable and per-event fields.
- *
- * - `collectSessionMeta()` — stable within a session (UA, screen, language, etc.), sent once.
- * - `collectEventMeta()` — per-event volatile fields (url, pathname, referrer), sent with every event.
- * - `collectBrowserMeta()` — legacy: merges both for backward compatibility.
- *
- * Does not include geo (country/region/city) — that requires server-side IP lookup.
- */
-/**
- * Session-stable metadata: user agent, screen, language, timezone, etc.
- * Collected once per session and sent as `session_context` on the wire.
- */
-export declare function collectSessionMeta(): Record<string, unknown>;
-/**
- * Per-event volatile metadata: only fields that actually change between events.
- * Includes `visitor_id` and `session_id` for server-side extraction,
- * plus `url` and `pathname` to track SPA navigation.
- */
-export declare function collectEventMeta(): Record<string, unknown>;
-/**
- * Legacy: full browser metadata (session + event fields merged).
- * Kept for backward compatibility with `Nexly.event()` and custom events.
- */
-export declare function collectBrowserMeta(): Record<string, unknown>;
-//# sourceMappingURL=browser-meta.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"browser-meta.d.ts","sourceRoot":"","sources":["../src/browser-meta.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAkBH;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAiF5D;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAc1D;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE5D"}

package/dist/browser-meta.js

@@ -1,119 +0,0 @@
-/**
- * Browser metadata collection, split into session-stable and per-event fields.
- *
- * - `collectSessionMeta()` — stable within a session (UA, screen, language, etc.), sent once.
- * - `collectEventMeta()` — per-event volatile fields (url, pathname, referrer), sent with every event.
- * - `collectBrowserMeta()` — legacy: merges both for backward compatibility.
- *
- * 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.
- * Collected once per session and sent as `session_context` on the wire.
- */
-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: only fields that actually change between events.
- * Includes `visitor_id` and `session_id` for server-side extraction,
- * plus `url` and `pathname` to track SPA navigation.
- */
-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 fields merged).
- * Kept for backward compatibility with `Nexly.event()` and custom events.
- */
-export function collectBrowserMeta() {
-    return { ...collectSessionMeta(), ...collectEventMeta() };
-}

package/dist/events/engagement.d.ts

@@ -1,13 +0,0 @@
-import { type CollectCredentials } from '../collect.js';
-type StopFn = () => void;
-/**
- * Attaches engagement listeners (scroll, click, input focus, visibility, keepalive heartbeat).
- * Returns a cleanup function that removes all listeners and timers.
- *
- * Duration is tracked client-side: a 1s tick increments `activeSeconds` only while visible.
- * A lightweight keepalive heartbeat fires every 60s for the realtime dashboard.
- * Summary events are sent on visibility hidden and beforeunload.
- */
-export declare function startEngagementTracking(creds: CollectCredentials): StopFn;
-export {};
-//# sourceMappingURL=engagement.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"engagement.d.ts","sourceRoot":"","sources":["../../src/events/engagement.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,KAAK,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAyB1E,KAAK,MAAM,GAAG,MAAM,IAAI,CAAA;AAExB;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,kBAAkB,GAAG,MAAM,CAmIzE"}

package/dist/events/engagement.js

@@ -1,143 +0,0 @@
-import { collectEventMeta, collectSessionMeta } from '../browser-meta.js';
-import { sendBeaconCollect } from '../collect.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.
- *
- * Duration is tracked client-side: a 1s tick increments `activeSeconds` only while visible.
- * A lightweight keepalive heartbeat fires every 60s for the realtime dashboard.
- * Summary events are sent on visibility hidden and beforeunload.
- */
-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();
-    }
-    // ---- client-side active duration tracking ----
-    let activeSeconds = 0;
-    const activeTickId = setInterval(() => {
-        if (document.visibilityState === 'visible') {
-            activeSeconds++;
-        }
-    }, ACTIVE_TICK_MS);
-    // ---- 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 / session summary ----
-    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 });
-    // ---- keepalive heartbeat (60s, lightweight, for realtime dashboard) ----
-    function sendKeepalive() {
-        if (document.visibilityState !== 'visible')
-            return;
-        sendEngagement(creds, 'heartbeat', 'lifecycle', { active_seconds: activeSeconds }, getSessionContextOnce());
-    }
-    // Send first heartbeat immediately to register the session context
-    sendKeepalive();
-    const keepaliveId = setInterval(sendKeepalive, KEEPALIVE_INTERVAL_MS);
-    // ---- cleanup ----
-    return () => {
-        ac.abort();
-        if (scrollTimer)
-            clearTimeout(scrollTimer);
-        clearInterval(activeTickId);
-        clearInterval(keepaliveId);
-    };
-}

package/dist/events/index.d.ts

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

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

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

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

package/dist/events/pageview.d.ts

@@ -1,9 +0,0 @@
-import { type CollectCredentials } from '../collect.js';
-/** Current document path, or `/` outside a browser. */
-export declare function getDefaultPathname(): string;
-/**
- * Page view: sends slim `context` (per-event meta) plus `session_context` (session-stable meta).
- * The backend upserts the session row from `session_context` on every pageview.
- */
-export declare function sendPageViewBeacon(creds: CollectCredentials, path?: string): boolean;
-//# sourceMappingURL=pageview.d.ts.map

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

@@ -1 +0,0 @@
-{"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;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,kBAAkB,EAAE,IAAI,GAAE,MAA6B,GAAG,OAAO,CAa1G"}

package/dist/events/pageview.js

@@ -1,24 +0,0 @@
-import { collectEventMeta, collectSessionMeta } 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: sends slim `context` (per-event meta) plus `session_context` (session-stable meta).
- * The backend upserts the session row from `session_context` on every pageview.
- */
-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/nexly.d.ts

@@ -1,50 +0,0 @@
-/** Options for {@link Nexly}. `key` is the ingest API token (sent as `api_token` on the wire). */
-export type NexlyInit = {
-    /** Override the ingest endpoint. Defaults to the Nexly production gateway. */
-    collectUrl?: string;
-    appId: string;
-    key: string;
-};
-/** Allowed event types. The backend rejects any other value. */
-export type NexlyEventType = 'pageview' | 'engagement' | 'custom';
-export type NexlyEventInput = {
-    name: string;
-    type: NexlyEventType;
-    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 {
-    private static instance;
-    /**
-     * Creates (or replaces) the global singleton and returns it.
-     * The provider calls this; plain functions use {@link getInstance}.
-     */
-    static init(options: NexlyInit): Nexly;
-    /** Returns the singleton created by {@link init}, or `null` if not yet initialized. */
-    static getInstance(): Nexly | null;
-    readonly collectUrl: string;
-    readonly appId: string;
-    readonly key: string;
-    constructor(init: NexlyInit);
-    private get disabled();
-    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 per-event meta + path; pass `context` to merge or override fields.
-     * Includes session_context so the backend can upsert session metadata.
-     */
-    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

@@ -1 +0,0 @@
-{"version":3,"file":"nexly.d.ts","sourceRoot":"","sources":["../src/nexly.ts"],"names":[],"mappings":"AAMA,kGAAkG;AAClG,MAAM,MAAM,SAAS,GAAG;IACtB,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;CACZ,CAAA;AAED,gEAAgE;AAChE,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,YAAY,GAAG,QAAQ,CAAA;AAEjE,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,cAAc,CAAA;IACpB,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,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAqB;IAE5C;;;OAGG;IACH,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,GAAG,KAAK;IAKtC,uFAAuF;IACvF,MAAM,CAAC,WAAW,IAAI,KAAK,GAAG,IAAI;IAIlC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;gBAER,IAAI,EAAE,SAAS;IAQ3B,OAAO,KAAK,QAAQ,GAEnB;IAED,OAAO,KAAK,WAAW,GAMtB;IAED,OAAO,CAAC,cAAc;IAOtB;;OAEG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO;IAKhC;;;OAGG;IACH,KAAK,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO;IAgBtC;;OAEG;IACH,eAAe,IAAI,MAAM,IAAI;CAI9B"}

package/dist/nexly.js

@@ -1,86 +0,0 @@
-import { collectEventMeta, collectSessionMeta } from './browser-meta.js';
-import { sendBeaconCollect } from './collect.js';
-import { getDefaultPathname, sendPageViewBeacon, startEngagementTracking } from './events/index.js';
-const DEFAULT_COLLECT_URL = 'https://gate.nexly.to/v1/collect';
-/**
- * High-level browser client: page views, custom events, optional engagement auto-tracking.
- */
-export class Nexly {
-    static instance = null;
-    /**
-     * Creates (or replaces) the global singleton and returns it.
-     * The provider calls this; plain functions use {@link getInstance}.
-     */
-    static init(options) {
-        Nexly.instance = new Nexly(options);
-        return Nexly.instance;
-    }
-    /** Returns the singleton created by {@link init}, or `null` if not yet initialized. */
-    static getInstance() {
-        return Nexly.instance;
-    }
-    collectUrl;
-    appId;
-    key;
-    constructor(init) {
-        this.collectUrl = (init.collectUrl ?? DEFAULT_COLLECT_URL).trim();
-        this.appId = (init.appId ?? '').trim();
-        this.key = (init.key ?? '').trim();
-        if (!this.appId)
-            console.warn('[Nexly] Missing appId — tracking will be disabled.');
-        if (!this.key)
-            console.warn('[Nexly] Missing key — tracking will be disabled.');
-    }
-    get disabled() {
-        return !this.appId || !this.key;
-    }
-    get credentials() {
-        return {
-            collectUrl: this.collectUrl,
-            appId: this.appId,
-            apiToken: this.key,
-        };
-    }
-    defaultContext() {
-        return {
-            ...collectEventMeta(),
-            path: getDefaultPathname(),
-        };
-    }
-    /**
-     * Sends a page view (`event_name` / `event_type`: `pageview`) with full browser context.
-     */
-    pageview(path) {
-        if (this.disabled)
-            return false;
-        return sendPageViewBeacon(this.credentials, path ?? getDefaultPathname());
-    }
-    /**
-     * Sends a custom event. Default context is per-event meta + path; pass `context` to merge or override fields.
-     * Includes session_context so the backend can upsert session metadata.
-     */
-    event(input) {
-        if (this.disabled)
-            return false;
-        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 ?? {},
-            sessionContext: collectSessionMeta(),
-        });
-    }
-    /**
-     * Starts scroll, click, focus, visibility, and heartbeat tracking. Returns a stop function.
-     */
-    startEngagement() {
-        if (this.disabled)
-            return () => { };
-        return startEngagementTracking(this.credentials);
-    }
-}

package/dist/session.d.ts

@@ -1,11 +0,0 @@
-/**
- * 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

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

@@ -1,52 +0,0 @@
-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;
-}