refactor: convert events module to TS by jaissica12 · Pull Request #1258 · mParticle/mparticle-web-sdk

jaissica12 · 2026-05-12T21:06:31Z

Background

As part of the ongoing effort to migrate the mParticle Web SDK from JavaScript to TypeScript, this PR converts the events module and its corresponding test file to TypeScript for improved type safety and developer experience.

What Has Changed

Converted src/events.js to src/events.ts with full type annotations on all method parameters, return types, and internal variables
Converted test/src/tests-event-logging.js to test/src/tests-event-logging.ts with proper global type declarations and type casts for intentionally invalid test inputs
Updated src/events.interfaces.ts:
- Added TrackingCallback type for geolocation tracking
- Expanded logImpressionEvent signature to accept SDKImpression | SDKImpression[] | SDKProductImpression | SDKProductImpression[]
- Widened promotion param to accept SDKPromotion | SDKPromotion[]
Minor supporting type adjustments in:
- src/sdkRuntimeModels.ts — widened PromotionActionType to accept typed union
- src/serverModel.ts — added as string cast for PromotionActionType
- src/store.ts — added timeout to SDKConfig interface
- test/src/config/constants.ts — type cast for window.mParticle

Screenshots/Video

Checklist

I have performed a self-review of my own code.
I have made corresponding changes to the documentation.
I have added tests that prove my fix is effective or that my feature works.
I have tested this locally.

Additional Notes

Reference Issue (For employees only. Ignore if you are an outside contributor)

Closes https://go/j/SDKE-1106

cursor · 2026-05-13T11:51:15Z

PR Summary

Medium Risk
Impression payload mapping now supports two input shapes, which could change commerce events if callers mixed formats; geolocation callback ordering was refactored but existing tests still cover tracking behavior.

Overview
Migrates the events module from JavaScript to TypeScript: events.js → events.ts, with IEvents implemented via typed this, full parameter/return types, and let/const instead of var.

Public API typing is tightened in events.interfaces.ts: new TrackingCallback for location tracking (replacing generic Callback), logPromotionEvent accepts a single promotion or an array, and logImpressionEvent accepts SDKImpression, SDKProductImpression, or arrays of either.

Impression logging now branches on shape: objects with Name map like legacy SDKImpression; otherwise SDKProductImpression uses ProductImpressionList / ProductList (SDKE-1199).

Geolocation startTracking is restructured so if tracking is already active the callback runs immediately with stored coords; otherwise watchPosition starts as before.

Tests move to tests-event-logging.ts with global Should/geolocation typings and as Function / String(...) casts for invalid inputs and fetch bodies. Small support changes: SDKConfig.timeout, promotion type unions, and temporary as Function casts on ecommerce helpers until that module is typed.

^{Reviewed by Cursor Bugbot for commit 1f4ed64. Bugbot is set up for automated code reviews on this repo. Configure here.}

alexs-mparticle · 2026-05-19T19:11:31Z

    logEvent(event: BaseEvent, eventOptions?: SDKEventOptions): void;
    logImpressionEvent(
-        impression: SDKProductImpression,
+        impression: SDKImpression | SDKImpression[] | SDKProductImpression | SDKProductImpression[],


I brought this up with @rmi22186 earlier. I would like for us to not support both arrays and non-arrays for these endpoints, but that might have to be a follow up project.

Created a follow-up ticket to track this: https://go/j/SDKE-1199

alexs-mparticle · 2026-05-19T19:12:27Z

-            }
-        } else {
-            var position = {
+    this.startTracking = function(callback: ((position?: GeolocationPosition | { coords: { latitude: number | string; longitude: number | string } }) => void) | null): void {


We should define a TrackingCallback type here.

alexs-mparticle · 2026-05-19T19:13:07Z

            };
            triggerCallback(callback, position);
+        } else {
+            if ('geolocation' in navigator) {


If this is a TypeScript migration, why are we adding a conditional here?

This conditional was already present in the original events.js, it wasn't added as part of the migration. The only change here was flipping the if/else branch order to address a SonarCloud "unexpected negated condition" warning (the original had if (!mpInstance._Store.isTracking) first).

alexs-mparticle · 2026-05-19T19:13:31Z


-        function triggerCallback(callback, position) {
+        function triggerCallback(
+            callback: ((position?: GeolocationPosition | { coords: { latitude: number | string; longitude: number | string } }) => void) | null,


This should be a new type definition.

alexs-mparticle · 2026-05-19T19:15:39Z


        if (event) {
-            event.EventCategory = mpInstance._Ecommerce.convertProductActionToEventType(
+            // TODO(SDKE-1106): Remove `as Function` casts when ecommerce.js is migrated to TS


Suggested change

// TODO(SDKE-1106): Remove `as Function` casts when ecommerce.js is migrated to TS

// https://go.mparticle.com/work/SDKE-1106

Intentional, this is a temporary cast that will be resolved when the ecommerce module is migrated to TS. Didn't want to create an extra ticket for this so just kept comment and existing migration ticket as refrence

alexs-mparticle · 2026-05-19T19:19:05Z

-            element,
-            i;
+            element: Element,
+            i: number;


Suggested change

i: number;

elementIndex: number;

renamed i to elementIndex

alexs-mparticle · 2026-05-19T19:19:56Z


 export interface SDKPromotionAction {
-    PromotionActionType: string;
+    PromotionActionType: string | valueof<typeof PromotionActionType>;


can we just use valueof<typeof PromotionActionType> so we can control the values? string would allow any string, thus negating the valueof

Keeping string | valueof for now, tightening to just valueof causes a downstream cast failure in sdkToEventsApiConverter.ts where it converts to PromotionActionActionEnum. Fixing that properly would require changes beyond the scope of this migration PR. We can revisit this in a follow-up.

alexs-mparticle · 2026-05-19T19:20:18Z

    workspaceToken?: string;
    requiredWebviewBridgeName?: string;
    isLoggingEnabled?: boolean;
+    timeout?: number;


is this a new value introduced in this pr?

SDKConfig.timeout was already used in the original events.js (for the DOM event handler's setTimeout). It just wasn't declared in the SDKConfig interface, so TypeScript would error on access. Added the type to match the existing runtime shape.

alexs-mparticle · 2026-05-19T19:21:11Z

 } from './config/constants';
+import { IMParticleInstanceManager } from '../../src/sdkRuntimeModels';
+
+declare global {


Can't this be imported from elsewhere?

Added it in constants and importing from there

alexs-mparticle · 2026-05-19T19:21:33Z

+    }
+}
+
+const mParticle = window.mParticle as IMParticleInstanceManager;


IIRC, this should be imported from config?

updated constants.ts to export mParticle with the IMParticleInstanceManager type, so this test file now imports it directly from config. Removed the local cast and the declare global Window declaration.

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 3443450. Configure here.}

…ression input safely

…failure

sonarqubecloud · 2026-05-25T22:02:46Z

Quality Gate failed

Failed conditions
4.3% Duplication on New Code (required ≤ 3%)

See analysis details on SonarQube Cloud

jaissica12 changed the base branch from master to development May 12, 2026 21:07

jaissica12 marked this pull request as ready for review May 13, 2026 11:51

jaissica12 requested a review from a team as a code owner May 13, 2026 11:51

cursor Bot reviewed May 13, 2026

View reviewed changes

Comment thread src/events.ts Outdated

Comment thread src/events.ts Outdated

alexs-mparticle requested changes May 19, 2026

View reviewed changes

cursor Bot reviewed May 20, 2026

View reviewed changes

Comment thread src/events.ts

rmi22186 and others added 10 commits May 21, 2026 20:38

feat: Report deprecated method usage through logging dispatcher (#1270)

2578b9a

refactor: convert events module to TS

7526516

fix SonarCloud issues

0c78596

fix failing tests

21b560c

fix SonarCloud warnings

fc885cb

improve type safety in events module

7acabb1

use arrow functions to preserve this context and handle SDKProductImp…

d4b2253

…ression input safely

address PR comments

15d9342

revert PromotionActionType type tightening to avoid downstream build …

2154875

…failure

convert addEventHandler to arrow function

89505d4

jaissica12 force-pushed the refactor/SDKE-1106-migrate-event-modules-to-TS branch from d6ac4c2 to 89505d4 Compare May 25, 2026 21:47

revert globalThis.location.href to window.location.href

1f4ed64

jaissica12 requested a review from alexs-mparticle May 26, 2026 11:32

rmi22186 force-pushed the development branch from bfe52c3 to 44cd55d Compare May 26, 2026 16:03

	// TODO(SDKE-1106): Remove `as Function` casts when ecommerce.js is migrated to TS
	// https://go.mparticle.com/work/SDKE-1106

Conversation

jaissica12 commented May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Background

What Has Changed

Screenshots/Video

Checklist

Additional Notes

Reference Issue (For employees only. Ignore if you are an outside contributor)

Uh oh!

cursor Bot commented May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jaissica12 May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jaissica12 May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jaissica12 May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sonarqubecloud Bot commented May 25, 2026

Quality Gate failed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jaissica12 commented May 12, 2026 •

edited

Loading

cursor Bot commented May 13, 2026 •

edited

Loading

jaissica12 May 20, 2026 •

edited

Loading

jaissica12 May 20, 2026 •

edited

Loading

jaissica12 May 20, 2026 •

edited

Loading