fix: abstract member polling into swappable transport layer (#304)

codingLogan · web-flow · commit 623fc1270aa5 · 2026-03-26T14:45:28.000-06:00
diff --git a/GEMINI.md b/GEMINI.md
@@ -0,0 +1,61 @@
+# Connect Widget AI Context
+
+## Project Overview
+
+`@mxenabled/connect-widget` is a UI-only library for the Connect Widget, built with React and TypeScript. It provides the visual components and state management for the widget but relies on an external API and configuration provided by the consuming application to function.
+
+The library uses `ConnectWidget` as the main entry point and `ApiProvider` to inject the necessary API callbacks.
+
+**Core Technologies:**
+
+- **UI Framework:** React
+- **Language:** TypeScript
+- **State Management:** Redux Toolkit
+- **Build Tool:** Vite
+- **Testing:** Vitest
+- **(Old. Do not introduce more usage) Component Library:** Kyper UI (`@kyper/*`)
+
+## Building and Running
+
+The project relies on standard npm scripts for development, building, and testing:
+
+- **Install Dependencies:** `npm install`
+- **Development Build (Watch Mode):** `npm run dev`
+- **Production Build:** `npm run build`
+- **Run Tests:** `npm run test`
+- **Watch Tests:** `npm run watch`
+- **Lint Code:** `npm run lint`
+- **Link locally:** Use `npm link` in the root and then `npm link @mxenabled/connect-widget` in the consuming application to test local changes.
+
+## Development Conventions
+
+This repository has strict architectural, styling, and testing standards defined in the Architecture Decision Records (`architectureDecisionRecords/`). All new code must conform to these ADRs.
+
+### Architecture & Design
+
+- **Architecture Decision Records (ADRs):** Any significant technical choices should be documented as an ADR. Pull requests with new code that does not adhere to the agreed-upon ADRs will not be approved (exceptions for urgent hotfixes).
+- **Styling:** The project uses **CSS Modules** for styling. Do not use Tailwind CSS or other global CSS frameworks unless specifically working on existing legacy code that hasn't been migrated.
+
+### Testing
+
+- **Frameworks:** Use **Vitest** for unit and integration testing. **MSW (Mock Service Worker)** is the standard for API mocking in tests. **Cypress** is the standard for end-to-end tests.
+- **Philosophy:** Prefer integration tests over unit tests. Mock as little as possible. The primary goal of testing is to ensure that the frontend works properly with the backend and to provide confidence to deploy without manual testing.
+
+### Git & Version Control
+
+- **Conventional Commits:** All commit messages must follow the Conventional Commits specification to trigger semantic versioning releases properly.
+- You can use `npx cz` (Commitizen) to launch interactive prompts for formatting your commit message.
+  - `fix:` triggers a PATCH bump
+  - `feat:` triggers a MINOR bump
+  - `BREAKING CHANGE:` footer triggers a MAJOR bump.
+
+## Project Structure Highlights
+
+- `src/`: Contains all the source code for the widget.
+  - `components/`: React components.
+  - `redux/`: Redux actions, reducers, selectors, and store configuration.
+  - `context/`: React context providers (like `ApiContext`).
+  - `hooks/`: Custom React hooks.
+  - `views/`: Higher-level view components.
+- `docs/`: Extensive documentation on analytics, API requirements, client config, and user features.
+- `architectureDecisionRecords/`: Documentation of core engineering decisions (ADRs).
diff --git a/src/hooks/__tests__/usePollMember-test.tsx b/src/hooks/__tests__/usePollMember-test.tsx
@@ -1,37 +1,16 @@
 import React from 'react'
 import { renderHook, waitFor } from '@testing-library/react'
 import { vi } from 'vitest'
-import { usePollMember } from 'src/hooks/usePollMember'
-import { ApiProvider } from 'src/context/ApiContext'
+import { usePollMember, PollingState } from 'src/hooks/usePollMember'
+import { ApiProvider, ApiContextTypes } from 'src/context/ApiContext'
 import { Provider } from 'react-redux'
-import { createReduxStore } from 'src/redux/Store'
+import { createReduxStore, RootState } from 'src/redux/Store'
 import { member, JOB_DATA } from 'src/services/mockedData'
 import { ReadableStatuses } from 'src/const/Statuses'
 import { CONNECTING_MESSAGES } from 'src/utilities/pollers'
 import { take } from 'rxjs/operators'
 
-interface PollingState {
-  isError: boolean
-  pollingCount: number
-  currentResponse?: unknown
-  pollingIsDone: boolean
-  userMessage?: string
-  initialDataReady?: boolean
-}
-
-interface ApiValue {
-  loadMemberByGuid?: (guid: string, locale: string) => Promise<unknown>
-  loadJob?: (jobGuid: string) => Promise<unknown>
-}
-
-interface PreloadedState {
-  experimentalFeatures?: {
-    optOutOfEarlyUserRelease?: boolean
-    memberPollingMilliseconds?: number
-  }
-}
-
-const createWrapper = (apiValue: ApiValue, preloadedState?: PreloadedState) => {
+const createWrapper = (apiValue: Partial<ApiContextTypes>, preloadedState?: Partial<RootState>) => {
   const store = createReduxStore(preloadedState)
   const Wrapper = ({ children }: { children: React.ReactNode }) => (
     <Provider store={store}>
@@ -641,4 +620,105 @@ describe('usePollMember', () => {
 
     subscription.unsubscribe()
   }, 10000)
+
+  it('should correctly update previousResponse and currentResponse over multiple polls', async () => {
+    const member1 = { ...member.member, guid: 'MBR-1' }
+    const member2 = { ...member.member, guid: 'MBR-2' }
+
+    const apiValue = {
+      loadMemberByGuid: vi.fn().mockResolvedValueOnce(member1).mockResolvedValue(member2),
+      loadJob: vi.fn().mockResolvedValue(JOB_DATA),
+    }
+
+    const preloadedState = {
+      experimentalFeatures: {
+        memberPollingMilliseconds: 1000,
+      },
+    }
+
+    const { result } = renderHook(() => usePollMember(), {
+      wrapper: createWrapper(apiValue, preloadedState),
+    })
+
+    const pollMember = result.current
+    const states: PollingState[] = []
+
+    const subscription = pollMember('MBR-123')
+      .pipe(take(2))
+      .subscribe((state: PollingState) => {
+        states.push(state)
+      })
+
+    await waitFor(
+      () => {
+        expect(states.length).toBeGreaterThanOrEqual(2)
+      },
+      { timeout: 3500 },
+    )
+
+    // First poll
+    expect(states[0].previousResponse).toEqual({})
+    expect(states[0].currentResponse).toEqual({ member: member1, job: JOB_DATA })
+
+    // Second poll
+    expect(states[1].previousResponse).toEqual({ member: member1, job: JOB_DATA })
+    expect(states[1].currentResponse).toEqual({ member: member2, job: JOB_DATA })
+
+    subscription.unsubscribe()
+  }, 10000)
+
+  it('should preserve previousResponse and currentResponse when an intermediate poll fails', async () => {
+    const member1 = { ...member.member, guid: 'MBR-1' }
+
+    const apiValue = {
+      loadMemberByGuid: vi
+        .fn()
+        .mockResolvedValueOnce(member1)
+        .mockRejectedValueOnce(new Error('Intermediate Error'))
+        .mockResolvedValue(member1),
+      loadJob: vi.fn().mockResolvedValue(JOB_DATA),
+    }
+
+    const preloadedState = {
+      experimentalFeatures: {
+        memberPollingMilliseconds: 1000,
+      },
+    }
+
+    const { result } = renderHook(() => usePollMember(), {
+      wrapper: createWrapper(apiValue, preloadedState),
+    })
+
+    const pollMember = result.current
+    const states: PollingState[] = []
+
+    const subscription = pollMember('MBR-123')
+      .pipe(take(3))
+      .subscribe((state: PollingState) => {
+        states.push(state)
+      })
+
+    await waitFor(
+      () => {
+        expect(states.length).toBeGreaterThanOrEqual(3)
+      },
+      { timeout: 5000 },
+    )
+
+    // First poll: Success
+    expect(states[0].isError).toBe(false)
+    expect(states[0].currentResponse).toEqual({ member: member1, job: JOB_DATA })
+
+    // Second poll: Error
+    expect(states[1].isError).toBe(true)
+    expect(states[1].previousResponse).toEqual({}) // Should be preserved from acc
+    expect(states[1].currentResponse).toEqual({ member: member1, job: JOB_DATA }) // Should be preserved from acc
+
+    // Third poll: Success again
+    expect(states[2].isError).toBe(false)
+    expect(states[2].previousResponse).toEqual({ member: member1, job: JOB_DATA }) // acc.currentResponse was preserved
+    expect(states[2].currentResponse).toEqual({ member: member1, job: JOB_DATA })
+
+    subscription.unsubscribe()
+  }, 10000)
 })
diff --git a/src/hooks/usePollMember.tsx b/src/hooks/usePollMember.tsx
@@ -4,8 +4,21 @@ import { useApi } from 'src/context/ApiContext'
 import { useSelector } from 'react-redux'
 import { getExperimentalFeatures } from 'src/redux/reducers/experimentalFeaturesSlice'
 
-import { defer, interval, of } from 'rxjs'
-import { catchError, scan, map, mergeMap, exhaustMap } from 'rxjs/operators'
+import { scan } from 'rxjs/operators'
+import {
+  createMemberUpdateTransport,
+  MemberUpdate,
+} from 'src/utilities/transport/MemberUpdateTransport'
+
+export interface PollingState {
+  isError: boolean
+  pollingCount: number
+  currentResponse?: MemberUpdate | Record<string, never>
+  previousResponse?: MemberUpdate | Record<string, never>
+  pollingIsDone: boolean
+  userMessage?: string
+  initialDataReady?: boolean
+}
 
 export function usePollMember() {
   const { api } = useApi()
@@ -20,32 +33,28 @@ export function usePollMember() {
   const pollingInterval = memberPollingMilliseconds || 3000
 
   const pollMember = (memberGuid: string) => {
-    return interval(pollingInterval).pipe(
-      /**
-       * used to be switchMap
-       * exhaustMap ignores new emissions from the source while the current inner observable is still active.
-       *
-       * This ensures that we do not start a new poll request until the previous one has completed,
-       * preventing overlapping requests and potential race conditions.
-       */
-      exhaustMap(() =>
-        // Poll the currentMember. Catch errors but don't handle it here
-        // the scan will handle it below
-        // @ts-expect-error: cannot invoke a method that might be undefined
-        defer(() => api.loadMemberByGuid(memberGuid, clientLocale)).pipe(
-          mergeMap((member) =>
-            defer(() => api.loadJob(member.most_recent_job_guid as string)).pipe(
-              map((job) => ({ member, job })),
-            ),
-          ),
-          catchError((error) => of(error)),
-        ),
-      ),
+    const loadMemberByGuid =
+      api.loadMemberByGuid ||
+      (() => Promise.reject(new Error('api.loadMemberByGuid is required for member polling')))
+
+    const updateStream$ = createMemberUpdateTransport(
+      {
+        loadMemberByGuid,
+        loadJob: api.loadJob,
+      },
+      memberGuid,
+      {
+        pollingInterval,
+        clientLocale,
+      },
+    )
+
+    return updateStream$.pipe(
       scan(
-        (acc, response) => {
+        (acc: PollingState, response) => {
           const isError = response instanceof Error
 
-          const pollingState = {
+          const pollingState: PollingState = {
             // only track if the most recent poll was an error
             isError,
             // always increase polling count
@@ -56,11 +65,14 @@ export function usePollMember() {
             currentResponse: isError ? acc.currentResponse : response,
             // preserve the initialDataReadySent flag
             initialDataReady: acc.initialDataReady,
+            pollingIsDone: false,
+            userMessage: acc.userMessage,
           }
 
           if (
             !isError &&
             !acc.initialDataReady &&
+            // @ts-expect-error response might be undefined or an error
             response?.job?.async_account_data_ready &&
             !optOutOfEarlyUserRelease
           ) {
@@ -76,7 +88,7 @@ export function usePollMember() {
             userMessage: messageKey,
           }
         },
-        { ...DEFAULT_POLLING_STATE },
+        { ...DEFAULT_POLLING_STATE } as PollingState,
       ),
     )
   }
diff --git a/src/utilities/transport/MemberUpdateTransport.ts b/src/utilities/transport/MemberUpdateTransport.ts
@@ -0,0 +1,37 @@
+import { Observable, defer, interval, of } from 'rxjs'
+import { catchError, map, mergeMap, exhaustMap } from 'rxjs/operators'
+import type { ApiContextTypes } from 'src/context/ApiContext'
+
+type MemberUpdateApi = Required<Pick<ApiContextTypes, 'loadMemberByGuid' | 'loadJob'>>
+
+export interface MemberUpdate {
+  member?: MemberResponseType
+  job?: JobResponseType
+}
+
+export interface MemberUpdateTransportOptions {
+  pollingInterval?: number
+  clientLocale?: string
+}
+
+export function createMemberUpdateTransport(
+  api: MemberUpdateApi,
+  memberGuid: string,
+  options: MemberUpdateTransportOptions = {},
+): Observable<MemberUpdate | Error> {
+  const pollingInterval = options.pollingInterval || 3000
+  const clientLocale = options.clientLocale || 'en'
+
+  return interval(pollingInterval).pipe(
+    exhaustMap(() =>
+      defer(() => api.loadMemberByGuid(memberGuid, clientLocale)).pipe(
+        mergeMap((member: MemberResponseType) =>
+          defer(() =>
+            api.loadJob((member as { most_recent_job_guid: string }).most_recent_job_guid),
+          ).pipe(map((job: JobResponseType) => ({ member, job }))),
+        ),
+        catchError((error) => of(error)),
+      ),
+    ),
+  )
+}
diff --git a/src/utilities/transport/__tests__/MemberUpdateTransport-test.ts b/src/utilities/transport/__tests__/MemberUpdateTransport-test.ts
