@nommos/core

A core typed library, have constants, functions, types, enums and classes which serve as bases for the framework based nommos user activity tracking module.

🧩 Compatibility

| Technology | Version | |-----------|---------| | Node.js | ≥ 14.x | | TypeScript | ≥ 4.7 | | Browser Support | Modern browsers + evergreen versions |

🛠 Technologies & Build System

This library is built with:

• TypeScript
• RxJS
• ES2022 output
• Jest
• UUID
• STOMP-JS

🏷 Tags

tracking, analytics, typescript, events, observables, nommos, webSockets

Enums Definitions

ANALYTICS_ACTION

enum ANALYTICS_ACTION {
  SIGNIN = 'SIGNIN',
  REGISTRATION = 'REGISTRATION',
  BET = 'BET',
  MENU = 'MENU',
  TOURNAMENT = 'TOURNAMENT',
  SPORT = 'SPORT',
  DEPOSIT = 'DEPOSIT',
  VISIT = 'VISIT',
  COUPON = 'COUPON',
}

Description

Represents the various actions that are carried by a user.

Members

| Member | Value | Description | |--------|-------|-------------| | SIGNIN | "SIGNIN" | login or sign in action | | REGISTRATION | "REGISTRATION" | registration or sign up action | | BET | "BET" | Bet selection and placement action | | MENU | "MENU" | Menu selection action | | TOURNAMENT | "TOURNAMENT" | Tournament selection action | | SPORT | "SPORT" | Sport selection action | | DEPOSIT | "DEPOSIT" | Deposit or refill account action | | VISIT | "VISIT" | Site or platform is visited action | | COUPON | "COUPON" | Making or using a coupon code action |

ANALYTICS_ACTION_STATE

enum ANALYTICS_ACTION_STATE {
  SELECT = 'SELECT',
  UNSELECT = 'UN_SELECT',
  SUBMIT = 'SUBMIT',
  SUCCESS = 'SUCCESS',
  FAILURE = 'FAILURE',
  INIT = 'INIT',
}

Description

Represents the various states associated to an action carried by a user.

Members

| Member | Value | Description | |--------|-------|-------------| | SELECT | "SELECT" | An action was selected | | UNSELECT | "UN_SELECT" | An action was unselected | | SUBMIT | "SUBMIT" | An action was submitted | | SUCCESS | "SUCCESS" | An action was successful | | FAILURE | "FAILURE" | An action failed | | INIT | "INIT" | An action was initialized |

SITE_SOURCE

enum SITE_SOURCE {
  FACEBOOK = 'FACEBOOK',
  INSTAGRAM = 'INSTAGRAM',
  TWITTER = 'TWITTER',
  TELEGRAM = 'TELEGRAM',
  DIRECT = 'DIRECT',
  SMS = 'SMS',
}

Description

Represents the platform (Social Media, SMS or direct access) the user used to have access to the site where his actions are monitored.

Members

| Member | Value | Description | |--------|-------|-------------| | FACEBOOK | "FACEBOOK" | Accessed from Facebook | | INSTAGRAM | "INSTAGRAM" | Accessed from Instagram | | TWITTER | "TWITTER" | Accessed from Twitter | | TELEGRAM | "TELEGRAM" | Accessed from Telegram | | DIRECT | "DIRECT" | Accessed directly | | SMS | "SMS" | Accessed from an SMS |

Types and Interfaces Definitions

Interface: ConnectionConfig

interface ConnectionConfig {
  token: string;
  mode: string;
  baseUrl?: string;
}

Description

An Interface representing the required information for initializing the tracking module. All connection details are fetched from the API using the provided token.

Fields

| Field | type | Description | |--------|-------|-------------| | token | string | The access token for fetching configuration | | mode | string | Which stack to talk to, and how loudly to log. 'dev' targets the test backend and enables console diagnostics; anything else targets production and stays silent. | | baseUrl | string? | Overrides the backend URL mode would select. For local or self-hosted deployments only. |

Tokens are issued per environment. The test and production stacks have separate databases, so a token minted on one is not valid on the other — mode must match wherever the token came from. An unrecognised mode falls back to production rather than failing closed.

Interface: UrlTrackingKey

interface UrlTrackingKey {
  source: string;
  affiliateKey?: string;
  parrainageKey?: string;
}

Description

An Interface representing the query parameters that should be tracked on the site url to get the SITE_SOURCE and optionly the affiliateCode (for affiliate Tracking) and the parrainageCode (for parrainage Tracking)

Fields

| Field | type | Description | |--------|-------|-------------| | source | string | The query parameter key for SITE_SOURCE| | affiliateKey | string | The optional query parameter key for affiliateCode| | parrainageKey | string | The optional query parameter key for parrainageCode |

Interface: AnalyticsEvent

interface AnalyticsEvent {
  timeStamp: number;
  channel: number;
  source: SITE_SOURCE;
  action: ANALYTICS_ACTION;
  state: ANALYTICS_ACTION_STATE;
  affiliateCode?: string;
  uid: string;
  bid: string;
  ip?: string;
  data?: Record<string, unknown>;
  meta?: Record<string, unknown>;
}

Description

An Interface representing the event being actually tracked, holding information which are exploited in analytics.

Fields

| Field | type | Description | |--------|-------|-------------| | timeStamp | number | The date and time at which the action was carried| | channel | number | Information if the action was carried out on a mobile device or a desktop| | source | SITE_SOURCE | The platform from which the user came from | | action | ANALYTICS_ACTION | The action carried out by the user | | state | ANALYTICS_ACTION_STATE | The state associated to the action carried out by the user | | affiliateCode | string | The affilate code tracked from the site url | | uid | string | The ID of the user who carried out the action | | bid | string | An string to uniquely identify a user from the navigator used | | ip | string | Optional IP address of the machine from which the user is accessing the site | | data | Record<string, unknown> | Optional extra information concerning the action carried out by the user| | meta | Record<string, unknown> | Optional meta data of where the action was carried by the user|

Type: ActionSelectState

type AnalyticsEvent = Record<ANALYTICS_ACTION, boolean>;

Description

A type to represent the select state (SELECT or UNSELECT) of actions (ANALYTICS_ACTION) tracked.

Functions

Function: getQueryParams

getQueryParams(url)

Description

Extracts the query parameters from a url.

Parameters

| Name | Type | Required | Description | |------|------|----------|-------------| | url | string | true| The url from which to extra query parameters |

Returns

• Record<string, string> - The records of the query parameters (key, value)

Examples

import { getQueryParams } from "@nommos/core";

getQueryParams("http://example.com?name=james&department=science&count=61");
// Returns: { name: "james", department: "science", count: "61"}

getQueryParams("http://example.com");
// Returns: {}

getQueryParams("");
// Returns: {}

Function: normString

normString(s)

Description

Format a string by removing trailing spaces and lower cases it.

Parameters

| Name | Type | Required | Description | |------|------|----------|-------------| | s | string | true| The string to format|

Returns

• string - formatted string

Examples

import { normString } from "@nommos/core";

normString(" hello world ");
// Returns: "hello world"

getQueryParams("Big Bang Theory ");
// Returns: "big bang theory"

getQueryParams("GOOD-MORNING");
// Returns: "good-morning"

Function: userAgentInfo

userAgentInfo(ua)

Description

Get browser, operating system and channel (mobile or desktop) of a user agent.

Parameters

| Name | Type | Required | Description | |------|------|----------|-------------| | ua | string | true| The user agent of the device|

Returns

• {browser: string, os: string, channel: 3 | 7} - Object having browser, operating system and channel information|

Examples

import { userAgentInfo } from "@nommos/core";

userAgentInfo("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/119.0.0.0 Safari/537.36");
// Returns: {browser: "Chrome 119", os: "macOs 10.15.7", channel: 7 }

userAgentInfo("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/119.0.0.0 Safari/537.36 Edg/119.0.0.0");
// Returns: {browser: "Chrome 119", os: "Windows 10.0", channel: 7 }

userAgentInfo("Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Mobile Safari/537.36");
// Returns: {browser: "Chrome 114", os: "Android 10", channel: 3 }

Web Popups

CRM web popups are delivered to a visitor's inbox and surfaced by the SDK itself. Nothing here runs before marketing consent is granted.

The notification tray

Clicking the bell opens a tray listing what is waiting — title, preview, relative time, and an unread dot — and the visitor picks which one to open. From the tray they can also mark everything as seen, dismiss a single message, or mute the arrival chime.

Two things are deliberately not true of the tray:

• Opening it does not mark anything as read. Seeing a title in a list is not reading the message, so the tray issues no view call and reports no engagement against any popup. Only opening a popup does that.
• There is no "clear all". Dismissing is terminal — it means never show me this again — so it is offered per message rather than as one sweeping click.

A popup sent at HIGH or CRITICAL priority still opens by itself, bypassing the tray. That is what those priorities are for.

Placement: the anchor is required

The bell renders only where you put it. Mark a slot on your own page:

<header>
  <span data-nommos-notification-anchor></span>
</header>

The launcher mounts inside that element, carries no surface of its own, and inherits your text colour so it sits among your existing header icons rather than on top of them. The anchor is followed for the life of the page, so an SPA that renders its header after the SDK boots still works, and removing the anchor takes the bell down with it.

With no anchor there is no bell and no tray. There is deliberately no floating-corner fallback: putting a permanent button on your page is your decision, not ours.

Popups still arrive and still auto-open as modals — only the persistent entry point is withheld. The cost is that a popup the visitor closes (rather than dismisses) has no way back until the next page load, unless you call openViewer() yourself. If you want visitors to be able to revisit messages, add an anchor.

Once anchored, the bell is permanent — it stays put even when everything has been read. Vacating a slot you reserved would collapse your layout around the gap, and chrome that vanishes reads as broken rather than as tidy.

The tray opens downward from the bell, flipping upward when there is not enough room below (a footer or bottom bar).

Requirement: the anchor element must not sit inside an ancestor carrying transform, filter or contain. The tray and the modal are both position: fixed, which escapes overflow: hidden — a sticky header clipping its overflow is fine — but not a new containing block. A transformed ancestor will clip them.

Styling hooks

The launcher and tray expose CSS parts, so you can restyle them from your own page without reaching into the shadow root:

| Part | What it is | |------|-----------| | launcher-wrap | Positioning wrapper around the bell | | launcher | The bell button itself | | tray | The notification panel |

API

| Method | Description | |--------|-------------| | openViewer(popupId?) | Opens a popup directly, bypassing the tray. Defaults to the highest-ranked one. | | getInbox() | Returns WebPopupInboxState — the current items and their unread count. | | setPopupSoundEnabled(enabled) | Mutes or unmutes the arrival chime. Visitor-level, persisted in localStorage. |

const { items, unreadCount } = tracker.getInbox();
if (unreadCount > 0) {
  await tracker.openViewer(items[0].id);
}

Classes

Class: DataAttribution

Description

Represents a wrapper to extract informations associated to events being tracked and make them accessible for user activity tracking.

Properties

| Property | Type | Description | Default| |----------|------|-------------|--------| | loadedUserIp$ | Observable<boolean> | Observable to know if the user IP address was captured | none | | hasParrainOrAffiliate$ | Observable<boolean> | Observable to know if Affiliate or Parrainage code was captured | none| | stripUrlTrackedParams$ | Observable<boolean> | Observable to know whether to strip tracked query parameters from the url | none| | stripUrlTrackedParams$ | Observable<boolean> | Observable to know whether to strip tracked query parameters from the url | none|

Constructor

constructor(private readonly urlTrackingKey: UrlTrackingKey)

Parameters

| Name | Type | Required |Description| |------|------|----------|-----------| | urlTrackingKey | UrlTrackingKey | true | Query parameters to capture from url for tracking |

Getters

Getter: browserId

Description

Unique identifier for the browser used to visit the site

Returns string

Getter: userIp

Description

IP address of the machine used to visit the site

Returns string

Getter: source

Description

Source of the user visiting the site

Returns SITE_SOURCE

Getter: affiliate

Description

Affiliate code from the url used by the user

Returns string | null

Getter: parrainage

Description

Parrainage code from the url used by the user

Returns string | null

Getter: trackAffiliate

Description

Tells us if an affiliate code was not yet tracked and should be tracked or it should not.

Returns boolean

Methods

Method: init

Description

Initialize the capturing of query parameters to track from the site url

Parameters

| Name | Type | Required |Description| |------|------|----------|-----------| | currentUrl | string | true | Url from which to capture query parameters for tracking | | options | { stripFromUrl?: boolean } | false | Object to strip query parameters from url after capturing them. By default they are stripped off |

Returns void

Method: setLoadedIP

Description

Pushes a true to the loadedUserIP$ observable

Parameters none

Returns void

Method: fetchIp

Description

Fetches the IP address of the machine used to accessed the site and sets the current user IP address.

Parameters none

Returns Observable<void>

Method: clearSourceSession

Description

Clears the source key value from session storage

Parameters none

Returns void

Method: clearAffiliateSession

Description

Clears the affiliate code key value from session storage

Parameters none

Returns void

Method: clearAffiliateHistory

Description

Clears the affiliate code key value history from session storage

Parameters none

Returns void

Class: WebSocketClient

Description

Represents a wrapper for connecting/disconnecting from rabbit, keeping track of pending events tracked not yet published, publishing events tracked and managed rabbit reconnections and publishing of pending events tracked.

Properties

| Property | Type | Description | Default| |----------|------|-------------|--------| | pendingEvents | AnalyticsEvent[] | List of pending tracked events not yet published | [] | | stompAnalyticsConnected$ | Observable<boolean> | Observable for connection status to web socket for events publishing | none |

Constructor

constructor()

Parameters - none

Methods

Method: connectAnalyticsStomp

Description

Establishes a STOMP WebSocket connection and wires lifecycle handlers.

• On successful connection:
  • Emits true for reactive subscribers
  • Flushes all queued analytics events
• On broker error:
  • Logs structured error output

Parameters

| Name | Type | Required |Description| |------|------|----------|-----------| | cfg | ConnectionConfig | true | Configuration including URL, credentials, mode etc for connecting to the websocket |

Returns void

Method: publishAnalyticsMessage

Description

Publishes a tracked event to a RabbitMQ queue. If the connection is not ready, the event is automatically queued and delivered once the socket reconnects.

Parameters

| Name | Type | Required |Description| |------|------|----------|-----------| | payload | AnalyticsEvent | true | The analytics event to send |

Returns void

Method: disconnect

Description

Gracefully shuts down the STOMP client and updates connection status. Safe to call even if the client was never created or already disconnected.

Parameters none

Returns void

Class: EventTracker

Description

Represents a wrapper to initialize tracking and publishing of events with required informations and meta data. Once an instance is made, data about the user and found on the site current url are captured, and connection to the rabbit webs socket is established.

Properties

| Property | Type | Description | Default| |----------|------|-------------|--------| | analyticsEvent$ | Observable<AnalyticsEvent> | Observable holding recently pushed tracked event | none |

Constructor

constructor( private readonly cfg: ConnectionConfig, private readonly urlTrackingKey: UrlTrackingKey)

Parameters

| Name | Type | Required |Description| |------|------|----------|-----------| | cfg | ConnectionConfig | true | Configuration config to initialize the web socket connection | | urlTrackingKey | UrlTrackingKey | true | Query parameters to initialize an instance of DataAttribution for information collection |

Methods

Method: trackingIsEnabled

Description

Tells whether tracking is enabled/disabled from config

Parameters - none

Returns boolean

Method: getActionSelectState

Description

Get the selection state of an action

Parameters

| Name | Type | Required |Description| |------|------|----------|-----------| | action | ANALYTICS_ACTION | true | Action you want to know the selection state |

Returns boolean

Method: setActionSelectState

Description

Set the selection state of an action

Parameters

| Name | Type | Required |Description| |------|------|----------|-----------| | action | ANALYTICS_ACTION | true | Action you want to set the selection state | | selected | boolean | true | selection state |

Returns void

Method: trackEvent

Description

Constructs the user interaction event and emits it into a pipeline for storage. The event has the action, action state, extra information associated to the action and the user, and information gotten from the DataAttribution instance and the user agent of the device used. the mode of operation to set the action state. This method:

• Resolves the correct SELECT or UNSELECT state
• Enriches the event with attribution information
• Extracts browser/channel/OS from the user agent
• Publishes the event to s pipeline for storage

Parameters

| Name | Type | Required |Description| |------|------|----------|-----------| | action | ANALYTICS_ACTION | true | Action to be tracked| | state | ANALYTICS_ACTION_STATE | true | State associated to the action being tracked| | data | Record<string, unknown> \| null | false | Extra information associated to the action being tracked| | toggle | boolean | false | Boolean value to know whether toggle selection state of the Action| | selected | boolean \| null | false | Boolean value to set the selection state of the action tracked, it is prioritized over toggle| | userId | string | false | ID of the user whom carried out the action| | currentUrl | string | false | The url of the page where the action was carried out by the user|

Returns void

Method: unsubscribe

Description

Unsubscribe to subscriptions made during connection to the web socket, fetching the machine IP address and publishing events tracked. This should be called on destroying an instance of this class.

Parameters none

Returns void