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 to expand the logImpressionEvent signature to accept SDKImpression | SDKImpression[] | SDKProductImpression | SDKProductImpression[]
Minor supporting type adjustments in src/sdkRuntimeModels.ts, src/serverModel.ts, and src/store.ts

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
Touches core event/commerce logging and location tracking codepaths; changes are largely type-safety oriented but broaden accepted impression/promotion inputs and adjust some runtime handling, so regressions would impact analytics payloads.

Overview
Refactors the Events module to TypeScript with explicit types for event logging, commerce events, DOM event handlers, and location tracking (including safer error logging and globalThis.location navigation).

Expands commerce helper APIs to accept more input shapes: logImpressionEvent now supports both SDKImpression and SDKProductImpression (single or array), and logPromotionEvent accepts single or multiple promotions; related model types and server DTO casting were adjusted to keep payload serialization compatible.

Updates config/runtime typing (SDKConfig.timeout) and converts the event-logging test suite to TypeScript, adding global type declarations and deliberate casts for invalid-input test cases.

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

…ression input safely

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.

…failure

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.}

sonarqubecloud · 2026-05-21T01:20:40Z

Quality Gate failed

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

See analysis details on SonarQube Cloud

refactor: convert events module to TS

6f952d8

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

jaissica12 added 4 commits May 13, 2026 07:09

fix SonarCloud issues

469e728

fix failing tests

8ad6296

fix SonarCloud warnings

4de7ee4

improve type safety in events module

14dfc68

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

Comment thread src/events.ts Outdated

use arrow functions to preserve this context and handle SDKProductImp…

12da570

…ression input safely

alexs-mparticle requested changes May 19, 2026

View reviewed changes

jaissica12 added 2 commits May 20, 2026 17:12

address PR comments

272342c

revert PromotionActionType type tightening to avoid downstream build …

3443450

…failure

cursor Bot reviewed May 20, 2026

View reviewed changes

Comment thread src/events.ts

convert addEventHandler to arrow function

d6ac4c2

	// 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 21, 2026

Quality Gate failed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 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