fix(ramps): persist terminal analytics dedupe

Co-authored-by: Lorenzo <lorenzosantos@users.noreply.github.com>

Author: cursoragent

app/core/Engine/controllers/ramps-controller/event-handlers/analytics.test.ts

@@ -929,6 +929,17 @@ describe('handleOrderStatusChangedForMetrics', () => {
       expect(mockTrackEvent).not.toHaveBeenCalled();
     });
 
+    it('does NOT re-emit when a previous terminal emit is rehydrated after app relaunch', () => {
+      ReduxService.store = configureStore({
+        terminalOrderAnalytics: { 'order-1': Date.now() },
+      });
+      const order = createMockOrder({ status: Status.Completed });
+
+      emitTerminalOrderAnalyticsFromCallback(order);
+
+      expect(mockTrackEvent).not.toHaveBeenCalled();
+    });
+
     it('tags a headless terminal failure as HEADLESS when a context entry exists', () => {
       const order = createMockOrder({
         status: Status.Failed,

app/core/Engine/controllers/ramps-controller/terminalOrderAnalyticsRegistry.ts

@@ -2,6 +2,11 @@ import {
   getInternalOrderCode,
   type RampsOrder,
 } from '@metamask/ramps-controller';
+import ReduxService from '../../../redux';
+import {
+  clearTerminalOrderAnalyticsEntries,
+  markTerminalOrderAnalyticsEmittedEntry,
+} from '../../../redux/slices/terminalOrderAnalytics';
 
 /**
  * Terminal-order analytics dedup registry (TRAM-3691).
@@ -29,9 +34,10 @@ import {
  * so `getInternalOrderCode` yields an identical key for the same order. Keying
  * off the raw `providerOrderId` would NOT be stable across those two paths.
  *
- * In-memory, same-session only (mirrors `headlessOrderContextRegistry`). A
- * process relaunch clears it; that is acceptable here because a terminal order
- * added after relaunch is a first observation in that session and SHOULD emit.
+ * The key is persisted in the `terminalOrderAnalytics` redux slice so app
+ * relaunches and repeated callback returns do not turn the same order settlement
+ * into multiple Mixpanel events. The local Set is retained as an immediate
+ * same-tick guard in case Redux persistence is temporarily unavailable.
  */
 const emittedTerminalOrders = new Set<string>();
 
@@ -41,7 +47,9 @@ const emittedTerminalOrders = new Set<string>();
  * @param order - The order whose terminal event was just emitted.
  */
 export function markTerminalOrderAnalyticsEmitted(order: RampsOrder): void {
-  emittedTerminalOrders.add(getInternalOrderCode(order));
+  const orderCode = getInternalOrderCode(order);
+  emittedTerminalOrders.add(orderCode);
+  ReduxService.store.dispatch(markTerminalOrderAnalyticsEmittedEntry(orderCode));
 }
 
 /**
@@ -52,7 +60,11 @@ export function markTerminalOrderAnalyticsEmitted(order: RampsOrder): void {
  * @returns True when a terminal event was already emitted for the order.
  */
 export function hasEmittedTerminalOrderAnalytics(order: RampsOrder): boolean {
-  return emittedTerminalOrders.has(getInternalOrderCode(order));
+  const orderCode = getInternalOrderCode(order);
+  return (
+    emittedTerminalOrders.has(orderCode) ||
+    Boolean(ReduxService.store.getState().terminalOrderAnalytics[orderCode])
+  );
 }
 
 /**
@@ -61,4 +73,5 @@ export function hasEmittedTerminalOrderAnalytics(order: RampsOrder): boolean {
  */
 export function __resetTerminalOrderAnalyticsRegistryForTests(): void {
   emittedTerminalOrders.clear();
+  ReduxService.store.dispatch(clearTerminalOrderAnalyticsEntries());
 }

app/core/redux/slices/terminalOrderAnalytics.test.ts

@@ -0,0 +1,52 @@
+import reducer, {
+  TERMINAL_ORDER_ANALYTICS_TTL_MS,
+  clearTerminalOrderAnalyticsEntries,
+  markTerminalOrderAnalyticsEmittedEntry,
+  type TerminalOrderAnalyticsState,
+} from './terminalOrderAnalytics';
+
+describe('terminalOrderAnalytics slice', () => {
+  const NOW = 1_700_000_000_000;
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('stores an emitted terminal order key with a timestamp', () => {
+    jest.spyOn(Date, 'now').mockReturnValue(NOW);
+
+    const state = reducer(
+      undefined,
+      markTerminalOrderAnalyticsEmittedEntry('order-1'),
+    );
+
+    expect(state).toEqual({ 'order-1': NOW });
+  });
+
+  it('clears all emitted terminal order keys', () => {
+    const initial: TerminalOrderAnalyticsState = {
+      'order-1': NOW,
+      'order-2': NOW,
+    };
+
+    expect(reducer(initial, clearTerminalOrderAnalyticsEntries())).toEqual({});
+  });
+
+  it('evicts entries older than the TTL on write', () => {
+    const stale: TerminalOrderAnalyticsState = {
+      'stale-order': NOW - TERMINAL_ORDER_ANALYTICS_TTL_MS - 1,
+      'fresh-order': NOW - 1000,
+    };
+    jest.spyOn(Date, 'now').mockReturnValue(NOW);
+
+    const state = reducer(
+      stale,
+      markTerminalOrderAnalyticsEmittedEntry('new-order'),
+    );
+
+    expect(state).toEqual({
+      'fresh-order': NOW - 1000,
+      'new-order': NOW,
+    });
+  });
+});

app/core/redux/slices/terminalOrderAnalytics.ts

@@ -0,0 +1,51 @@
+import { createSlice, type PayloadAction } from '@reduxjs/toolkit';
+
+/**
+ * Terminal analytics events represent one order reaching a terminal state
+ * (completed/failed/cancelled). Keep a bounded persisted record so callback
+ * re-fetches, app relaunches, and polling races cannot emit the same terminal
+ * event repeatedly for the same order.
+ */
+export type TerminalOrderAnalyticsState = Record<string, number>;
+
+/**
+ * 90 days is long enough to cover delayed settlement and users reopening old
+ * orders, while keeping the persisted key set bounded.
+ */
+export const TERMINAL_ORDER_ANALYTICS_TTL_MS = 90 * 24 * 60 * 60 * 1000;
+
+export const initialState: TerminalOrderAnalyticsState = {};
+
+const pruneExpiredEntries = (
+  state: TerminalOrderAnalyticsState,
+  now: number,
+): void => {
+  for (const key of Object.keys(state)) {
+    if (now - state[key] > TERMINAL_ORDER_ANALYTICS_TTL_MS) {
+      delete state[key];
+    }
+  }
+};
+
+const terminalOrderAnalyticsSlice = createSlice({
+  name: 'terminalOrderAnalytics',
+  initialState,
+  reducers: {
+    markTerminalOrderAnalyticsEmittedEntry: (
+      state,
+      action: PayloadAction<string>,
+    ): void => {
+      const now = Date.now();
+      pruneExpiredEntries(state, now);
+      state[action.payload] = now;
+    },
+    clearTerminalOrderAnalyticsEntries: (): TerminalOrderAnalyticsState => ({}),
+  },
+});
+
+export const {
+  markTerminalOrderAnalyticsEmittedEntry,
+  clearTerminalOrderAnalyticsEntries,
+} = terminalOrderAnalyticsSlice.actions;
+
+export default terminalOrderAnalyticsSlice.reducer;

app/reducers/index.ts

@@ -47,6 +47,7 @@ import rewardsReducer, { RewardsState } from './rewards';
 import { isTestEnvironment } from '../util/test/utils';
 import attributionReducer from '../core/redux/slices/attribution';
 import headlessOrderContextsReducer from '../core/redux/slices/headlessOrderContexts';
+import terminalOrderAnalyticsReducer from '../core/redux/slices/terminalOrderAnalytics';
 
 /**
  * Infer state from a reducer
@@ -138,6 +139,7 @@ export interface RootState {
   networkConnectionBanner: NetworkConnectionBannerState;
   attribution: StateFromReducer<typeof attributionReducer>;
   headlessOrderContexts: StateFromReducer<typeof headlessOrderContextsReducer>;
+  terminalOrderAnalytics: StateFromReducer<typeof terminalOrderAnalyticsReducer>;
 }
 
 const baseReducers = {
@@ -196,6 +198,7 @@ const rootReducer = combineReducers<RootState, any>({
   ...baseReducers,
   attribution: attributionReducer,
   headlessOrderContexts: headlessOrderContextsReducer,
+  terminalOrderAnalytics: terminalOrderAnalyticsReducer,
 });
 
 export default rootReducer;

app/util/test/initial-root-state.ts

@@ -9,6 +9,7 @@ import { initialState as initialBridgeState } from '../../core/redux/slices/brid
 import { initialState as initialQrKeyringScannerState } from '../../core/redux/slices/qrKeyringScanner';
 import { initialState as initialCardState } from '../../core/redux/slices/card';
 import { initialState as initialMoneyBalanceState } from '../../core/redux/slices/moneyBalance';
+import { initialState as initialTerminalOrderAnalyticsState } from '../../core/redux/slices/terminalOrderAnalytics';
 import initialBackgroundState from './initial-background-state.json';
 import { userInitialState } from '../../reducers/user';
 import { initialNavigationState } from '../../reducers/navigation';
@@ -82,6 +83,7 @@ const initialRootState: RootState = {
     attribution: null,
   },
   headlessOrderContexts: {},
+  terminalOrderAnalytics: initialTerminalOrderAnalyticsState,
 };
 
 if (isTestEnvironment) {