@luxexchange/notifications 1.0.0

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

@@ -0,0 +1,113 @@
+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 ReactiveCondition } from '@luxexchange/notifications/src/notification-data-source/types/ReactiveCondition'
+import { type NotificationTracker } from '@luxexchange/notifications/src/notification-tracker/NotificationTracker'
+import { getLogger } from '@luxfi/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 '@luxexchange/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 '@luxfi/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>
+}