@nexly/core 0.15.4 → 0.16.1

package/dist/collect.d.ts

@@ -16,10 +16,77 @@ export type CollectCredentials = {
     /** Which SDK identity to report (see {@link TrackEventInput.client}). Optional. */
     client?: NexlyClient;
 } & IngestCredentials;
+/**
+ * Top-level scalar payload used by the `cdata` slot. The contract is
+ * intentionally narrow: a flat object whose values are `string`,
+ * `number`, or `boolean`. All values are normalised to strings
+ * server-side (see `internal/apps/ingest_sanitize.go::SanitizeCData`)
+ * so downstream analytics deal with one type per key. Nested objects
+ * and arrays are silently dropped — push richer payloads through a
+ * different surface.
+ */
+export type CData = Record<string, string | number | boolean>;
+/**
+ * Typed override for the per-event attribution slot accepted by
+ * {@link NexlyBase.customEvent}'s third parameter. Mirrors
+ * `internal/apps/ingest_context.go::StandardAttributionKeys` —
+ * keep both ends in sync when adding new marketing parameters.
+ *
+ * Standard attribution keys are also auto-extracted by the server
+ * from the landing URL on the first event of a session; this type
+ * lets callers manually override the per-event value when the URL
+ * no longer carries the parameter (deep-links, post-navigation
+ * clicks, server-side redirects).
+ */
+export type StandardContextOverride = {
+    utm_source?: string;
+    utm_medium?: string;
+    utm_campaign?: string;
+    utm_content?: string;
+    utm_term?: string;
+    gclid?: string;
+    gad_source?: string;
+    gad_campaignid?: string;
+    fbclid?: string;
+    msclkid?: string;
+    ttclid?: string;
+    li_fat_id?: string;
+    yclid?: string;
+    mc_cid?: string;
+    ref?: string;
+};
+/**
+ * Runtime mirror of the keys in {@link StandardContextOverride}.
+ * Mirrors `internal/apps/ingest_context.go::StandardAttributionKeys`
+ * on the server — when adding a new marketing parameter, update both
+ * sides plus the type above.
+ *
+ * Useful when application code needs to split a free-form payload
+ * into the {@link CData} slot (product-data) and the third `context`
+ * parameter of {@link NexlyBase.customEvent} (attribution
+ * overrides). Note that `ref` is included because it is a
+ * standard affiliate / referral parameter; apps that use `ref` as
+ * a product-internal code (e.g. Vaiz) should treat it as cdata
+ * rather than attribution — partition it out manually.
+ */
+export declare const STANDARD_ATTRIBUTION_KEYS: readonly ["utm_source", "utm_medium", "utm_campaign", "utm_content", "utm_term", "gclid", "gad_source", "gad_campaignid", "fbclid", "msclkid", "ttclid", "li_fat_id", "yclid", "mc_cid", "ref"];
+/** Union of {@link STANDARD_ATTRIBUTION_KEYS} entries. */
+export type StandardAttributionKey = (typeof STANDARD_ATTRIBUTION_KEYS)[number];
+/**
+ * Returns `true` when `key` is a member of {@link STANDARD_ATTRIBUTION_KEYS}.
+ * Use this as a predicate when splitting a flat payload into the
+ * {@link CData} slot and the attribution-overrides slot.
+ */
+export declare function isStandardAttributionKey(key: string): key is StandardAttributionKey;
 /**
  * Event envelope:
- * - `context` — per-event volatile metadata (path, screen, viewport, visitor_id, session_id, …).
- * - `data` — owner-defined custom properties.
+ * - `context` — per-event volatile metadata (path, screen, viewport, visitor_id, session_id, …)
+ *   plus optional standard attribution overrides (`utm_*`, `gclid`, …).
+ * - `data` — SDK-emitted built-in event payload (engagement: `tag`/`max_percent`,
+ *   lifecycle: `active_seconds`, …). Validated server-side against a per-event-type
+ *   allowlist; user-defined keys belong in `cdata` instead.
+ * - `cdata` — user-defined custom analytics payload validated against the per-app
+ *   `Custom data` registry. Scalar contract — see {@link CData}.
  * - `session_context` — session-stable metadata (OS, locale, screen), sent once per session.
  */
 export type TrackEventInput = {
@@ -34,11 +101,13 @@ export type TrackEventInput = {
     client?: NexlyClient;
     context?: Record<string, unknown>;
     data?: Record<string, unknown>;
+    cdata?: CData;
     sessionContext?: Record<string, unknown>;
 };
 /**
  * Builds the JSON body for POST /v1/collect (snake_case wire format).
  * Duplicates `context.path` to the top-level `path` when present.
+ * Includes `cdata` when the caller passed a non-empty object.
  * 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;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAE/C,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;IAClB,mFAAmF;IACnF,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB,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;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,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,CAwBnF"}
+{"version":3,"file":"collect.d.ts","sourceRoot":"","sources":["../src/collect.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAE/C,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;IAClB,mFAAmF;IACnF,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB,GAAG,iBAAiB,CAAA;AAErB;;;;;;;;GAQG;AACH,MAAM,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAA;AAE7D;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,GAAG,CAAC,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,yBAAyB,iMAgB5B,CAAA;AAEV,0DAA0D;AAC1D,MAAM,MAAM,sBAAsB,GAAG,CAAC,OAAO,yBAAyB,CAAC,CAAC,MAAM,CAAC,CAAA;AAI/E;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,IAAI,sBAAsB,CAEnF;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,WAAW,EAAE,iBAAiB,CAAA;IAC9B,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC9B,KAAK,CAAC,EAAE,KAAK,CAAA;IACb,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACzC,CAAA;AAMD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA4BnF"}

package/dist/collect.js

@@ -4,12 +4,53 @@
  * This module is safe to import from any runtime (browser, React Native, Node).
  * Transport (beacon / fetch / native) lives in platform-specific packages.
  */
+/**
+ * Runtime mirror of the keys in {@link StandardContextOverride}.
+ * Mirrors `internal/apps/ingest_context.go::StandardAttributionKeys`
+ * on the server — when adding a new marketing parameter, update both
+ * sides plus the type above.
+ *
+ * Useful when application code needs to split a free-form payload
+ * into the {@link CData} slot (product-data) and the third `context`
+ * parameter of {@link NexlyBase.customEvent} (attribution
+ * overrides). Note that `ref` is included because it is a
+ * standard affiliate / referral parameter; apps that use `ref` as
+ * a product-internal code (e.g. Vaiz) should treat it as cdata
+ * rather than attribution — partition it out manually.
+ */
+export const STANDARD_ATTRIBUTION_KEYS = [
+    'utm_source',
+    'utm_medium',
+    'utm_campaign',
+    'utm_content',
+    'utm_term',
+    'gclid',
+    'gad_source',
+    'gad_campaignid',
+    'fbclid',
+    'msclkid',
+    'ttclid',
+    'li_fat_id',
+    'yclid',
+    'mc_cid',
+    'ref',
+];
+const STANDARD_ATTRIBUTION_KEY_SET = new Set(STANDARD_ATTRIBUTION_KEYS);
+/**
+ * Returns `true` when `key` is a member of {@link STANDARD_ATTRIBUTION_KEYS}.
+ * Use this as a predicate when splitting a flat payload into the
+ * {@link CData} slot and the attribution-overrides slot.
+ */
+export function isStandardAttributionKey(key) {
+    return STANDARD_ATTRIBUTION_KEY_SET.has(key);
+}
 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 the top-level `path` when present.
+ * Includes `cdata` when the caller passed a non-empty object.
  * Includes `session_context` when provided (first event of a session).
  */
 export function buildCollectPayload(input) {
@@ -31,6 +72,10 @@ export function buildCollectPayload(input) {
     if (pathFromContext) {
         body.path = pathFromContext;
     }
+    const cdata = isPlainObject(input.cdata) ? input.cdata : null;
+    if (cdata && Object.keys(cdata).length > 0) {
+        body.cdata = cdata;
+    }
     const sc = isPlainObject(input.sessionContext) ? input.sessionContext : null;
     if (sc && Object.keys(sc).length > 0) {
         body.session_context = sc;

package/dist/index.d.ts

@@ -5,7 +5,7 @@
  * - `@nexly/web` — browser (sendBeacon, DOM meta, engagement listeners).
  * - `@nexly/react-native` — React Native (fetch, AsyncStorage, AppState).
  */
-export { buildCollectPayload, type CollectCredentials, type IngestCredentials, type TrackEventInput, } from './collect.js';
+export { buildCollectPayload, isStandardAttributionKey, STANDARD_ATTRIBUTION_KEYS, type CData, type CollectCredentials, type IngestCredentials, type StandardAttributionKey, type StandardContextOverride, type TrackEventInput, } from './collect.js';
 export { NexlyBase, DEFAULT_COLLECT_URL, type NexlyEventInput, type NexlyEventType, type NexlyInit, } from './nexly-base.js';
 export { NexlyClient } from './clients.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;;;;;;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;AACxB,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,yBAAyB,EACzB,KAAK,KAAK,EACV,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC5B,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;AACxB,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA"}

package/dist/index.js

@@ -5,6 +5,6 @@
  * - `@nexly/web` — browser (sendBeacon, DOM meta, engagement listeners).
  * - `@nexly/react-native` — React Native (fetch, AsyncStorage, AppState).
  */
-export { buildCollectPayload, } from './collect.js';
+export { buildCollectPayload, isStandardAttributionKey, STANDARD_ATTRIBUTION_KEYS, } from './collect.js';
 export { NexlyBase, DEFAULT_COLLECT_URL, } from './nexly-base.js';
 export { NexlyClient } from './clients.js';

package/dist/nexly-base.d.ts

@@ -1,5 +1,5 @@
 import type { NexlyClient } from './clients.js';
-import { type IngestCredentials } from './collect.js';
+import { type CData, type IngestCredentials, type StandardContextOverride } 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 = {
@@ -22,7 +22,22 @@ export type NexlyEventType = 'pageview' | 'engagement' | 'custom' | 'navigation'
 export type NexlyEventInput = {
     name: string;
     type: NexlyEventType | string;
+    /**
+     * SDK-emitted built-in event payload. For built-in event types
+     * (`engagement`, `lifecycle`, `pageview`, `navigation`) the server
+     * validates this against a per-event-type allowlist. For
+     * `type: 'custom'` events, user-defined payload belongs in
+     * {@link cdata} instead — `data` is reserved for SDK metrics.
+     */
     data?: Record<string, unknown>;
+    /**
+     * User-defined custom analytics payload. Top-level scalar map
+     * (`string` / `number` / `boolean`). Server validates against the
+     * per-app `Custom data` registry; unapproved keys are discovered
+     * but not stored. Use {@link NexlyBase.customEvent} for the
+     * ergonomic per-event API.
+     */
+    cdata?: CData;
     /** Merged on top of default platform context (see {@link NexlyBase.collectEventContext}). */
     context?: Record<string, unknown>;
 };
@@ -72,9 +87,26 @@ export declare abstract class NexlyBase {
      */
     pageview(path?: string): boolean;
     /**
-     * Sends a custom event. Pass `context` to merge or override default fields.
+     * Sends a generic event. The unstructured `context` is merged on top
+     * of the default platform context; `data` carries SDK-internal
+     * payload (or user payload for legacy callers; new code should
+     * prefer {@link customEvent} for custom analytics).
      */
     event(input: NexlyEventInput): boolean;
+    /**
+     * Sends a custom analytics event. `cdata` carries the user-defined
+     * scalar payload that the server validates against the per-app
+     * `Custom data` registry. The optional `context` slot is the typed
+     * override for standard attribution keys (`utm_*`, `gclid`,
+     * `gad_source`, …) when the landing URL no longer carries them at
+     * event time (deep links, post-navigation clicks, server-side
+     * redirects).
+     *
+     * Equivalent to calling `event({ name, type: 'custom', cdata,
+     * context })` but with a tighter type for `context` (only standard
+     * attribution keys, no free-form fields).
+     */
+    customEvent(name: string, cdata?: CData, context?: StandardContextOverride): boolean;
     private dispatch;
 }
 //# sourceMappingURL=nexly-base.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"nexly-base.d.ts","sourceRoot":"","sources":["../src/nexly-base.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC/C,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;IACX;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB,CAAA;AAED,gEAAgE;AAChE,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,YAAY,GAAG,QAAQ,GAAG,YAAY,CAAA;AAEhF,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;;;;;;;;;;;;GAYG;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;IACpB,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,CAAA;IAExC;;;;;;OAMG;IACH,OAAO,CAAC,qBAAqB,CAAsB;IAEnD,SAAS,aAAa,IAAI,EAAE,SAAS;IASrC,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;;OAEG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO;IAWhC;;OAEG;IACH,KAAK,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO;IAYtC,OAAO,CAAC,QAAQ;CA4BjB"}
+{"version":3,"file":"nexly-base.d.ts","sourceRoot":"","sources":["../src/nexly-base.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC/C,OAAO,EAEL,KAAK,KAAK,EACV,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,EAC7B,MAAM,cAAc,CAAA;AAIrB,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;IACX;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB,CAAA;AAED,gEAAgE;AAChE,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,YAAY,GAAG,QAAQ,GAAG,YAAY,CAAA;AAEhF,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,cAAc,GAAG,MAAM,CAAA;IAC7B;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC9B;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,KAAK,CAAA;IACb,6FAA6F;IAC7F,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAClC,CAAA;AAED;;;;;;;;;;;;GAYG;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;IACpB,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,CAAA;IAExC;;;;;;OAMG;IACH,OAAO,CAAC,qBAAqB,CAAsB;IAEnD,SAAS,aAAa,IAAI,EAAE,SAAS;IASrC,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;;OAEG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO;IAWhC;;;;;OAKG;IACH,KAAK,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO;IAatC;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,uBAAuB,GAAG,OAAO;IAapF,OAAO,CAAC,QAAQ;CA8BjB"}

package/dist/nexly-base.js

@@ -1,4 +1,4 @@
-import { buildCollectPayload } from './collect.js';
+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.
@@ -65,7 +65,10 @@ export class NexlyBase {
         });
     }
     /**
-     * Sends a custom event. Pass `context` to merge or override default fields.
+     * Sends a generic event. The unstructured `context` is merged on top
+     * of the default platform context; `data` carries SDK-internal
+     * payload (or user payload for legacy callers; new code should
+     * prefer {@link customEvent} for custom analytics).
      */
     event(input) {
         if (this.disabled)
@@ -77,6 +80,33 @@ export class NexlyBase {
             eventType: input.type,
             context,
             data: input.data ?? {},
+            cdata: input.cdata,
+        });
+    }
+    /**
+     * Sends a custom analytics event. `cdata` carries the user-defined
+     * scalar payload that the server validates against the per-app
+     * `Custom data` registry. The optional `context` slot is the typed
+     * override for standard attribution keys (`utm_*`, `gclid`,
+     * `gad_source`, …) when the landing URL no longer carries them at
+     * event time (deep links, post-navigation clicks, server-side
+     * redirects).
+     *
+     * Equivalent to calling `event({ name, type: 'custom', cdata,
+     * context })` but with a tighter type for `context` (only standard
+     * attribution keys, no free-form fields).
+     */
+    customEvent(name, cdata, context) {
+        if (this.disabled)
+            return false;
+        const defaultContext = { ...this.collectEventContext(), path: this.getDefaultPath() };
+        const merged = context ? { ...defaultContext, ...context } : defaultContext;
+        return this.dispatch({
+            eventName: name,
+            eventType: 'custom',
+            context: merged,
+            data: {},
+            cdata,
         });
     }
     dispatch(args) {
@@ -96,6 +126,7 @@ export class NexlyBase {
             client: this.client,
             context: args.context,
             data: args.data,
+            cdata: args.cdata,
             sessionContext,
         });
         return this.transport(payload);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nexly/core",
-  "version": "0.15.4",
+  "version": "0.16.1",
   "description": "Nexly ingest core (platform-agnostic): types, payload builder, abstract NexlyBase client",
   "license": "MIT",
   "keywords": [