@nexly/core 0.5.0 → 0.7.0

package/README.md

@@ -23,6 +23,16 @@ nexly.event({ name: 'click', type: 'engagement', data: { id: 'x' } })
 
 Constructor options use the `NexlyInit` type from the published typings.
 
+### Singleton
+
+When using a provider (`@nexly/react-web` or `@nexly/next`), the client is also available as a singleton — useful for plain functions outside the React tree:
+
+```ts
+import { Nexly } from '@nexly/core'
+
+Nexly.getInstance()?.event({ name: 'click', type: 'engagement' })
+```
+
 ## API
 
 The package ships `.d.ts` files; use your editor or `node_modules` typings for the full export list.

package/dist/events/engagement.js

@@ -103,7 +103,7 @@ export function startEngagementTracking(creds) {
             flushScrollDepth();
             const secs = Math.round(accumulatedVisibleMs / 1000);
             if (secs > 0) {
-                sendEngagement(creds, 'visibility_change', 'lifecycle', { visible_seconds: secs, state: 'hidden' });
+                sendEngagement(creds, 'visibility_change', 'engagement', { visible_seconds: secs, state: 'hidden' });
             }
         }
         else {
@@ -118,7 +118,7 @@ export function startEngagementTracking(creds) {
         }
         flushScrollDepth();
         const secs = Math.round(accumulatedVisibleMs / 1000);
-        sendEngagement(creds, 'visibility_change', 'lifecycle', { visible_seconds: secs, state: 'unload' });
+        sendEngagement(creds, 'visibility_change', 'engagement', { visible_seconds: secs, state: 'unload' });
     }
     window.addEventListener('beforeunload', onBeforeUnload, { signal });
     // ---- heartbeat ----
@@ -127,7 +127,7 @@ export function startEngagementTracking(creds) {
         if (document.visibilityState !== 'visible')
             return;
         const elapsed = Math.round((Date.now() - startTime) / 1000);
-        sendEngagement(creds, 'heartbeat', 'lifecycle', { elapsed_seconds: elapsed });
+        sendEngagement(creds, 'heartbeat', 'engagement', { elapsed_seconds: elapsed });
     }
     const heartbeatId = setInterval(sendHeartbeat, HEARTBEAT_INTERVAL_MS);
     // ---- cleanup ----

package/dist/index.d.ts

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

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,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/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>;
@@ -16,6 +18,14 @@ export type NexlyEventInput = {
  * 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;

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,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;;OAEG;IACH,KAAK,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO;IActC;;OAEG;IACH,eAAe,IAAI,MAAM,IAAI;CAG9B"}

package/dist/nexly.js

@@ -6,6 +6,19 @@ 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;

package/package.json

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