@luxexchange/notifications 1.0.0

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

@@ -0,0 +1,177 @@
+import { type InAppNotification } from '@luxexchange/api'
+import { createNotificationDataSource } from '@luxexchange/notifications/src/notification-data-source/implementations/createNotificationDataSource'
+import { type NotificationDataSource } from '@luxexchange/notifications/src/notification-data-source/NotificationDataSource'
+import { type NotificationTracker } from '@luxexchange/notifications/src/notification-tracker/NotificationTracker'
+import { getLogger } from '@luxfi/utilities/src/logger/logger'
+
+/**
+ * Configuration for a single trigger condition.
+ * Each trigger represents a local notification that should be shown when conditions are met.
+ */
+export interface TriggerCondition {
+  /**
+   * Unique ID for this notification.
+   * Must use 'local:' prefix to distinguish from backend-generated notifications
+   * and prevent API tracker from trying to acknowledge them server-side.
+   */
+  id: string
+
+  /**
+   * Check if the notification should be shown now.
+   * Called on each poll interval.
+   */
+  shouldShow: () => boolean | Promise<boolean>
+
+  /**
+   * Create the notification object to be rendered.
+   * Only called when shouldShow returns true.
+   */
+  createNotification: () => InAppNotification
+
+  /**
+   * Optional callback when user acknowledges the notification.
+   * Use this to update Redux state or perform other side effects.
+   */
+  onAcknowledge?: () => void
+}
+
+export interface CreateLocalTriggerDataSourceContext {
+  /** Array of trigger conditions to evaluate */
+  triggers: TriggerCondition[]
+
+  /** Tracker for checking/storing processed state */
+  tracker: NotificationTracker
+
+  /** How often to check triggers in milliseconds (default: 5000ms) */
+  pollIntervalMs?: number
+
+  /** Source identifier for telemetry */
+  source?: string
+
+  /** File tag for logging */
+  logFileTag?: string
+}
+
+const DEFAULT_POLL_INTERVAL_MS = 5000
+const DEFAULT_SOURCE = 'local_triggers'
+const DEFAULT_LOG_FILE_TAG = 'createLocalTriggerDataSource'
+
+/**
+ * Creates a data source for condition-based local notifications.
+ *
+ * Unlike API-based data sources, this polls local state (e.g., Redux selectors)
+ * to determine when to show notifications. Useful for modals that should auto-open
+ * based on user state or behavior (e.g., app rating prompts, backup reminders).
+ *
+ * @example
+ * ```typescript
+ * const localTriggers = createLocalTriggerDataSource({
+ *   triggers: [
+ *     {
+ *       id: 'local:app_rating',
+ *       shouldShow: () => appRatingSelector(getState()).shouldPrompt,
+ *       createNotification: () => createAppRatingNotification(),
+ *       onAcknowledge: () => dispatch(setAppRating({})),
+ *     },
+ *   ],
+ *   tracker,
+ *   pollIntervalMs: 5000,
+ * })
+ * ```
+ */
+export function createLocalTriggerDataSource(ctx: CreateLocalTriggerDataSourceContext): NotificationDataSource {
+  const {
+    triggers,
+    tracker,
+    pollIntervalMs = DEFAULT_POLL_INTERVAL_MS,
+    source = DEFAULT_SOURCE,
+    logFileTag = DEFAULT_LOG_FILE_TAG,
+  } = ctx
+
+  let intervalId: ReturnType<typeof setInterval> | null = null
+  let currentCallback: ((notifications: InAppNotification[], source: string) => void) | null = null
+
+  const checkTriggers = async (): Promise<InAppNotification[]> => {
+    const notifications: InAppNotification[] = []
+
+    for (const trigger of triggers) {
+      try {
+        // Skip if already processed
+        const isProcessed = await tracker.isProcessed(trigger.id)
+        if (isProcessed) {
+          continue
+        }
+
+        // Check if trigger condition is met
+        const shouldShow = await Promise.resolve(trigger.shouldShow())
+        if (shouldShow) {
+          notifications.push(trigger.createNotification())
+        }
+      } catch (error) {
+        getLogger().error(error, {
+          tags: { file: logFileTag, function: 'checkTriggers' },
+          extra: { triggerId: trigger.id },
+        })
+      }
+    }
+
+    return notifications
+  }
+
+  const pollAndEmit = async (logFunctionTag: string): Promise<void> => {
+    if (!currentCallback) {
+      return
+    }
+
+    try {
+      const notifications = await checkTriggers()
+      currentCallback(notifications, source)
+    } catch (error) {
+      getLogger().error(error, {
+        tags: { file: logFileTag, function: logFunctionTag },
+      })
+    }
+  }
+
+  const start = (onNotifications: (notifications: InAppNotification[], source: string) => void): void => {
+    if (intervalId) {
+      return
+    }
+
+    currentCallback = onNotifications
+
+    // Check immediately on start
+    pollAndEmit('start').catch((error) => {
+      getLogger().error(error, {
+        tags: { file: logFileTag, function: 'start' },
+      })
+    })
+
+    // Then poll at interval
+    intervalId = setInterval(() => {
+      pollAndEmit('setInterval').catch((error) => {
+        getLogger().error(error, {
+          tags: { file: logFileTag, function: 'setInterval' },
+        })
+      })
+    }, pollIntervalMs)
+  }
+
+  const stop = async (): Promise<void> => {
+    if (intervalId) {
+      clearInterval(intervalId)
+      intervalId = null
+    }
+    currentCallback = null
+  }
+
+  return createNotificationDataSource({ start, stop })
+}
+
+/**
+ * Get a trigger by notification ID.
+ * Useful for finding the trigger's callbacks when a notification is interacted with.
+ */
+export function getTriggerById(triggers: TriggerCondition[], notificationId: string): TriggerCondition | undefined {
+  return triggers.find((t) => t.id === notificationId)
+}

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

@@ -0,0 +1,19 @@
+import { type InAppNotification } from '@luxfi/api'
+import { type NotificationDataSource } from '@luxfi/notifications/src/notification-data-source/NotificationDataSource'
+
+/**
+ * Basic implementation of the NotificationDataSource interface.
+ */
+export function createNotificationDataSource(ctx: {
+  start: (onNotifications: (notifications: InAppNotification[], source: string) => void) => void
+  stop: () => Promise<void>
+}): NotificationDataSource {
+  return {
+    start: (onNotifications: (notifications: InAppNotification[], source: string) => void): void => {
+      ctx.start(onNotifications)
+    },
+    stop: async (): Promise<void> => {
+      await ctx.stop()
+    },
+  }
+}

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 '@uniswap/client-notification-service/dist/uniswap/notificationservice/v1/api_pb'
+import type { InAppNotification, NotificationsApiClient } from '@luxexchange/api'
+import { ContentStyle } from '@luxexchange/api'
+import { getNotificationQueryOptions } from '@luxexchange/notifications/src/notification-data-source/getNotificationQueryOptions'
+import { createPollingNotificationDataSource } from '@luxexchange/notifications/src/notification-data-source/implementations/createPollingNotificationDataSource'
+import { ReactQueryCacheKey } from '@luxfi/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 '@luxfi/api'
+import { createNotificationDataSource } from '@luxfi/notifications/src/notification-data-source/implementations/createNotificationDataSource'
+import { type NotificationDataSource } from '@luxfi/notifications/src/notification-data-source/NotificationDataSource'
+import { getLogger } from '@luxfi/utilities/src/logger/logger'
+import { type QueryOptionsResult } from '@luxfi/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 })
+}