@l.x/notifications 1.0.3 → 1.0.5

package/src/notification-data-source/implementations/createPollingNotificationDataSource.test.ts

@@ -0,0 +1,398 @@
+import { QueryClient } from '@tanstack/react-query'
+import {
+  Content,
+  GetNotificationsResponse,
+  Metadata,
+  Notification,
+  PlatformType,
+} from '@luxamm/client-notification-service/dist/lx/notificationservice/v1/api_pb'
+import type { InAppNotification, NotificationsApiClient } from '@l.x/api'
+import { ContentStyle } from '@l.x/api'
+import { getNotificationQueryOptions } from '@l.x/notifications/src/notification-data-source/getNotificationQueryOptions'
+import { createPollingNotificationDataSource } from '@l.x/notifications/src/notification-data-source/implementations/createPollingNotificationDataSource'
+import { ReactQueryCacheKey } from 'utilities/src/reactQuery/cache'
+import { afterEach, beforeEach, describe, expect, it, type Mock, vi } from 'vitest'
+
+function createMockNotification(id: string): InAppNotification {
+  return new Notification({
+    id,
+    metadata: new Metadata({ owner: 'foo', business: 'bar' }),
+    content: new Content({ style: ContentStyle.MODAL, title: 'Hello' }),
+  })
+}
+
+describe('createPollingNotificationDataSource', () => {
+  let queryClient: QueryClient
+  let mockApiClient: NotificationsApiClient
+  let mockNotifications: InAppNotification[]
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    queryClient = new QueryClient()
+
+    mockNotifications = [createMockNotification('1'), createMockNotification('2')]
+
+    mockApiClient = {
+      getNotifications: vi.fn().mockResolvedValue(new GetNotificationsResponse({ notifications: mockNotifications })),
+      ackNotification: vi.fn().mockResolvedValue(undefined),
+    }
+  })
+
+  afterEach(() => {
+    queryClient.clear()
+  })
+
+  it('creates a notification data source with start and stop methods', () => {
+    const testQueryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    })
+
+    const dataSource = createPollingNotificationDataSource({
+      queryClient: testQueryClient,
+      queryOptions: getNotificationQueryOptions({
+        apiClient: mockApiClient,
+        getPlatformType: () => PlatformType.WEB,
+      }),
+    })
+
+    expect(dataSource).toBeDefined()
+    expect(typeof dataSource.start).toBe('function')
+    expect(typeof dataSource.stop).toBe('function')
+  })
+
+  it('calls onNotifications when notifications are received', async () => {
+    const testQueryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    })
+
+    const dataSource = createPollingNotificationDataSource({
+      queryClient: testQueryClient,
+      queryOptions: getNotificationQueryOptions({
+        apiClient: mockApiClient,
+        getPlatformType: () => PlatformType.WEB,
+      }),
+    })
+
+    const onNotifications = vi.fn()
+    dataSource.start(onNotifications)
+
+    // Wait for the query to resolve
+    await vi.waitFor(() => {
+      expect(onNotifications).toHaveBeenCalledWith(mockNotifications, 'polling_api')
+    })
+
+    await dataSource.stop()
+  })
+
+  it('calls apiClient.getNotifications when started', async () => {
+    const testQueryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    })
+
+    const dataSource = createPollingNotificationDataSource({
+      queryClient: testQueryClient,
+      queryOptions: getNotificationQueryOptions({
+        apiClient: mockApiClient,
+        getPlatformType: () => PlatformType.WEB,
+      }),
+    })
+
+    const onNotifications = vi.fn()
+    dataSource.start(onNotifications)
+
+    await vi.waitFor(() => {
+      expect(mockApiClient.getNotifications).toHaveBeenCalled()
+    })
+
+    await dataSource.stop()
+  })
+
+  it.each([
+    ['WEB', PlatformType.WEB],
+    ['MOBILE', PlatformType.MOBILE],
+    ['EXTENSION', PlatformType.EXTENSION],
+  ] as const)(
+    'calls apiClient.getNotifications with platform_type %s when getPlatformType returns that platform',
+    async (_label, platformType) => {
+      const testQueryClient = new QueryClient({
+        defaultOptions: { queries: { retry: false } },
+      })
+
+      const dataSource = createPollingNotificationDataSource({
+        queryClient: testQueryClient,
+        queryOptions: getNotificationQueryOptions({
+          apiClient: mockApiClient,
+          getPlatformType: () => platformType,
+        }),
+      })
+
+      const onNotifications = vi.fn()
+      dataSource.start(onNotifications)
+
+      await vi.waitFor(() => {
+        expect(mockApiClient.getNotifications).toHaveBeenCalledWith({ platform_type: platformType })
+      })
+
+      await dataSource.stop()
+    },
+  )
+
+  it('does not start twice if already active', async () => {
+    const testQueryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    })
+
+    const dataSource = createPollingNotificationDataSource({
+      queryClient: testQueryClient,
+      queryOptions: getNotificationQueryOptions({
+        apiClient: mockApiClient,
+        getPlatformType: () => PlatformType.WEB,
+      }),
+    })
+
+    const onNotifications = vi.fn()
+    dataSource.start(onNotifications)
+
+    // Try to start again
+    dataSource.start(onNotifications)
+
+    // Wait a bit to ensure no double calls
+    await vi.waitFor(() => {
+      expect(mockApiClient.getNotifications).toHaveBeenCalledTimes(1)
+    })
+
+    await dataSource.stop()
+  })
+
+  it('handles API errors gracefully', async () => {
+    const testQueryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    })
+
+    const error = new Error('API Error')
+    mockApiClient.getNotifications = vi.fn().mockRejectedValue(error)
+
+    const dataSource = createPollingNotificationDataSource({
+      queryClient: testQueryClient,
+      queryOptions: getNotificationQueryOptions({
+        apiClient: mockApiClient,
+        getPlatformType: () => PlatformType.WEB,
+      }),
+    })
+
+    const onNotifications = vi.fn()
+    dataSource.start(onNotifications)
+
+    // Wait for error handling
+    await vi.waitFor(() => {
+      expect(mockApiClient.getNotifications).toHaveBeenCalled()
+    })
+
+    // onNotifications should not be called on error
+    expect(onNotifications).not.toHaveBeenCalled()
+
+    await dataSource.stop()
+  })
+
+  it('stops polling when stop is called', async () => {
+    const testQueryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    })
+
+    const dataSource = createPollingNotificationDataSource({
+      queryClient: testQueryClient,
+      queryOptions: getNotificationQueryOptions({
+        apiClient: mockApiClient,
+        getPlatformType: () => PlatformType.WEB,
+        pollIntervalMs: 100, // Short interval for testing
+      }),
+    })
+
+    const onNotifications = vi.fn()
+    dataSource.start(onNotifications)
+
+    await vi.waitFor(() => {
+      expect(onNotifications).toHaveBeenCalled()
+    })
+
+    const callCountBeforeStop = (mockApiClient.getNotifications as Mock).mock.calls.length
+
+    await dataSource.stop()
+
+    // Wait a bit longer than poll interval
+    await new Promise((resolve) => setTimeout(resolve, 200))
+
+    // Should not have made additional API calls after stop
+    expect((mockApiClient.getNotifications as Mock).mock.calls.length).toBe(callCountBeforeStop)
+  })
+
+  it('can be started again after stopping', async () => {
+    const testQueryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    })
+
+    const dataSource = createPollingNotificationDataSource({
+      queryClient: testQueryClient,
+      queryOptions: getNotificationQueryOptions({
+        apiClient: mockApiClient,
+        getPlatformType: () => PlatformType.WEB,
+      }),
+    })
+
+    const onNotifications = vi.fn()
+
+    // Start, wait, then stop
+    dataSource.start(onNotifications)
+    await vi.waitFor(() => {
+      expect(onNotifications).toHaveBeenCalledWith(mockNotifications, 'polling_api')
+    })
+    await dataSource.stop()
+
+    // Wait a bit for cleanup to complete
+    await new Promise((resolve) => setTimeout(resolve, 50))
+
+    // Clear the query cache completely
+    testQueryClient.clear()
+
+    // Clear mocks
+    vi.clearAllMocks()
+    mockApiClient.getNotifications = vi
+      .fn()
+      .mockResolvedValue(new GetNotificationsResponse({ notifications: mockNotifications }))
+
+    // Start again with a new callback
+    const onNotifications2 = vi.fn()
+    dataSource.start(onNotifications2)
+    await vi.waitFor(() => {
+      expect(onNotifications2).toHaveBeenCalled()
+    })
+
+    await dataSource.stop()
+  })
+
+  it('uses custom poll interval when provided', async () => {
+    const testQueryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    })
+
+    const customPollInterval = 100
+    const dataSource = createPollingNotificationDataSource({
+      queryClient: testQueryClient,
+      queryOptions: getNotificationQueryOptions({
+        apiClient: mockApiClient,
+        getPlatformType: () => PlatformType.WEB,
+        pollIntervalMs: customPollInterval,
+      }),
+    })
+
+    const onNotifications = vi.fn()
+    dataSource.start(onNotifications)
+
+    // Wait for initial call
+    await vi.waitFor(() => {
+      expect(mockApiClient.getNotifications).toHaveBeenCalled()
+    })
+
+    // Verify the data source was created successfully with custom interval
+    // Note: Testing actual polling behavior is complex due to React Query's internal timing
+    // The main goal is to ensure the custom interval is accepted without errors
+    expect(dataSource).toBeDefined()
+    expect(typeof dataSource.start).toBe('function')
+    expect(typeof dataSource.stop).toBe('function')
+
+    await dataSource.stop()
+  })
+
+  it('passes empty array to onNotifications when API returns empty array', async () => {
+    const testQueryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    })
+
+    mockApiClient.getNotifications = vi.fn().mockResolvedValue(new GetNotificationsResponse({ notifications: [] }))
+
+    const dataSource = createPollingNotificationDataSource({
+      queryClient: testQueryClient,
+      queryOptions: getNotificationQueryOptions({
+        apiClient: mockApiClient,
+        getPlatformType: () => PlatformType.WEB,
+      }),
+    })
+
+    const onNotifications = vi.fn()
+    dataSource.start(onNotifications)
+
+    await vi.waitFor(() => {
+      expect(onNotifications).toHaveBeenCalledWith([], 'polling_api')
+    })
+
+    await dataSource.stop()
+  })
+
+  it('cancels queries when stopped', async () => {
+    const testQueryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    })
+
+    const dataSource = createPollingNotificationDataSource({
+      queryClient: testQueryClient,
+      queryOptions: getNotificationQueryOptions({
+        apiClient: mockApiClient,
+        getPlatformType: () => PlatformType.WEB,
+      }),
+    })
+
+    const cancelQueriesSpy = vi.spyOn(testQueryClient, 'cancelQueries')
+
+    const onNotifications = vi.fn()
+    dataSource.start(onNotifications)
+
+    await vi.waitFor(() => {
+      expect(onNotifications).toHaveBeenCalled()
+    })
+
+    await dataSource.stop()
+
+    expect(cancelQueriesSpy).toHaveBeenCalledWith({ queryKey: [ReactQueryCacheKey.Notifications] })
+
+    cancelQueriesSpy.mockRestore()
+  })
+
+  it('retries failed requests according to retry configuration', async () => {
+    let callCount = 0
+    mockApiClient.getNotifications = vi.fn().mockImplementation(() => {
+      callCount++
+      if (callCount <= 2) {
+        return Promise.reject(new Error('Temporary error'))
+      }
+      return Promise.resolve(new GetNotificationsResponse({ notifications: mockNotifications }))
+    })
+
+    // Create a fresh QueryClient to test actual retry behavior from queryOptions
+    const retryQueryClient = new QueryClient()
+
+    const dataSource = createPollingNotificationDataSource({
+      queryClient: retryQueryClient,
+      queryOptions: getNotificationQueryOptions({
+        apiClient: mockApiClient,
+        getPlatformType: () => PlatformType.WEB,
+      }),
+    })
+
+    const onNotifications = vi.fn()
+    dataSource.start(onNotifications)
+
+    // Should eventually succeed after retries
+    await vi.waitFor(
+      () => {
+        expect(onNotifications).toHaveBeenCalled()
+      },
+      { timeout: 10000 },
+    )
+
+    // Should have made multiple attempts (initial + 2 retries)
+    expect(callCount).toBe(3)
+
+    await dataSource.stop()
+    retryQueryClient.clear()
+  })
+})

package/src/notification-data-source/implementations/createPollingNotificationDataSource.ts

@@ -0,0 +1,74 @@
+import { type QueryClient, type QueryKey, QueryObserver } from '@tanstack/react-query'
+import { type InAppNotification } from '@l.x/api'
+import { createNotificationDataSource } from '@l.x/notifications/src/notification-data-source/implementations/createNotificationDataSource'
+import { type NotificationDataSource } from '@l.x/notifications/src/notification-data-source/NotificationDataSource'
+import { getLogger } from 'utilities/src/logger/logger'
+import { type QueryOptionsResult } from 'utilities/src/reactQuery/queryOptions'
+
+interface CreatePollingNotificationDataSourceContext<TQueryKey extends QueryKey = QueryKey> {
+  queryClient: QueryClient
+  queryOptions: QueryOptionsResult<InAppNotification[], Error, InAppNotification[], TQueryKey>
+}
+
+/**
+ * Creates a polling notification data source using React Query.
+ * This handles the lifecycle orchestration of the query (start/stop).
+ */
+export function createPollingNotificationDataSource<TQueryKey extends QueryKey = QueryKey>(
+  ctx: CreatePollingNotificationDataSourceContext<TQueryKey>,
+): NotificationDataSource {
+  const { queryClient, queryOptions } = ctx
+
+  let observer: QueryObserver<InAppNotification[], Error, InAppNotification[], InAppNotification[], TQueryKey> | null =
+    null
+  let unsubscribe: (() => void) | null = null
+  let isActive = false
+
+  const start = async (
+    onNotifications: (notifications: InAppNotification[], source: string) => void,
+  ): Promise<void> => {
+    if (isActive) {
+      return // Prevent multiple starts
+    }
+
+    isActive = true
+
+    observer = new QueryObserver<InAppNotification[], Error, InAppNotification[], InAppNotification[], TQueryKey>(
+      queryClient,
+      queryOptions,
+    )
+
+    unsubscribe = observer.subscribe((result) => {
+      // Only trigger callback when we have successful data
+      // Check both result.data exists AND status is success to avoid partial states
+      if (result.data && result.status === 'success') {
+        onNotifications(result.data, 'polling_api')
+      } else if (result.error) {
+        getLogger().error(result.error, {
+          tags: { file: 'createPollingNotificationDataSource', function: 'subscribe' },
+        })
+      }
+    })
+  }
+
+  const stop = async (): Promise<void> => {
+    if (unsubscribe) {
+      unsubscribe()
+      unsubscribe = null
+    }
+
+    observer = null
+
+    try {
+      await queryClient.cancelQueries({ queryKey: queryOptions.queryKey })
+    } catch (error) {
+      getLogger().error(error, {
+        tags: { file: 'createPollingNotificationDataSource', function: 'stop' },
+      })
+    } finally {
+      isActive = false
+    }
+  }
+
+  return createNotificationDataSource({ start, stop })
+}

package/src/notification-data-source/implementations/createReactiveDataSource.ts

@@ -0,0 +1,113 @@
+import { type InAppNotification } from '@l.x/api'
+import { createNotificationDataSource } from '@l.x/notifications/src/notification-data-source/implementations/createNotificationDataSource'
+import { type NotificationDataSource } from '@l.x/notifications/src/notification-data-source/NotificationDataSource'
+import { type ReactiveCondition } from '@l.x/notifications/src/notification-data-source/types/ReactiveCondition'
+import { type NotificationTracker } from '@l.x/notifications/src/notification-tracker/NotificationTracker'
+import { getLogger } from 'utilities/src/logger/logger'
+
+export interface CreateReactiveDataSourceContext<TState> {
+  /** The reactive condition that determines when to show the notification */
+  condition: ReactiveCondition<TState>
+
+  /** Tracker for checking/storing processed state */
+  tracker: NotificationTracker
+
+  /** Source identifier for telemetry (default: 'reactive') */
+  source?: string
+
+  /** File tag for logging (default: 'createReactiveDataSource') */
+  logFileTag?: string
+}
+
+const DEFAULT_SOURCE = 'reactive'
+const DEFAULT_LOG_FILE_TAG = 'createReactiveDataSource'
+
+/**
+ * Creates a data source for reactive, state-driven notifications.
+ *
+ * Unlike polling-based data sources, this subscribes to state changes and
+ * immediately re-evaluates whether to show/hide the notification. The notification
+ * is emitted when shouldShow returns true and removed when it returns false.
+ *
+ * Key behaviors:
+ * - Subscribes to condition's state changes on start()
+ * - When state changes, checks shouldShow(state)
+ * - Emits [notification] when shouldShow is true and not already processed
+ * - Emits [] when shouldShow is false (hides the notification)
+ * - Checks tracker.isProcessed to prevent showing dismissed notifications
+ *
+ * @example
+ * ```typescript
+ * const offlineDataSource = createReactiveDataSource({
+ *   condition: createOfflineCondition({ getState }),
+ *   tracker,
+ * })
+ *
+ * notificationService.registerDataSource(offlineDataSource)
+ * ```
+ */
+export function createReactiveDataSource<TState>(ctx: CreateReactiveDataSourceContext<TState>): NotificationDataSource {
+  const { condition, tracker, source = DEFAULT_SOURCE, logFileTag = DEFAULT_LOG_FILE_TAG } = ctx
+
+  let unsubscribe: (() => void) | null = null
+  let currentCallback: ((notifications: InAppNotification[], source: string) => void) | null = null
+
+  const emitNotifications = async (state: TState): Promise<void> => {
+    if (!currentCallback) {
+      return
+    }
+
+    try {
+      // Check if notification was already dismissed/processed
+      const isProcessed = await tracker.isProcessed(condition.notificationId)
+      if (isProcessed) {
+        // Already dismissed, emit empty array
+        currentCallback([], source)
+        return
+      }
+
+      // Evaluate the condition
+      const shouldShow = condition.shouldShow(state)
+
+      if (shouldShow) {
+        const notification = condition.createNotification(state)
+        currentCallback([notification], source)
+      } else {
+        // Condition not met, emit empty array to hide
+        currentCallback([], source)
+      }
+    } catch (error) {
+      getLogger().error(error, {
+        tags: { file: logFileTag, function: 'emitNotifications' },
+        extra: { notificationId: condition.notificationId },
+      })
+    }
+  }
+
+  const start = (onNotifications: (notifications: InAppNotification[], source: string) => void): void => {
+    if (unsubscribe) {
+      return
+    }
+
+    currentCallback = onNotifications
+
+    // Subscribe to state changes
+    unsubscribe = condition.subscribe((state: TState) => {
+      emitNotifications(state).catch((error) => {
+        getLogger().error(error, {
+          tags: { file: logFileTag, function: 'subscribe' },
+        })
+      })
+    })
+  }
+
+  const stop = async (): Promise<void> => {
+    if (unsubscribe) {
+      unsubscribe()
+      unsubscribe = null
+    }
+    currentCallback = null
+  }
+
+  return createNotificationDataSource({ start, stop })
+}

package/src/notification-data-source/types/ReactiveCondition.ts

@@ -0,0 +1,60 @@
+import { type InAppNotification } from '@l.x/api'
+
+/**
+ * A reactive condition for state-driven notifications.
+ *
+ * Unlike polling-based TriggerCondition, ReactiveCondition uses push-based updates
+ * via a subscribe mechanism. The data source subscribes to state changes and
+ * immediately re-evaluates whether to show/hide the notification.
+ *
+ * This is ideal for conditions that:
+ * - Need instant response to state changes (e.g., network status)
+ * - Already have observable state (e.g., NetInfo, Redux store subscriptions)
+ * - Should show/hide without polling delay
+ *
+ * @template TState - The shape of the state that drives the condition
+ *
+ * @example
+ * ```typescript
+ * const offlineCondition: ReactiveCondition<OfflineState> = {
+ *   notificationId: 'local:session:offline',
+ *   subscribe: (onStateChange) => {
+ *     return NetInfo.addEventListener((state) => {
+ *       onStateChange({ isConnected: state.isConnected })
+ *     })
+ *   },
+ *   shouldShow: (state) => state.isConnected === false,
+ *   createNotification: (state) => new Notification({ ... })
+ * }
+ * ```
+ */
+export interface ReactiveCondition<TState> {
+  /**
+   * Unique notification ID.
+   * Must use 'local:' prefix to distinguish from backend-generated notifications.
+   * Use 'local:session:' prefix for session-scoped notifications that reset on app restart.
+   */
+  notificationId: string
+
+  /**
+   * Subscribe to state changes.
+   * @param onStateChange - Callback to invoke when state changes
+   * @returns Unsubscribe function to stop receiving updates
+   */
+  subscribe: (onStateChange: (state: TState) => void) => () => void
+
+  /**
+   * Check if the notification should be shown based on current state.
+   * @param state - The current state
+   * @returns true if the notification should be visible
+   */
+  shouldShow: (state: TState) => boolean
+
+  /**
+   * Create the notification object to be rendered.
+   * Called when shouldShow returns true.
+   * @param state - The current state (may be useful for dynamic notification content)
+   * @returns The notification to display
+   */
+  createNotification: (state: TState) => InAppNotification
+}

package/src/notification-processor/NotificationProcessor.ts

@@ -0,0 +1,26 @@
+import { type InAppNotification } from '@l.x/api'
+
+/**
+ * Result of processing notifications, separating primary notifications
+ * from chained notifications that should be shown later
+ */
+export interface NotificationProcessorResult {
+  /**
+   * Primary notifications that should be rendered immediately
+   */
+  primary: InAppNotification[]
+
+  /**
+   * Chained notifications that should be stored for later triggering
+   */
+  chained: Map<string, InAppNotification>
+}
+
+export interface NotificationProcessor {
+  /**
+   * Process incoming notifications against current state
+   * Separates primary notifications (to be shown immediately) from chained notifications
+   * (to be shown when triggered by another notification's POPUP action)
+   */
+  process(notifications: InAppNotification[]): Promise<NotificationProcessorResult>
+}