diff --git a/GEMINI.md b/GEMINI.md new file mode 100644 index 0000000000..c804d3b20d --- /dev/null +++ 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 index df85432d29..41869a1fda 100644 --- 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 - loadJob?: (jobGuid: string) => Promise -} - -interface PreloadedState { - experimentalFeatures?: { - optOutOfEarlyUserRelease?: boolean - memberPollingMilliseconds?: number - } -} - -const createWrapper = (apiValue: ApiValue, preloadedState?: PreloadedState) => { +const createWrapper = (apiValue: Partial, preloadedState?: Partial) => { const store = createReduxStore(preloadedState) const Wrapper = ({ children }: { children: React.ReactNode }) => ( @@ -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 index d3fbb4bc96..9c571569da 100644 --- 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 + previousResponse?: MemberUpdate | Record + 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 new file mode 100644 index 0000000000..e81d7fc63b --- /dev/null +++ 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> + +export interface MemberUpdate { + member?: MemberResponseType + job?: JobResponseType +} + +export interface MemberUpdateTransportOptions { + pollingInterval?: number + clientLocale?: string +} + +export function createMemberUpdateTransport( + api: MemberUpdateApi, + memberGuid: string, + options: MemberUpdateTransportOptions = {}, +): Observable { + 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 new file mode 100644 index 0000000000..32e9e59584 --- /dev/null +++ b/src/utilities/transport/__tests__/MemberUpdateTransport-test.ts @@ -0,0 +1,137 @@ +import { vi } from 'vitest' +import { take } from 'rxjs/operators' +import { createMemberUpdateTransport, MemberUpdate } from '../MemberUpdateTransport' + +describe('MemberUpdateTransport', () => { + const mockMemberGuid = 'MBR-123' + const mockClientLocale = 'en' + const mockMember = { most_recent_job_guid: 'JOB-123', guid: mockMemberGuid } + const mockJob = { guid: 'JOB-123', status: 'COMPLETED' } + + let mockApi: { + loadMemberByGuid: ReturnType + loadJob: ReturnType + } + + beforeEach(() => { + vi.useFakeTimers() + mockApi = { + loadMemberByGuid: vi.fn().mockResolvedValue(mockMember), + loadJob: vi.fn().mockResolvedValue(mockJob), + } + }) + + afterEach(() => { + vi.restoreAllMocks() + }) + + it('should emit a member and job update after the polling interval', async () => { + const transport$ = createMemberUpdateTransport(mockApi, mockMemberGuid, { + pollingInterval: 1000, + clientLocale: mockClientLocale, + }) + + const results: (MemberUpdate | Error)[] = [] + + const subscription = transport$.pipe(take(1)).subscribe((val) => { + results.push(val) + }) + + // Fast-forward past the first interval + await vi.advanceTimersByTimeAsync(1000) + + expect(mockApi.loadMemberByGuid).toHaveBeenCalledWith(mockMemberGuid, mockClientLocale) + expect(mockApi.loadJob).toHaveBeenCalledWith('JOB-123') + expect(results).toEqual([{ member: mockMember, job: mockJob }]) + + subscription.unsubscribe() + }) + + it('should continue emitting updates on each interval', async () => { + const transport$ = createMemberUpdateTransport(mockApi, mockMemberGuid, { + pollingInterval: 1000, + clientLocale: mockClientLocale, + }) + + const results: (MemberUpdate | Error)[] = [] + + const subscription = transport$.subscribe((val) => { + results.push(val) + }) + + // Fast-forward 3 intervals + await vi.advanceTimersByTimeAsync(3000) + + expect(mockApi.loadMemberByGuid).toHaveBeenCalledTimes(3) + expect(mockApi.loadJob).toHaveBeenCalledTimes(3) + expect(results).toHaveLength(3) + + subscription.unsubscribe() + }) + + it('should emit an error if loadMemberByGuid fails', async () => { + const error = new Error('Network error loading member') + mockApi.loadMemberByGuid.mockRejectedValue(error) + + const transport$ = createMemberUpdateTransport(mockApi, mockMemberGuid, { + pollingInterval: 1000, + clientLocale: mockClientLocale, + }) + + const results: (MemberUpdate | Error)[] = [] + + const subscription = transport$.pipe(take(1)).subscribe((val) => { + results.push(val) + }) + + await vi.advanceTimersByTimeAsync(1000) + + expect(mockApi.loadMemberByGuid).toHaveBeenCalledWith(mockMemberGuid, mockClientLocale) + expect(mockApi.loadJob).not.toHaveBeenCalled() // Should not be called if member fails + expect(results).toEqual([error]) + + subscription.unsubscribe() + }) + + it('should emit an error if loadJob fails', async () => { + const error = new Error('Network error loading job') + mockApi.loadJob.mockRejectedValue(error) + + const transport$ = createMemberUpdateTransport(mockApi, mockMemberGuid, { + pollingInterval: 1000, + clientLocale: mockClientLocale, + }) + + const results: (MemberUpdate | Error)[] = [] + + const subscription = transport$.pipe(take(1)).subscribe((val) => { + results.push(val) + }) + + await vi.advanceTimersByTimeAsync(1000) + + expect(mockApi.loadMemberByGuid).toHaveBeenCalledWith(mockMemberGuid, mockClientLocale) + expect(mockApi.loadJob).toHaveBeenCalledWith('JOB-123') + expect(results).toEqual([error]) + + subscription.unsubscribe() + }) + + it('should use default options if not provided', async () => { + const transport$ = createMemberUpdateTransport(mockApi, mockMemberGuid) + + const results: (MemberUpdate | Error)[] = [] + + const subscription = transport$.pipe(take(1)).subscribe((val) => { + results.push(val) + }) + + // Default interval is 3000 + await vi.advanceTimersByTimeAsync(3000) + + expect(mockApi.loadMemberByGuid).toHaveBeenCalledWith(mockMemberGuid, 'en') + expect(results).toHaveLength(1) + + subscription.unsubscribe() + }) +})