@luxexchange/notifications 1.0.0

package/src/notification-processor/implementations/createBaseNotificationProcessor.ts

@@ -0,0 +1,239 @@
+import { ContentStyle, type InAppNotification, OnClickAction } from '@luxexchange/api'
+import { createNotificationProcessor } from '@luxexchange/notifications/src/notification-processor/implementations/createNotificationProcessor'
+import {
+  type NotificationProcessor,
+  type NotificationProcessorResult,
+} from '@luxexchange/notifications/src/notification-processor/NotificationProcessor'
+import { type NotificationTracker } from '@luxexchange/notifications/src/notification-tracker/NotificationTracker'
+import { getLogger } from '@luxfi/utilities/src/logger/logger'
+
+/**
+ * Creates a base notification processor that implements style-based deduplication and limiting,
+ * as well as separating primary and chained notifications using topological sorting.
+ *
+ * Processing rules:
+ * 1. Builds a dependency graph of notifications based on POPUP actions
+ * 2. Uses topological sort to identify root notifications (those with no incoming edges)
+ * 3. Filters out notifications that have already been processed (tracked)
+ * 4. Limits the number of primary notifications per content style (LOWER_LEFT_BANNER: 3, others: 1)
+ * 5. Returns primary notifications for immediate rendering and chained notifications for later
+ *
+ * This properly handles notification chains of any length (A → B → C → D → ...).
+ *
+ * @param tracker - The NotificationTracker to check which notifications have been processed
+ * @returns A NotificationProcessor that applies these rules
+ */
+export function createBaseNotificationProcessor(tracker: NotificationTracker): NotificationProcessor {
+  return createNotificationProcessor({
+    process: async (notifications: InAppNotification[]): Promise<NotificationProcessorResult> => {
+      const processedIds = await tracker.getProcessedIds()
+
+      // Step 1: Build dependency graph and identify roots using topological analysis
+      const { roots, nonRoots } = identifyRootsAndChained(notifications)
+
+      // Step 2: Separate primary (roots) and chained (non-roots) notifications
+      const primaryNotifications: InAppNotification[] = []
+      const chainedNotifications: InAppNotification[] = []
+
+      for (const notification of notifications) {
+        if (roots.has(notification.id)) {
+          primaryNotifications.push(notification)
+        } else if (nonRoots.has(notification.id)) {
+          chainedNotifications.push(notification)
+        }
+      }
+
+      // Step 3: Filter out notifications that are locally tracked or don't have DISMISS action
+      const filteredPrimary = primaryNotifications.filter((notification) => {
+        if (processedIds.has(notification.id)) {
+          return false
+        }
+        if (!hasDismissAction(notification)) {
+          getLogger().warn(
+            'createBaseNotificationProcessor',
+            'process',
+            `Filtering out notification ${notification.id} - no DISMISS action found in any click configuration`,
+            { notification },
+          )
+          return false
+        }
+        return true
+      })
+
+      const filteredChained = chainedNotifications.filter((notification) => {
+        if (processedIds.has(notification.id)) {
+          return false
+        }
+        if (!hasDismissAction(notification)) {
+          getLogger().warn(
+            'createBaseNotificationProcessor',
+            'process',
+            `Filtering out notification ${notification.id} - no DISMISS action found in any click configuration`,
+            { notification },
+          )
+          return false
+        }
+        return true
+      })
+
+      // Step 4: Limit the number of primary notifications per content style
+      const limitedPrimary = limitNotifications(filteredPrimary)
+
+      // Step 5: Convert chained notifications to a Map for fast lookup
+      const chainedMap = new Map<string, InAppNotification>()
+      for (const notification of filteredChained) {
+        chainedMap.set(notification.id, notification)
+      }
+
+      return {
+        primary: limitedPrimary,
+        chained: chainedMap,
+      }
+    },
+  })
+}
+
+/**
+ * Checks if a notification has at least one DISMISS action in any of its click configurations.
+ * Every notification must have a way to be dismissed.
+ */
+function hasDismissAction(notification: InAppNotification): boolean {
+  // Check all buttons for DISMISS action
+  const buttons = notification.content?.buttons ?? []
+  for (const button of buttons) {
+    if (button.onClick?.onClick.includes(OnClickAction.DISMISS)) {
+      return true
+    }
+  }
+
+  // Check background click for DISMISS action
+  const backgroundOnClick = notification.content?.background?.backgroundOnClick
+  if (backgroundOnClick?.onClick.includes(OnClickAction.DISMISS)) {
+    return true
+  }
+
+  // Check onDismissClick for DISMISS action (close button)
+  const onDismissClick = notification.content?.onDismissClick
+  if (onDismissClick?.onClick.includes(OnClickAction.DISMISS)) {
+    return true
+  }
+
+  return false
+}
+
+/**
+ * Identifies root notifications and chained notifications using graph analysis.
+ *
+ * Builds a dependency graph where:
+ * - Nodes are notifications
+ * - Edges represent POPUP actions (A → B means A has a button/background that pops up B)
+ *
+ * Root notifications are those with no incoming edges (not referenced by any POPUP action).
+ * Chained notifications are those with at least one incoming edge.
+ *
+ * This properly handles chains of any length: A → B → C → D
+ * - A is a root (no incoming edges)
+ * - B, C, D are chained (have incoming edges)
+ *
+ * @returns Object with two sets: roots (primary notifications) and nonRoots (chained notifications)
+ */
+function identifyRootsAndChained(notifications: InAppNotification[]): { roots: Set<string>; nonRoots: Set<string> } {
+  const allIds = new Set<string>(notifications.map((n) => n.id))
+  const hasIncomingEdge = new Set<string>()
+
+  for (const notification of notifications) {
+    const popupTargets = extractPopupTargets(notification)
+
+    for (const targetId of popupTargets) {
+      if (allIds.has(targetId)) {
+        hasIncomingEdge.add(targetId)
+      }
+    }
+  }
+
+  const roots = new Set<string>()
+  const nonRoots = new Set<string>()
+
+  for (const notification of notifications) {
+    if (hasIncomingEdge.has(notification.id)) {
+      nonRoots.add(notification.id)
+    } else {
+      roots.add(notification.id)
+    }
+  }
+
+  return { roots, nonRoots }
+}
+
+/**
+ * Extracts all notification IDs that are targeted by POPUP actions in this notification.
+ * Checks both button clicks and background clicks.
+ */
+function extractPopupTargets(notification: InAppNotification): string[] {
+  const targets: string[] = []
+
+  const buttons = notification.content?.buttons ?? []
+  for (const button of buttons) {
+    const target = getPopupTarget(button.onClick)
+    if (target) {
+      targets.push(target)
+    }
+  }
+
+  const backgroundTarget = getPopupTarget(notification.content?.background?.backgroundOnClick)
+  if (backgroundTarget) {
+    targets.push(backgroundTarget)
+  }
+
+  return targets
+}
+
+/**
+ * Gets the target notification ID if this onClick action includes POPUP.
+ */
+function getPopupTarget(onClick: { onClick: OnClickAction[]; onClickLink?: string } | undefined): string | undefined {
+  if (!onClick?.onClick.includes(OnClickAction.POPUP)) {
+    return undefined
+  }
+  return onClick.onClickLink
+}
+
+/**
+ * Limits the number of notifications per content style.
+ * - LOWER_LEFT_BANNER: up to 3 notifications
+ * - SYSTEM_BANNER: 1 notification (sticky system alerts)
+ * - All other styles: 1 notification each
+ */
+function limitNotifications(notifications: InAppNotification[]): InAppNotification[] {
+  const groupedByStyle = new Map<number, InAppNotification[]>()
+
+  for (const notification of notifications) {
+    const style = notification.content?.style ?? ContentStyle.UNSPECIFIED
+    const group = groupedByStyle.get(style) ?? []
+    group.push(notification)
+    groupedByStyle.set(style, group)
+  }
+
+  const limited: InAppNotification[] = []
+
+  for (const [style, group] of groupedByStyle.entries()) {
+    const limit = getStyleLimit(style)
+    limited.push(...group.slice(0, limit))
+  }
+
+  return limited
+}
+
+/**
+ * Returns the maximum number of concurrent notifications for a given content style.
+ */
+function getStyleLimit(style: number): number {
+  if (style === ContentStyle.LOWER_LEFT_BANNER) {
+    return 3
+  }
+  if (style === ContentStyle.SYSTEM_BANNER) {
+    return 1
+  }
+  // Default: 1 for MODAL, UNSPECIFIED, and any future styles
+  return 1
+}

package/src/notification-processor/implementations/createNotificationProcessor.test.ts

@@ -0,0 +1,130 @@
+import type { InAppNotification } from '@luxfi/api'
+import { createNotificationProcessor } from '@luxfi/notifications/src/notification-processor/implementations/createNotificationProcessor'
+import { describe, expect, it, vi } from 'vitest'
+
+describe('createNotificationProcessor', () => {
+  it('creates a notification processor with process method', () => {
+    const mockProcess = vi.fn()
+    const processor = createNotificationProcessor({
+      process: mockProcess,
+    })
+
+    expect(processor).toBeDefined()
+    expect(typeof processor.process).toBe('function')
+  })
+
+  it('delegates process call to injected process function', async () => {
+    const mockNotifications: InAppNotification[] = [
+      {
+        id: 'test-notif-1-id',
+        metaData: {},
+        notificationName: 'test-notif-1',
+        timestamp: 1000,
+        content: { style: 'CONTENT_STYLE_MODAL', title: 'test-notif-1-title' },
+        userId: 'user-1',
+      } as InAppNotification,
+    ]
+    const mockResult: InAppNotification[] = [
+      {
+        id: 'result-notif-id',
+        metaData: {},
+        notificationName: 'result-notif',
+        timestamp: 2000,
+        content: { style: 'CONTENT_STYLE_MODAL', title: 'result-notif-title' },
+        userId: 'user-1',
+      } as InAppNotification,
+    ]
+
+    const mockProcess = vi.fn().mockResolvedValue(mockResult)
+    const processor = createNotificationProcessor({
+      process: mockProcess,
+    })
+
+    const result = await processor.process(mockNotifications)
+
+    expect(mockProcess).toHaveBeenCalledWith(mockNotifications)
+    expect(result).toBe(mockResult)
+  })
+
+  it('preserves the exact arguments passed to process method', async () => {
+    const notifications: InAppNotification[] = [
+      {
+        id: 'notif-1-id',
+        metaData: {},
+        notificationName: 'notif-1',
+        timestamp: 1000,
+        content: { style: 'CONTENT_STYLE_MODAL', title: 'notif-1-title' },
+        userId: 'user-1',
+      } as InAppNotification,
+      {
+        id: 'notif-2-id',
+        metaData: {},
+        notificationName: 'notif-2',
+        timestamp: 2000,
+        content: { style: 'CONTENT_STYLE_BANNER', title: 'notif-2-title' },
+        userId: 'user-1',
+      } as InAppNotification,
+    ]
+
+    let capturedNotifications: InAppNotification[] | undefined
+
+    const mockProcess = vi.fn(async (notifs) => {
+      capturedNotifications = notifs
+      return []
+    })
+
+    const processor = createNotificationProcessor({
+      process: mockProcess,
+    })
+
+    await processor.process(notifications)
+
+    expect(capturedNotifications).toBe(notifications)
+  })
+
+  it('returns empty array when injected process returns empty array', async () => {
+    const mockProcess = vi.fn().mockResolvedValue([])
+    const processor = createNotificationProcessor({
+      process: mockProcess,
+    })
+
+    const result = await processor.process([])
+
+    expect(result).toEqual([])
+  })
+
+  it('handles multiple calls with different arguments', async () => {
+    const mockProcess = vi.fn(async (notifications) => notifications)
+    const processor = createNotificationProcessor({
+      process: mockProcess,
+    })
+
+    const notifs1: InAppNotification[] = [
+      {
+        id: 'notif-1-id',
+        metaData: {},
+        notificationName: 'notif-1',
+        timestamp: 1000,
+        content: { style: 'CONTENT_STYLE_MODAL', title: 'notif-1-title' },
+        userId: 'user-1',
+      } as InAppNotification,
+    ]
+    const notifs2: InAppNotification[] = [
+      {
+        id: 'notif-2-id',
+        metaData: {},
+        notificationName: 'notif-2',
+        timestamp: 2000,
+        content: { style: 'CONTENT_STYLE_BANNER', title: 'notif-2-title' },
+        userId: 'user-1',
+      } as InAppNotification,
+    ]
+
+    const result1 = await processor.process(notifs1)
+    const result2 = await processor.process(notifs2)
+
+    expect(mockProcess).toHaveBeenCalledTimes(2)
+    expect(result1).toEqual(notifs1)
+    expect(result2).toEqual(notifs2)
+  })
+})

package/src/notification-processor/implementations/createNotificationProcessor.ts

@@ -0,0 +1,15 @@
+import { type InAppNotification } from '@luxfi/api'
+import {
+  type NotificationProcessor,
+  type NotificationProcessorResult,
+} from '@luxfi/notifications/src/notification-processor/NotificationProcessor'
+
+export function createNotificationProcessor(ctx: {
+  process: (notifications: InAppNotification[]) => Promise<NotificationProcessorResult>
+}): NotificationProcessor {
+  return {
+    process: async (notifications: InAppNotification[]): Promise<NotificationProcessorResult> => {
+      return ctx.process(notifications)
+    },
+  }
+}

package/src/notification-renderer/NotificationRenderer.ts

@@ -0,0 +1,8 @@
+import { type InAppNotification } from '@luxfi/api'
+
+export interface NotificationRenderer {
+  // Render a notification and return cleanup function
+  render(notification: InAppNotification): () => void
+  // Check if a notification type can be rendered (e.g., only one modal at a time)
+  canRender(notification: InAppNotification): boolean
+}

package/src/notification-renderer/components/BannerTemplate.tsx

@@ -0,0 +1,188 @@
+import { ReactNode } from 'react'
+import { Button, Flex, IconButton, styled, Text, useIsDarkMode } from '@luxfi/ui/src'
+import { X } from '@luxfi/ui/src/components/icons/X'
+import { zIndexes } from '@luxfi/ui/src/theme'
+
+const BANNER_WIDTH = 260
+const BANNER_HEIGHT = 150
+const GRADIENT_BACKGROUND_HEIGHT = 64 // Vertical midpoint of the thumbnail
+const ICON_SIZE = 40
+
+const BannerContainer = styled(Flex, {
+  borderRadius: '$rounded16',
+  minHeight: BANNER_HEIGHT,
+  shadowColor: '$shadowColor',
+  shadowOffset: { width: 0, height: 4 },
+  shadowOpacity: 0.4,
+  shadowRadius: 10,
+  overflow: 'hidden',
+  padding: '$spacing16',
+  backgroundColor: '$surface1',
+  borderWidth: 1,
+  borderColor: '$surface3',
+  variants: {
+    clickable: {
+      true: {
+        cursor: 'pointer',
+      },
+      false: {
+        cursor: 'default',
+      },
+    },
+  } as const,
+})
+
+const GradientBackground = styled(Flex, {
+  position: 'absolute',
+  top: 0,
+  left: 0,
+  right: 0,
+  width: '100%',
+  height: GRADIENT_BACKGROUND_HEIGHT,
+  backgroundSize: 'cover',
+  backgroundPosition: 'center',
+  backgroundRepeat: 'no-repeat',
+  mask: 'linear-gradient(180deg, rgba(0,0,0,0.48) 0%, rgba(0,0,0,0) 100%)',
+})
+
+const IconContainer = styled(Flex, {
+  width: ICON_SIZE,
+  height: ICON_SIZE,
+  backgroundSize: 'cover',
+  backgroundPosition: 'center',
+  backgroundRepeat: 'no-repeat',
+  borderRadius: '$rounded6',
+})
+
+const ContentWrapper = styled(Flex, {
+  flex: 1,
+  justifyContent: 'space-between',
+  paddingTop: 16,
+})
+
+function BannerXButton({ handleClose }: { handleClose: () => void }): JSX.Element {
+  return (
+    <Flex row centered position="absolute" right={8} top={8} zIndex={zIndexes.mask}>
+      <IconButton
+        size="xxsmall"
+        emphasis="secondary"
+        icon={<X />}
+        onPress={(e) => {
+          e.stopPropagation()
+          handleClose()
+        }}
+      />
+    </Flex>
+  )
+}
+
+export interface BannerTemplateButton {
+  text: string
+  onPress: () => void
+  isPrimary?: boolean
+}
+
+interface BannerTemplateProps {
+  backgroundImageUrl?: string
+  /** Optional dark mode variant for backgroundImageUrl. Falls back to backgroundImageUrl if not provided. */
+  darkModeBackgroundImageUrl?: string
+  /** Pre-rendered icon element. When provided, takes priority over iconUrl. */
+  icon?: ReactNode
+  iconUrl?: string
+  /** Optional dark mode variant for iconUrl. Falls back to iconUrl if not provided. */
+  darkModeIconUrl?: string
+  title: string
+  subtitle?: string
+  onClose: () => void
+  onPress?: () => void
+  children?: ReactNode
+  /** Override the default banner width. Use '100%' for full-width. */
+  width?: number | string
+  /** Optional button to display below the content */
+  button?: BannerTemplateButton
+}
+
+/**
+ * BannerTemplate component
+ *
+ * A reusable template for rendering lower-banner notifications.
+ * Extracted from SolanaPromoBanner to be shared across the notification system.
+ *
+ * Features:
+ * - Fixed position in lower-left corner
+ * - Optional background image with gradient overlay
+ * - Optional icon
+ * - Title and subtitle text (or custom children)
+ * - Dismiss button
+ * - Click handler support
+ */
+export function BannerTemplate({
+  backgroundImageUrl,
+  darkModeBackgroundImageUrl,
+  icon,
+  iconUrl,
+  darkModeIconUrl,
+  title,
+  subtitle,
+  onClose,
+  onPress,
+  children,
+  width,
+  button,
+}: BannerTemplateProps): JSX.Element {
+  const isDarkMode = useIsDarkMode()
+  const effectiveBackgroundUrl =
+    isDarkMode && darkModeBackgroundImageUrl ? darkModeBackgroundImageUrl : backgroundImageUrl
+  const effectiveIconUrl = isDarkMode && darkModeIconUrl ? darkModeIconUrl : iconUrl
+
+  return (
+    <BannerContainer pointerEvents="auto" width={width ?? BANNER_WIDTH} clickable={!!onPress} onPress={onPress}>
+      <BannerXButton handleClose={onClose} />
+
+      {effectiveBackgroundUrl && <GradientBackground backgroundImage={`url(${effectiveBackgroundUrl})`} />}
+
+      <ContentWrapper>
+        <Flex gap="$spacing8">
+          {icon ? (
+            <Flex centered width={ICON_SIZE} height={ICON_SIZE}>
+              {icon}
+            </Flex>
+          ) : effectiveIconUrl ? (
+            <IconContainer backgroundImage={`url(${effectiveIconUrl})`} />
+          ) : (
+            <Flex width={ICON_SIZE} height={ICON_SIZE} backgroundColor="transparent" />
+          )}
+
+          {children || (
+            <Flex gap="$spacing4">
+              <Text variant="body3" color="$neutral1">
+                {title}
+              </Text>
+              {subtitle && (
+                <Text variant="body4" color="$neutral2">
+                  {subtitle}
+                </Text>
+              )}
+            </Flex>
+          )}
+        </Flex>
+
+        {button && (
+          <Flex marginTop="$spacing12">
+            <Button
+              size="medium"
+              emphasis={button.isPrimary ? 'primary' : 'secondary'}
+              minHeight="$spacing36"
+              onPress={(e) => {
+                e.stopPropagation()
+                button.onPress()
+              }}
+            >
+              {button.text}
+            </Button>
+          </Flex>
+        )}
+      </ContentWrapper>
+    </BannerContainer>
+  )
+}

package/src/notification-renderer/components/InlineBannerNotification.tsx

@@ -0,0 +1,123 @@
+import { BackgroundType } from '@uniswap/client-notification-service/dist/uniswap/notificationservice/v1/api_pb'
+import type { InAppNotification } from '@luxexchange/api'
+import {
+  BannerTemplate,
+  type BannerTemplateButton,
+} from '@luxexchange/notifications/src/notification-renderer/components/BannerTemplate'
+import { parseCustomIconLink } from '@luxexchange/notifications/src/notification-renderer/utils/iconUtils'
+import { type NotificationClickTarget } from '@luxexchange/notifications/src/notification-service/NotificationService'
+import { memo, useMemo } from 'react'
+import { useTranslation } from 'react-i18next'
+
+const BANNER_ICON_SIZE = 40
+
+interface InlineBannerNotificationProps {
+  notification: InAppNotification
+  onNotificationClick?: (notificationId: string, target: NotificationClickTarget) => void
+  /** Override the default banner width. Use '100%' for full-width. */
+  width?: number | string
+  /** Enable button rendering. Defaults to false (web only). */
+  renderButton?: boolean
+}
+
+/**
+ * InlineBannerNotification component
+ *
+ * A wrapper around BannerTemplate for rendering notification API-driven banners.
+ * Can be used inline (extension/mobile) or in fixed position (web).
+ * Delegates click handling to the NotificationService.
+ *
+ * Features:
+ * - Maps notification API types to BannerTemplate props
+ * - Delegates click actions to NotificationService via onNotificationClick
+ * - Extracts background images and icons from notification content
+ *
+ * Notification API Type Mapping:
+ * - content.title → Banner title
+ * - content.subtitle → Banner description
+ * - content.background.link → Background image URL (when backgroundType is IMAGE)
+ * - content.background.backgroundOnClick → Handled by NotificationService
+ */
+export const InlineBannerNotification = memo(function InlineBannerNotification({
+  notification,
+  onNotificationClick,
+  width,
+  renderButton = false,
+}: InlineBannerNotificationProps) {
+  const { t, i18n } = useTranslation()
+  const content = notification.content
+
+  const handleClose = (): void => {
+    onNotificationClick?.(notification.id, { type: 'dismiss' })
+  }
+
+  const hasBackgroundClick = !!content?.background?.backgroundOnClick
+
+  const handleBannerPress = (): void => {
+    onNotificationClick?.(notification.id, { type: 'background' })
+  }
+
+  const backgroundImageUrl = useMemo(() => {
+    const background = content?.background
+    if (background && background.backgroundType === BackgroundType.IMAGE && background.link) {
+      return background.link
+    }
+    return undefined
+  }, [content?.background])
+
+  const darkModeBackgroundImageUrl = useMemo(() => {
+    const background = content?.background
+    if (background && background.backgroundType === BackgroundType.IMAGE && background.darkModeLink) {
+      return background.darkModeLink
+    }
+    return undefined
+  }, [content?.background])
+
+  const customIcon = useMemo(() => {
+    const parsed = parseCustomIconLink(content?.iconLink)
+    if (!parsed.IconComponent) {
+      return undefined
+    }
+    const Icon = parsed.IconComponent
+    return <Icon size={BANNER_ICON_SIZE} color={parsed.colorToken ?? '$neutral1'} />
+  }, [content?.iconLink])
+
+  const button = useMemo((): BannerTemplateButton | undefined => {
+    if (!renderButton) {
+      return undefined
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    const firstButton = content?.buttons?.[0]
+    if (!firstButton) {
+      return undefined
+    }
+
+    // Translate known i18n keys, otherwise use raw text
+    const buttonText = i18n.exists(firstButton.text) ? t(firstButton.text) : firstButton.text
+
+    return {
+      text: buttonText,
+      isPrimary: firstButton.isPrimary ?? false,
+      onPress: (): void => {
+        onNotificationClick?.(notification.id, { type: 'button', index: 0 })
+      },
+    }
+  }, [renderButton, content?.buttons, notification.id, onNotificationClick, t, i18n])
+
+  return (
+    <BannerTemplate
+      backgroundImageUrl={backgroundImageUrl}
+      darkModeBackgroundImageUrl={darkModeBackgroundImageUrl}
+      icon={customIcon}
+      iconUrl={customIcon ? undefined : content?.iconLink}
+      darkModeIconUrl={customIcon ? undefined : content?.darkModeIconLink}
+      title={content?.title ?? ''}
+      subtitle={content?.subtitle ?? ''}
+      width={width}
+      button={button}
+      onClose={handleClose}
+      onPress={hasBackgroundClick ? handleBannerPress : undefined}
+    />
+  )
+})