@nexly/core 0.16.0 → 0.16.1

package/dist/collect.d.ts

@@ -55,6 +55,29 @@ export type StandardContextOverride = {
     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, …)

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;;;;;;;;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;;;;;;;;;;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"}
+{"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,6 +4,46 @@
  * 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);
 }

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 CData, type CollectCredentials, type IngestCredentials, type StandardContextOverride, 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,KAAK,EACV,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,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"}
+{"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/package.json

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