@nexly/core 0.6.0 → 0.8.0

package/dist/browser-meta.d.ts

@@ -1,9 +1,26 @@
 /**
- * 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.
+ * 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 +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"}
+{"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,7 +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.
+ * 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.
  */
@@ -14,19 +16,18 @@ function safe(fn) {
         return undefined;
     }
 }
-export function collectBrowserMeta() {
+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.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) {
@@ -41,10 +42,14 @@ export function collectBrowserMeta() {
     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.online = safe(() => navigator.onLine);
     out.hardware_concurrency = safe(() => navigator.hardwareConcurrency);
     out.max_touch_points = safe(() => navigator.maxTouchPoints);
     const conn = safe(() => navigator.connection);
@@ -87,15 +92,28 @@ export function collectBrowserMeta() {
             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 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 {};
     }
-    return Object.fromEntries(Object.entries(out).filter(([, v]) => v !== undefined && v !== '' && !(Array.isArray(v) && v.length === 0)));
+    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/collect.d.ts

@@ -5,8 +5,9 @@ export type IngestCredentials = {
 };
 /**
  * Event envelope:
- * - `context` — built-in traffic / device / locale (referrer, url, utm_*, os, device, …). Not owner-registered.
+ * - `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.
  */
 export type TrackEventInput = {
     credentials: IngestCredentials;
@@ -14,6 +15,7 @@ export type TrackEventInput = {
     eventType: string;
     context?: Record<string, unknown>;
     data?: Record<string, unknown>;
+    sessionContext?: Record<string, unknown>;
 };
 /** Full send: transport URL + event envelope. */
 export type SendBeaconCollectInput = TrackEventInput & {
@@ -26,6 +28,7 @@ export type CollectCredentials = {
 /**
  * Builds the JSON body for POST /v1/collect (snake_case wire format).
  * Duplicates `context.path` to top-level `path` when present.
+ * Includes `session_context` when provided (first event of a session).
  */
 export declare function buildCollectPayload(input: TrackEventInput): Record<string, unknown>;
 /**

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;;;;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"}
+{"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"}

package/dist/collect.js

@@ -4,6 +4,7 @@ function isPlainObject(v) {
 /**
  * Builds the JSON body for POST /v1/collect (snake_case wire format).
  * Duplicates `context.path` to 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 : {};
@@ -21,6 +22,10 @@ export function buildCollectPayload(input) {
     if (path) {
         body.path = path;
     }
+    const sc = isPlainObject(input.sessionContext) ? input.sessionContext : null;
+    if (sc && Object.keys(sc).length > 0) {
+        body.session_context = sc;
+    }
     return body;
 }
 /**

package/dist/events/engagement.d.ts

@@ -1,8 +1,12 @@
 import { type CollectCredentials } from '../collect.js';
 type StopFn = () => void;
 /**
- * Attaches engagement listeners (scroll, click, input focus, visibility, heartbeat).
+ * 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 {};

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

@@ -1 +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"}
+{"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,24 +1,27 @@
-import { collectBrowserMeta } from '../browser-meta.js';
+import { collectEventMeta, collectSessionMeta } from '../browser-meta.js';
 import { sendBeaconCollect } from '../collect.js';
 const CLICK_THROTTLE_MS = 500;
-const HEARTBEAT_INTERVAL_MS = 30_000;
+const KEEPALIVE_INTERVAL_MS = 60_000;
 const SCROLL_DEBOUNCE_MS = 300;
-function makeContext() {
-    return collectBrowserMeta();
-}
-function sendEngagement(creds, eventName, eventType, data) {
+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: makeContext(),
+        context: collectEventMeta(),
         data,
+        sessionContext,
     });
 }
 /**
- * Attaches engagement listeners (scroll, click, input focus, visibility, heartbeat).
+ * 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') {
@@ -26,6 +29,20 @@ export function startEngagementTracking(creds) {
     }
     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;
@@ -91,50 +108,36 @@ export function startEngagementTracking(creds) {
         });
     }
     document.addEventListener('focusin', onFocusIn, { signal });
-    // ---- visibility / visit duration ----
-    let visibleSince = document.visibilityState === 'visible' ? Date.now() : 0;
-    let accumulatedVisibleMs = 0;
+    // ---- visibility / session summary ----
     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' });
+            if (activeSeconds > 0) {
+                sendEngagement(creds, 'session_ping', 'lifecycle', { active_seconds: activeSeconds });
             }
         }
-        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' });
+        sendEngagement(creds, 'session_end', 'lifecycle', { active_seconds: activeSeconds });
     }
     window.addEventListener('beforeunload', onBeforeUnload, { signal });
-    // ---- heartbeat ----
-    const startTime = Date.now();
-    function sendHeartbeat() {
+    // ---- keepalive heartbeat (60s, lightweight, for realtime dashboard) ----
+    function sendKeepalive() {
         if (document.visibilityState !== 'visible')
             return;
-        const elapsed = Math.round((Date.now() - startTime) / 1000);
-        sendEngagement(creds, 'heartbeat', 'lifecycle', { elapsed_seconds: elapsed });
+        sendEngagement(creds, 'heartbeat', 'lifecycle', { active_seconds: activeSeconds }, getSessionContextOnce());
     }
-    const heartbeatId = setInterval(sendHeartbeat, HEARTBEAT_INTERVAL_MS);
+    // 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(heartbeatId);
+        clearInterval(activeTickId);
+        clearInterval(keepaliveId);
     };
 }

package/dist/events/pageview.d.ts

@@ -2,7 +2,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).
+ * 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 +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"}
+{"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,11 +1,12 @@
-import { collectBrowserMeta } from '../browser-meta.js';
+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: fills `context` with {@link collectBrowserMeta} and sets `path` (overrides pathname from the location snapshot).
+ * 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({
@@ -14,9 +15,10 @@ export function sendPageViewBeacon(creds, path = getDefaultPathname()) {
         eventName: 'pageview',
         eventType: 'pageview',
         context: {
-            ...collectBrowserMeta(),
+            ...collectEventMeta(),
             path,
         },
         data: {},
+        sessionContext: collectSessionMeta(),
     });
 }

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 /**
  * Browser event ingest client (public API).
  */
-export { Nexly, type NexlyEventInput, type NexlyInit } from './nexly.js';
-export { collectBrowserMeta } from './browser-meta.js';
+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';

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

package/dist/index.js

@@ -2,7 +2,7 @@
  * Browser event ingest client (public API).
  */
 export { Nexly } from './nexly.js';
-export { collectBrowserMeta } from './browser-meta.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';

package/dist/nexly.d.ts

@@ -5,9 +5,11 @@ export type NexlyInit = {
     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: string;
+    type: NexlyEventType;
     data?: Record<string, unknown>;
     /** Merged on top of default browser context (see {@link collectBrowserMeta}) and current `path`. */
     context?: Record<string, unknown>;
@@ -35,7 +37,8 @@ export declare class Nexly {
      */
     pageview(path?: string): boolean;
     /**
-     * Sends a custom event. Default context is browser meta + path; pass `context` to merge or override fields.
+     * 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;
     /**

package/dist/nexly.d.ts.map

@@ -1 +1 @@
-{"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,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,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;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"}
+{"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;IAM3B,OAAO,KAAK,WAAW,GAMtB;IAED,OAAO,CAAC,cAAc;IAOtB;;OAEG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO;IAIhC;;;OAGG;IACH,KAAK,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO;IAetC;;OAEG;IACH,eAAe,IAAI,MAAM,IAAI;CAG9B"}

package/dist/nexly.js

@@ -1,4 +1,4 @@
-import { collectBrowserMeta } from './browser-meta.js';
+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';
@@ -36,7 +36,7 @@ export class Nexly {
     }
     defaultContext() {
         return {
-            ...collectBrowserMeta(),
+            ...collectEventMeta(),
             path: getDefaultPathname(),
         };
     }
@@ -47,7 +47,8 @@ export class Nexly {
         return sendPageViewBeacon(this.credentials, path ?? getDefaultPathname());
     }
     /**
-     * Sends a custom event. Default context is browser meta + path; pass `context` to merge or override fields.
+     * 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) {
         const context = input.context
@@ -60,6 +61,7 @@ export class Nexly {
             eventType: input.type,
             context,
             data: input.data ?? {},
+            sessionContext: collectSessionMeta(),
         });
     }
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nexly/core",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Nexly browser ingest core (sendBeacon, Nexly client, context, engagement)",
   "license": "MIT",
   "keywords": [