@luxexchange/notifications 1.0.0

package/src/notification-tracker/implementations/createApiNotificationTracker.test.ts

@@ -0,0 +1,465 @@
+import type { QueryClient } from '@tanstack/react-query'
+import type { NotificationsApiClient } from '@luxfi/api'
+import { createApiNotificationTracker } from '@luxfi/notifications/src/notification-tracker/implementations/createApiNotificationTracker'
+import type { TrackingMetadata } from '@luxfi/notifications/src/notification-tracker/NotificationTracker'
+import { describe, expect, it, type Mock, vi } from 'vitest'
+
+describe('createApiNotificationTracker', () => {
+  const createMockApiClient = (): NotificationsApiClient =>
+    ({
+      ackNotification: vi.fn().mockResolvedValue(undefined),
+    }) as unknown as NotificationsApiClient
+
+  const createMockQueryClient = (): QueryClient =>
+    ({
+      fetchQuery: vi.fn((options) => options.queryFn()),
+    }) as unknown as QueryClient
+
+  const createMockStorage = (): {
+    has: Mock<(notificationId: string) => Promise<boolean>>
+    add: Mock<(notificationId: string, metadata?: { timestamp: number }) => Promise<void>>
+    getAll: Mock<() => Promise<Set<string>>>
+    deleteOlderThan: Mock<(timestamp: number) => Promise<void>>
+  } => ({
+    has: vi.fn().mockResolvedValue(false),
+    add: vi.fn().mockResolvedValue(undefined),
+    getAll: vi.fn().mockResolvedValue(new Set<string>()),
+    deleteOlderThan: vi.fn().mockResolvedValue(undefined),
+  })
+
+  const mockMetadata: TrackingMetadata = {
+    timestamp: Date.now(),
+  }
+
+  describe('isProcessed', () => {
+    it('returns true when storage has the notification', async () => {
+      const mockApiClient = createMockApiClient()
+      const mockStorage = createMockStorage()
+      mockStorage.has.mockResolvedValue(true)
+
+      const tracker = createApiNotificationTracker({
+        notificationsApiClient: mockApiClient,
+        queryClient: createMockQueryClient(),
+        storage: mockStorage,
+      })
+
+      const result = await tracker.isProcessed('notif-1')
+
+      expect(result).toBe(true)
+      expect(mockStorage.has).toHaveBeenCalledWith('notif-1')
+    })
+
+    it('returns false when storage does not have the notification', async () => {
+      const mockApiClient = createMockApiClient()
+      const mockStorage = createMockStorage()
+      mockStorage.has.mockResolvedValue(false)
+
+      const tracker = createApiNotificationTracker({
+        notificationsApiClient: mockApiClient,
+        queryClient: createMockQueryClient(),
+        storage: mockStorage,
+      })
+
+      const result = await tracker.isProcessed('notif-1')
+
+      expect(result).toBe(false)
+      expect(mockStorage.has).toHaveBeenCalledWith('notif-1')
+    })
+  })
+
+  describe('getProcessedIds', () => {
+    it('returns all IDs from storage when storage is provided', async () => {
+      const mockApiClient = createMockApiClient()
+      const mockStorage = createMockStorage()
+      const expectedIds = new Set(['notif-1', 'notif-2', 'notif-3'])
+      mockStorage.getAll.mockResolvedValue(expectedIds)
+
+      const tracker = createApiNotificationTracker({
+        notificationsApiClient: mockApiClient,
+        queryClient: createMockQueryClient(),
+        storage: mockStorage,
+      })
+
+      const result = await tracker.getProcessedIds()
+
+      expect(result).toBe(expectedIds)
+      expect(mockStorage.getAll).toHaveBeenCalled()
+    })
+  })
+
+  describe('track', () => {
+    it('calls API and updates storage on successful acknowledgment', async () => {
+      const mockApiClient = createMockApiClient()
+      const mockStorage = createMockStorage()
+
+      const tracker = createApiNotificationTracker({
+        notificationsApiClient: mockApiClient,
+        queryClient: createMockQueryClient(),
+        storage: mockStorage,
+      })
+
+      await tracker.track('notif-1', mockMetadata)
+
+      expect(mockApiClient.ackNotification).toHaveBeenCalledWith({
+        ids: ['notif-1'],
+      })
+      expect(mockStorage.add).toHaveBeenCalledWith('notif-1', {
+        timestamp: mockMetadata.timestamp,
+      })
+    })
+
+    it('updates storage and logs error when API call fails', async () => {
+      const mockApiClient = createMockApiClient()
+      const mockStorage = createMockStorage()
+      const apiError = new Error('API request failed')
+      mockApiClient.ackNotification = vi.fn().mockRejectedValue(apiError)
+
+      const tracker = createApiNotificationTracker({
+        notificationsApiClient: mockApiClient,
+        queryClient: createMockQueryClient(),
+        storage: mockStorage,
+      })
+
+      // Should not throw - errors are caught and logged
+      await expect(tracker.track('notif-1', mockMetadata)).resolves.not.toThrow()
+
+      // Verify storage was still updated despite API failure
+      expect(mockStorage.add).toHaveBeenCalledWith('notif-1', {
+        timestamp: mockMetadata.timestamp,
+      })
+    })
+
+    it('logs error when API fails and no storage provided', async () => {
+      const mockApiClient = createMockApiClient()
+      const apiError = new Error('Network error')
+      mockApiClient.ackNotification = vi.fn().mockRejectedValue(apiError)
+
+      const tracker = createApiNotificationTracker({
+        notificationsApiClient: mockApiClient,
+        storage: createMockStorage(),
+      })
+
+      // Should not throw - errors are caught and logged
+      await expect(tracker.track('notif-1', mockMetadata)).resolves.not.toThrow()
+    })
+
+    it('calls API and updates storage even when API fails', async () => {
+      const mockApiClient = createMockApiClient()
+      const mockStorage = createMockStorage()
+      const apiError = new Error('Connection timeout')
+      mockApiClient.ackNotification = vi.fn().mockRejectedValue(apiError)
+
+      const tracker = createApiNotificationTracker({
+        notificationsApiClient: mockApiClient,
+        queryClient: createMockQueryClient(),
+        storage: mockStorage,
+      })
+
+      // Should not throw - errors are caught and logged
+      await tracker.track('notif-1', mockMetadata)
+
+      // Verify API was called
+      expect(mockApiClient.ackNotification).toHaveBeenCalledWith({
+        ids: ['notif-1'],
+      })
+
+      // Verify storage was updated despite API failure
+      expect(mockStorage.add).toHaveBeenCalledWith('notif-1', {
+        timestamp: mockMetadata.timestamp,
+      })
+    })
+
+    it('handles non-Error objects thrown by API', async () => {
+      const mockApiClient = createMockApiClient()
+      const mockStorage = createMockStorage()
+      mockApiClient.ackNotification = vi.fn().mockRejectedValue('String error')
+
+      const tracker = createApiNotificationTracker({
+        notificationsApiClient: mockApiClient,
+        queryClient: createMockQueryClient(),
+        storage: mockStorage,
+      })
+
+      // Should not throw - errors are caught and logged
+      await expect(tracker.track('notif-1', mockMetadata)).resolves.not.toThrow()
+
+      // Verify storage was updated despite API failure
+      expect(mockStorage.add).toHaveBeenCalledWith('notif-1', {
+        timestamp: mockMetadata.timestamp,
+      })
+    })
+
+    it('preserves metadata with different tracking strategies', async () => {
+      const mockApiClient = createMockApiClient()
+      const mockStorage = createMockStorage()
+
+      const tracker = createApiNotificationTracker({
+        notificationsApiClient: mockApiClient,
+        queryClient: createMockQueryClient(),
+        storage: mockStorage,
+      })
+
+      const notificationIds = ['notif-1', 'notif-2', 'notif-3', 'notif-4']
+
+      for (let i = 0; i < notificationIds.length; i++) {
+        const metadata: TrackingMetadata = {
+          timestamp: Date.now() + i,
+        }
+
+        await tracker.track(notificationIds[i], metadata)
+
+        expect(mockStorage.add).toHaveBeenCalledWith(notificationIds[i], {
+          timestamp: metadata.timestamp,
+        })
+      }
+    })
+
+    it('makes separate API calls for separate track invocations', async () => {
+      const mockApiClient = createMockApiClient()
+      const mockStorage = createMockStorage()
+
+      const tracker = createApiNotificationTracker({
+        notificationsApiClient: mockApiClient,
+        queryClient: createMockQueryClient(),
+        storage: mockStorage,
+      })
+
+      await tracker.track('notif-1', mockMetadata)
+      await tracker.track('notif-2', mockMetadata)
+      await tracker.track('notif-3', mockMetadata)
+
+      expect(mockApiClient.ackNotification).toHaveBeenCalledTimes(3)
+      expect(mockApiClient.ackNotification).toHaveBeenNthCalledWith(1, { ids: ['notif-1'] })
+      expect(mockApiClient.ackNotification).toHaveBeenNthCalledWith(2, { ids: ['notif-2'] })
+      expect(mockApiClient.ackNotification).toHaveBeenNthCalledWith(3, { ids: ['notif-3'] })
+    })
+  })
+
+  describe('cleanup', () => {
+    it('calls storage deleteOlderThan when provided', async () => {
+      const mockApiClient = createMockApiClient()
+      const mockStorage = createMockStorage()
+
+      const tracker = createApiNotificationTracker({
+        notificationsApiClient: mockApiClient,
+        queryClient: createMockQueryClient(),
+        storage: mockStorage,
+      })
+
+      expect(tracker.cleanup).toBeDefined()
+
+      const timestamp = Date.now() - 7 * 24 * 60 * 60 * 1000 // 7 days ago
+      await tracker.cleanup?.(timestamp)
+
+      expect(mockStorage.deleteOlderThan).toHaveBeenCalledWith(timestamp)
+    })
+
+    it('handles multiple cleanup calls with different timestamps', async () => {
+      const mockApiClient = createMockApiClient()
+      const mockStorage = createMockStorage()
+
+      const tracker = createApiNotificationTracker({
+        notificationsApiClient: mockApiClient,
+        queryClient: createMockQueryClient(),
+        storage: mockStorage,
+      })
+
+      const timestamp1 = Date.now() - 7 * 24 * 60 * 60 * 1000
+      const timestamp2 = Date.now() - 14 * 24 * 60 * 60 * 1000
+      const timestamp3 = Date.now() - 30 * 24 * 60 * 60 * 1000
+
+      await tracker.cleanup?.(timestamp1)
+      await tracker.cleanup?.(timestamp2)
+      await tracker.cleanup?.(timestamp3)
+
+      expect(mockStorage.deleteOlderThan).toHaveBeenCalledTimes(3)
+      expect(mockStorage.deleteOlderThan).toHaveBeenNthCalledWith(1, timestamp1)
+      expect(mockStorage.deleteOlderThan).toHaveBeenNthCalledWith(2, timestamp2)
+      expect(mockStorage.deleteOlderThan).toHaveBeenNthCalledWith(3, timestamp3)
+    })
+  })
+
+  describe('local notifications', () => {
+    it('skips API call for local: prefixed notifications but persists to storage', async () => {
+      const mockApiClient = createMockApiClient()
+      const mockStorage = createMockStorage()
+
+      const tracker = createApiNotificationTracker({
+        notificationsApiClient: mockApiClient,
+        queryClient: createMockQueryClient(),
+        storage: mockStorage,
+      })
+
+      await tracker.track('local:backup_reminder', mockMetadata)
+
+      // API should NOT be called for local notifications
+      expect(mockApiClient.ackNotification).not.toHaveBeenCalled()
+
+      // Storage should still be updated (persists across sessions)
+      expect(mockStorage.add).toHaveBeenCalledWith('local:backup_reminder', {
+        timestamp: mockMetadata.timestamp,
+      })
+    })
+
+    it('skips both API and storage for local:session: prefixed notifications (memory-only)', async () => {
+      const mockApiClient = createMockApiClient()
+      const mockStorage = createMockStorage()
+
+      const tracker = createApiNotificationTracker({
+        notificationsApiClient: mockApiClient,
+        queryClient: createMockQueryClient(),
+        storage: mockStorage,
+      })
+
+      await tracker.track('local:session:offline', mockMetadata)
+
+      // API should NOT be called
+      expect(mockApiClient.ackNotification).not.toHaveBeenCalled()
+
+      // Storage should NOT be updated (session-scoped = memory only)
+      expect(mockStorage.add).not.toHaveBeenCalled()
+    })
+
+    it('marks session-scoped notification as processed via pendingAcks', async () => {
+      const mockApiClient = createMockApiClient()
+      const mockStorage = createMockStorage()
+      mockStorage.has.mockResolvedValue(false) // Not in storage
+
+      const tracker = createApiNotificationTracker({
+        notificationsApiClient: mockApiClient,
+        queryClient: createMockQueryClient(),
+        storage: mockStorage,
+      })
+
+      // Initially not processed
+      expect(await tracker.isProcessed('local:session:offline')).toBe(false)
+
+      // Track it (memory-only)
+      await tracker.track('local:session:offline', mockMetadata)
+
+      // Now processed (via pendingAcks in-memory set)
+      expect(await tracker.isProcessed('local:session:offline')).toBe(true)
+
+      // But storage was NOT written to
+      expect(mockStorage.add).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('integration scenarios', () => {
+    it('prevents race condition: isProcessed returns true immediately after track is called', async () => {
+      const mockApiClient = createMockApiClient()
+      const mockStorage = createMockStorage()
+
+      // Simulate slow storage writes (e.g., IndexedDB or localStorage)
+      let storageWriteResolver: (() => void) | undefined
+      const storageWritePromise = new Promise<void>((resolve) => {
+        storageWriteResolver = resolve
+      })
+      mockStorage.add.mockReturnValue(storageWritePromise)
+
+      // Storage hasn't been written to yet
+      mockStorage.has.mockResolvedValue(false)
+
+      const tracker = createApiNotificationTracker({
+        notificationsApiClient: mockApiClient,
+        queryClient: createMockQueryClient(),
+        storage: mockStorage,
+      })
+
+      // Initially not processed
+      expect(await tracker.isProcessed('notif-1')).toBe(false)
+
+      // Start tracking (but don't await - simulates in-flight acknowledgment)
+      const trackPromise = tracker.track('notif-1', mockMetadata)
+
+      // CRITICAL: Even though storage.has still returns false and storage write hasn't completed,
+      // isProcessed should return true due to in-memory pending set
+      // This prevents notifications from re-appearing when data source refetches
+      expect(await tracker.isProcessed('notif-1')).toBe(true)
+
+      // Complete the storage write
+      storageWriteResolver?.()
+      await trackPromise
+
+      // Still processed after storage write completes
+      mockStorage.has.mockResolvedValue(true)
+      expect(await tracker.isProcessed('notif-1')).toBe(true)
+    })
+
+    it('handles complete notification lifecycle', async () => {
+      const mockApiClient = createMockApiClient()
+      const mockStorage = createMockStorage()
+
+      const tracker = createApiNotificationTracker({
+        notificationsApiClient: mockApiClient,
+        queryClient: createMockQueryClient(),
+        storage: mockStorage,
+      })
+
+      // Initially not processed
+      mockStorage.has.mockResolvedValue(false)
+      expect(await tracker.isProcessed('notif-1')).toBe(false)
+
+      // Track notification
+      await tracker.track('notif-1', mockMetadata)
+
+      // Now marked as processed
+      mockStorage.has.mockResolvedValue(true)
+      expect(await tracker.isProcessed('notif-1')).toBe(true)
+
+      // Appears in processed IDs
+      mockStorage.getAll.mockResolvedValue(new Set(['notif-1']))
+      expect(await tracker.getProcessedIds()).toEqual(new Set(['notif-1']))
+
+      // Clean up old entries
+      await tracker.cleanup?.(Date.now() - 1000)
+      expect(mockStorage.deleteOlderThan).toHaveBeenCalled()
+    })
+
+    it('marks notification as processed even when storage fails (UX priority)', async () => {
+      const mockApiClient = createMockApiClient()
+      const mockStorage = createMockStorage()
+
+      const tracker = createApiNotificationTracker({
+        notificationsApiClient: mockApiClient,
+        queryClient: createMockQueryClient(),
+        storage: mockStorage,
+      })
+
+      // Simulate storage failure
+      mockStorage.add.mockRejectedValue(new Error('Storage quota exceeded'))
+      mockStorage.has.mockResolvedValue(false)
+
+      // Track should not throw - errors are caught and logged
+      await expect(tracker.track('notif-1', mockMetadata)).resolves.not.toThrow()
+
+      // Verify API was called
+      expect(mockApiClient.ackNotification).toHaveBeenCalledWith({
+        ids: ['notif-1'],
+      })
+
+      // CRITICAL: Even though storage failed, the notification should still be
+      // considered processed due to in-memory pending set (UX priority)
+      expect(await tracker.isProcessed('notif-1')).toBe(true)
+    })
+
+    it('tracks same notification multiple times independently without deduplication', async () => {
+      const mockApiClient = createMockApiClient()
+      const mockStorage = createMockStorage()
+
+      const tracker = createApiNotificationTracker({
+        notificationsApiClient: mockApiClient,
+        queryClient: createMockQueryClient(),
+        storage: mockStorage,
+      })
+
+      await tracker.track('notif-1', mockMetadata)
+      await tracker.track('notif-1', { ...mockMetadata, timestamp: Date.now() + 1000 })
+      await tracker.track('notif-1', { ...mockMetadata, timestamp: Date.now() + 2000 })
+
+      // Each call should independently call the API and storage
+      expect(mockApiClient.ackNotification).toHaveBeenCalledTimes(3)
+      expect(mockStorage.add).toHaveBeenCalledTimes(3)
+    })
+  })
+})

package/src/notification-tracker/implementations/createApiNotificationTracker.ts

@@ -0,0 +1,154 @@
+import type { FetchQueryOptions, QueryClient } from '@tanstack/react-query'
+import type { NotificationsApiClient } from '@luxfi/api'
+import { createNotificationTracker } from '@luxfi/notifications/src/notification-tracker/implementations/createNotificationTracker'
+import {
+  NotificationTracker,
+  TrackingMetadata,
+} from '@luxfi/notifications/src/notification-tracker/NotificationTracker'
+import { getLogger } from '@luxfi/utilities/src/logger/logger'
+import { ReactQueryCacheKey } from '@luxfi/utilities/src/reactQuery/cache'
+
+/**
+ * Context for creating an API-based notification tracker
+ */
+export interface ApiNotificationTrackerContext {
+  notificationsApiClient: NotificationsApiClient
+  queryClient: QueryClient
+  /**
+   * Optional local storage for tracking state (e.g., to avoid duplicate API calls)
+   * If not provided, the tracker will always call the API
+   */
+  storage: {
+    has: (notificationId: string) => Promise<boolean>
+    add: (notificationId: string, metadata?: { timestamp: number }) => Promise<void>
+    getAll: () => Promise<Set<string>>
+    deleteOlderThan: (timestamp: number) => Promise<void>
+  }
+}
+
+/**
+ * Creates a notification tracker that uses the backend API to mark notifications as tracked.
+ *
+ * This implementation calls the AckNotifications API endpoint when a notification is tracked,
+ * allowing the backend to record that the user has seen/interacted with the notification.
+ *
+ * Example usage:
+ * ```typescript
+ * import { createApiNotificationTracker } from '@luxfi/notifications'
+ * import { createNotificationsApiClient } from '@luxfi/api'
+ *
+ * const apiClient = createNotificationsApiClient({
+ *   fetchClient: myFetchClient,
+ *   getApiPathPrefix: () => '/notifications/v1'
+ * })
+ *
+ * const tracker = createApiNotificationTracker({
+ *   notificationsApiClient: apiClient,
+ *   queryClient: myQueryClient
+ * })
+ *
+ * // Track a notification (sends request to backend with automatic retries)
+ * await tracker.track('notif-123', {
+ *   timestamp: Date.now()
+ * })
+ * ```
+ */
+export function createApiNotificationTracker(ctx: ApiNotificationTrackerContext): NotificationTracker {
+  const { notificationsApiClient, queryClient, storage } = ctx
+
+  // Track in-flight acknowledgments to prevent race conditions
+  // If a notification is being acknowledged but storage write hasn't completed yet,
+  // this ensures isProcessed() returns true immediately to prevent re-appearing notifications
+  const pendingAcks = new Set<string>()
+
+  const ackNotificationOptions = (notificationId: string): FetchQueryOptions => ({
+    queryKey: [ReactQueryCacheKey.AckNotification, notificationId],
+    queryFn: () =>
+      notificationsApiClient.ackNotification({
+        ids: [notificationId],
+      }),
+    // Retry up to 3 times for network errors or 5xx server errors
+    retry: 3,
+    // Exponential backoff: 1s, 2s, 4s, capped at 30s
+    retryDelay: (attemptIndex: number) => Math.min(1000 * 2 ** attemptIndex, 30000),
+    // Don't cache the result - this is a write operation
+    gcTime: 0,
+  })
+
+  const isProcessed = async (notificationId: string): Promise<boolean> => {
+    if (pendingAcks.has(notificationId)) {
+      return true
+    }
+    return storage.has(notificationId)
+  }
+
+  const getProcessedIds = async (): Promise<Set<string>> => {
+    return storage.getAll()
+  }
+
+  const track = async (notificationId: string, metadata: TrackingMetadata): Promise<void> => {
+    // Immediately mark as pending (synchronous) to prevent race condition
+    // where data source refetches before storage write completes
+    pendingAcks.add(notificationId)
+
+    // Check notification type by prefix
+    const isLocalNotification = notificationId.startsWith('local:')
+    const isSessionScopedNotification = notificationId.startsWith('local:session:')
+
+    // Session-scoped notifications only track in memory (pendingAcks), not storage.
+    // They will reset on app restart, allowing the notification to show again if
+    // the condition is still true (e.g., offline banner shows again after restart).
+    if (isSessionScopedNotification) {
+      return
+    }
+
+    // Attempt to call the backend API to acknowledge the notification
+    try {
+      await Promise.all([
+        // Skip API call for local notifications since the backend has no knowledge of them
+        isLocalNotification ? Promise.resolve() : queryClient.fetchQuery(ackNotificationOptions(notificationId)),
+        // Even if API fails, update localStorage so the notification stays dismissed
+        // from the user's perspective. This prioritizes UX over perfect backend consistency.
+        //
+        // Tradeoff: If localStorage is later cleared but the backend never received the ack,
+        // the notification could reappear. However, by the time localStorage is cleaned up
+        // or cleared, the notification will typically be expired on the backend anyway.
+        storage
+          .add(notificationId, { timestamp: metadata.timestamp })
+          .catch((storageError) => {
+            getLogger().error(
+              `Storage write failed for notification ${notificationId}: ${storageError instanceof Error ? storageError.message : String(storageError)}`,
+              {
+                tags: { file: 'createApiNotificationTracker', function: 'track' },
+              },
+            )
+          }),
+      ])
+    } catch (error) {
+      getLogger().error(
+        `Failed to acknowledge notification ${notificationId} after retries: ${error instanceof Error ? error.message : String(error)}`,
+        {
+          tags: {
+            file: 'createApiNotificationTracker',
+            function: 'track',
+          },
+        },
+      )
+      // Keep notification in pendingAcks even on error - prioritize UX
+      // The user dismissed it, so it should stay dismissed from their perspective
+    }
+    // Note: We intentionally don't remove from pendingAcks after completion
+    // Once acknowledged, it should always be considered processed
+  }
+
+  const cleanup = async (olderThan: number): Promise<void> => {
+    await storage.deleteOlderThan(olderThan)
+  }
+
+  return createNotificationTracker({
+    isProcessed,
+    getProcessedIds,
+    track,
+    cleanup,
+  })
+}

package/src/notification-tracker/implementations/createNoopNotificationTracker.ts

@@ -0,0 +1,44 @@
+import { createNotificationTracker } from '@luxfi/notifications/src/notification-tracker/implementations/createNotificationTracker'
+import {
+  NotificationTracker,
+  TrackingMetadata,
+} from '@luxfi/notifications/src/notification-tracker/NotificationTracker'
+
+/**
+ * Creates a no-op notification tracker that doesn't persist any state.
+ *
+ * Example usage:
+ * ```typescript
+ * import { createNoopNotificationTracker } from '@luxfi/notifications'
+ *
+ * const tracker = createNoopNotificationTracker()
+ *
+ * // All operations are no-ops
+ * const processed = await tracker.isProcessed('notif-123') // always false
+ * await tracker.track('notif-123', { timestamp: Date.now(), strategy: 'render' }) // no-op
+ * ```
+ */
+export function createNoopNotificationTracker(): NotificationTracker {
+  const isProcessed = async (_notificationId: string): Promise<boolean> => {
+    return false
+  }
+
+  const getProcessedIds = async (): Promise<Set<string>> => {
+    return new Set()
+  }
+
+  const track = async (_notificationId: string, _metadata: TrackingMetadata): Promise<void> => {
+    // no-op
+  }
+
+  const cleanup = async (_olderThan: number): Promise<void> => {
+    // no-op
+  }
+
+  return createNotificationTracker({
+    isProcessed,
+    getProcessedIds,
+    track,
+    cleanup,
+  })
+}

package/src/notification-tracker/implementations/createNotificationTracker.ts

@@ -0,0 +1,31 @@
+import {
+  NotificationTracker,
+  TrackingMetadata,
+} from '@luxfi/notifications/src/notification-tracker/NotificationTracker'
+
+/**
+ * Basic implementation of the NotificationTracker interface.
+ */
+export function createNotificationTracker(ctx: {
+  isProcessed: (notificationId: string) => Promise<boolean>
+  getProcessedIds: () => Promise<Set<string>>
+  track: (notificationId: string, metadata: TrackingMetadata) => Promise<void>
+  cleanup?: (olderThan: number) => Promise<void>
+}): NotificationTracker {
+  return {
+    isProcessed: async (notificationId: string): Promise<boolean> => {
+      return ctx.isProcessed(notificationId)
+    },
+    getProcessedIds: async (): Promise<Set<string>> => {
+      return ctx.getProcessedIds()
+    },
+    track: async (notificationId: string, metadata: TrackingMetadata): Promise<void> => {
+      return ctx.track(notificationId, metadata)
+    },
+    cleanup: ctx.cleanup
+      ? async (olderThan: number): Promise<void> => {
+          return ctx.cleanup?.(olderThan)
+        }
+      : undefined,
+  }
+}