@luxexchange/notifications 1.0.2 → 1.0.3

package/.depcheckrc

@@ -0,0 +1,14 @@
+ignores: [
+    # Test coverage tool
+    "@vitest/coverage-v8",
+
+    # Standard ignores
+    "typescript",
+    "@typescript/native-preview",
+    "depcheck",
+
+    # Internal packages / workspaces - used in test files
+    "@universe/notifications",
+    "@universe/api",
+    "utilities",
+  ]

package/.eslintrc.js

@@ -0,0 +1,20 @@
+module.exports = {
+  extends: ['@luxamm/eslint-config/lib'],
+  parserOptions: {
+    tsconfigRootDir: __dirname,
+  },
+  overrides: [
+    {
+      files: ['*.ts', '*.tsx'],
+      rules: {
+        'no-relative-import-paths/no-relative-import-paths': [
+          'error',
+          {
+            allowSameFolder: false,
+            prefix: '@luxexchange/notifications',
+          },
+        ],
+      },
+    },
+  ],
+}

package/README.md

@@ -0,0 +1,548 @@
+# @universe/notifications
+
+A platform-agnostic notification service for fetching, processing, storing, and displaying in-app notifications across web, mobile, and extension platforms.
+
+## Table of Contents
+
+- [Architecture](#architecture)
+- [Core Concepts](#core-concepts)
+  - [Notification Types](#notification-types-contentstyle)
+  - [Data Source Patterns](#data-source-patterns)
+  - [Notification Chains](#notification-chains)
+  - [Notification ID Conventions](#notification-id-conventions)
+  - [User Actions](#user-actions-onclickaction)
+- [Getting Started](#getting-started)
+- [Platform Integrations](#platform-integrations)
+  - [Web](#web-integration)
+  - [Mobile](#mobile-integration)
+  - [Extension](#extension-integration)
+- [Common Patterns](#common-patterns)
+- [Testing](#testing)
+- [Troubleshooting](#troubleshooting)
+- [API Reference](#api-reference)
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         NotificationService                             │
+│                           (Orchestrator)                                │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                         │
+│   ┌──────────────────┐     ┌───────────────────┐     ┌──────────────┐  │
+│   │   DataSources    │────▶│    Processor      │────▶│   Renderer   │  │
+│   │                  │     │                   │     │              │  │
+│   │ • Polling (API)  │     │ • Filters tracked │     │ • canRender  │  │
+│   │ • Reactive       │     │ • Limits by style │     │ • render()   │  │
+│   │ • LocalTrigger   │     │ • Separates chains│     │ • cleanup()  │  │
+│   │ • Interval       │     │                   │     │              │  │
+│   └──────────────────┘     └───────────────────┘     └──────────────┘  │
+│            │                        │                       │          │
+│            │                        ▼                       │          │
+│            │               ┌───────────────────┐            │          │
+│            │               │     Tracker       │◀───────────┘          │
+│            │               │                   │                       │
+│            │               │ • isProcessed()   │                       │
+│            │               │ • track()         │                       │
+│            │               │ • cleanup()       │                       │
+│            │               └───────────────────┘                       │
+│            │                        │                                  │
+│            ▼                        ▼                                  │
+│   ┌─────────────────────────────────────────────────────────────────┐  │
+│   │                         Telemetry                                │  │
+│   │  onNotificationReceived → onNotificationShown → onInteracted    │  │
+│   └─────────────────────────────────────────────────────────────────┘  │
+│                                                                         │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### Component Responsibilities
+
+| Component | Responsibility |
+|-----------|----------------|
+| **DataSource** | Feeds notifications to the service (API polling, state subscriptions, local triggers) |
+| **Processor** | Filters tracked notifications, enforces style limits, separates primary vs chained |
+| **Renderer** | Platform-specific UI rendering with canRender/render/cleanup lifecycle |
+| **Tracker** | Tracks acknowledged notifications to prevent re-showing |
+| **Telemetry** | Reports lifecycle events (received, shown, interacted) to analytics |
+
+### Lifecycle
+
+1. **Initialize** — Service starts all data sources
+2. **Receive** — Data sources emit notifications to the service
+3. **Process** — Processor filters and categorizes notifications
+4. **Render** — Renderer displays primary notifications, stores chained for later
+5. **Interact** — User clicks trigger actions (DISMISS, ACK, POPUP, EXTERNAL_LINK)
+6. **Track** — ACK action marks notification as processed
+7. **Destroy** — Service cleans up data sources and active renders
+
+## Core Concepts
+
+### Notification Types (ContentStyle)
+
+| Style | Description | Max Concurrent | Typical Use |
+|-------|-------------|----------------|-------------|
+| `MODAL` | Full-screen overlays requiring user action | 1 | Feature announcements, onboarding flows |
+| `SYSTEM_BANNER` | System alerts (typically at screen bottom) | 1 | Offline status, storage warnings |
+| `LOWER_LEFT_BANNER` | Promotional banners stacked in lower-left | 3 | Chain promotions, feature highlights |
+
+### Data Source Patterns
+
+The service supports four patterns for feeding notifications:
+
+#### 1. Polling (Backend API via React Query)
+
+Best for: Backend-driven notifications with automatic caching and refetch.
+
+```typescript
+import { createPollingNotificationDataSource, getNotificationQueryOptions } from '@universe/notifications'
+
+const pollingDataSource = createPollingNotificationDataSource({
+  queryClient,
+  queryOptions: getNotificationQueryOptions({ address, platformType, appId }),
+})
+```
+
+#### 2. Reactive (Push-based Subscriptions)
+
+Best for: Instant response to state changes (network status, storage quota).
+
+```typescript
+import { createReactiveDataSource, type ReactiveCondition } from '@universe/notifications'
+
+const offlineCondition: ReactiveCondition<{ isConnected: boolean }> = {
+  notificationId: 'local:session:offline',
+  subscribe: (onStateChange) => {
+    return NetInfo.addEventListener((state) => {
+      onStateChange({ isConnected: state.isConnected })
+    })
+  },
+  shouldShow: (state) => state.isConnected === false,
+  createNotification: () => new Notification({ /* ... */ }),
+}
+
+const reactiveDataSource = createReactiveDataSource({
+  condition: offlineCondition,
+  tracker,
+})
+```
+
+#### 3. LocalTrigger (Condition-based Polling)
+
+Best for: Periodic checks of local state (Redux selectors, app conditions).
+
+```typescript
+import { createLocalTriggerDataSource, type TriggerCondition } from '@universe/notifications'
+
+const backupTrigger: TriggerCondition = {
+  id: 'local:backup_reminder',
+  shouldShow: async () => {
+    const account = selectActiveAccount(getState())
+    return account && !hasExternalBackup(account)
+  },
+  createNotification: () => new Notification({ /* ... */ }),
+  onAcknowledge: () => dispatch(setLastSeenTs(Date.now())),
+}
+
+const localTriggerDataSource = createLocalTriggerDataSource({
+  triggers: [backupTrigger],
+  tracker,
+  pollIntervalMs: 5000,
+})
+```
+
+#### 4. Interval (Simple Periodic Checks)
+
+Best for: Custom periodic notification fetching.
+
+```typescript
+import { createIntervalNotificationDataSource } from '@universe/notifications'
+
+const intervalDataSource = createIntervalNotificationDataSource({
+  pollIntervalMs: 30000,
+  source: 'legacy_banners',
+  logFileTag: 'LegacyBanners',
+  getNotifications: async () => fetchLegacyBanners(),
+})
+```
+
+### Notification Chains
+
+Notifications can trigger follow-up notifications using the `POPUP` action:
+
+```typescript
+// Step 1: User sees welcome banner
+{
+  id: 'welcome_step_1',
+  content: {
+    buttons: [{
+      text: 'Learn More',
+      onClick: {
+        onClick: [OnClickAction.DISMISS, OnClickAction.POPUP],
+        onClickLink: 'welcome_step_2'  // ← triggers next notification
+      }
+    }]
+  }
+}
+
+// Step 2: Detailed modal (stored as "chained" until triggered)
+{
+  id: 'welcome_step_2',
+  content: { style: ContentStyle.MODAL, /* ... */ }
+}
+```
+
+The processor automatically identifies root vs chained notifications using graph analysis.
+
+### Notification ID Conventions
+
+| Prefix | Storage | Behavior |
+|--------|---------|----------|
+| (none) | API + localStorage | Permanent tracking, synced with backend |
+| `local:` | localStorage only | Permanent tracking, local only (no API calls) |
+| `local:session:` | sessionStorage | Resets on app restart (e.g., offline banner) |
+
+### User Actions (OnClickAction)
+
+| Action | Effect |
+|--------|--------|
+| `DISMISS` | Hides the notification (can reappear if not ACK'd) |
+| `ACK` | Marks as acknowledged, prevents re-showing |
+| `POPUP` | Shows the notification specified in `onClickLink` |
+| `EXTERNAL_LINK` | Navigates to URL in `onClickLink` via `onNavigate` handler |
+
+Actions are combined in arrays and executed sequentially:
+```typescript
+onClick: [OnClickAction.DISMISS, OnClickAction.ACK]  // Hide and mark processed
+onClick: [OnClickAction.DISMISS, OnClickAction.POPUP]  // Hide and show next
+```
+
+## Getting Started
+
+### Initialize the Service
+
+```typescript
+import {
+  createNotificationService,
+  createPollingNotificationDataSource,
+  createBaseNotificationProcessor,
+  createNotificationTracker,
+  createNotificationRenderer,
+  createNotificationTelemetry,
+} from '@universe/notifications'
+
+const notificationService = createNotificationService({
+  dataSources: [
+    createPollingNotificationDataSource({ queryClient, queryOptions }),
+    // Add more data sources as needed
+  ],
+  tracker: createNotificationTracker(storageAdapter),
+  processor: createBaseNotificationProcessor(tracker),
+  renderer: createNotificationRenderer({ onRender, canRender }),
+  telemetry: createNotificationTelemetry({ analytics }),
+  onNavigate: (url) => window.open(url, '_blank'),
+})
+
+await notificationService.initialize()
+```
+
+### Handle User Interactions
+
+```typescript
+// When user clicks a button (index 0)
+notificationService.onNotificationClick(notificationId, { type: 'button', index: 0 })
+
+// When user clicks the dismiss/close button
+notificationService.onNotificationClick(notificationId, { type: 'dismiss' })
+
+// When user clicks the background
+notificationService.onNotificationClick(notificationId, { type: 'background' })
+
+// When notification is shown to user (for telemetry)
+notificationService.onNotificationShown(notificationId)
+
+// When render fails (e.g., unknown notification style)
+notificationService.onRenderFailed(notificationId)
+```
+
+### Cleanup
+
+```typescript
+// On unmount or navigation
+notificationService.destroy()
+```
+
+## Platform Integrations
+
+### Web Integration
+
+**Location:** `apps/web/src/notification-service/`
+
+```
+apps/web/src/notification-service/
+├── WebNotificationService.tsx          # Service initialization
+├── createLocalStorageAdapter.ts        # localStorage-based tracker
+├── notification-renderer/
+│   ├── NotificationContainer.tsx       # Renders all notification types
+│   ├── StackedLowerLeftBanners.tsx     # Framer-motion stacking animations
+│   ├── notificationStore.ts            # Zustand store for UI state
+│   └── components/
+│       └── SystemBannerNotification.tsx
+├── data-sources/
+│   ├── createLegacyBannersNotificationDataSource.ts
+│   └── createSystemAlertsDataSource.ts
+└── telemetry/
+    └── getNotificationTelemetry.ts
+```
+
+**Key features:**
+- Zustand store pattern for UI state management
+- Framer-motion animations for stacked banners
+- localStorage-based notification tracking
+
+### Mobile Integration
+
+**Location:** `apps/mobile/src/notification-service/`
+
+```
+apps/mobile/src/notification-service/
+├── MobileNotificationServiceManager.tsx  # Service manager component
+├── MobileNotificationService.ts          # Service initialization
+├── createMobileStorageAdapter.ts         # MMKV-based tracker
+├── handleNotificationNavigation.ts       # Navigation handler
+├── notification-renderer/
+│   ├── NotificationContainer.tsx         # Routes to custom renderers
+│   ├── SystemBannerPortal.tsx            # Portal for system banners
+│   └── createMobileNotificationRenderer.ts
+├── renderers/
+│   ├── BackupReminderModalRenderer.tsx   # Custom modal for backup reminder
+│   └── OfflineBannerRenderer.tsx         # Custom banner for offline state
+├── triggers/
+│   ├── backupReminderTrigger.ts          # LocalTrigger example
+│   └── createMobileLocalTriggerDataSource.ts
+└── data-sources/
+    ├── reactive/
+    │   └── offlineCondition.ts           # ReactiveCondition example
+    └── banners/                          # Legacy banner data sources
+```
+
+**Key features:**
+- MMKV storage for high-performance tracking
+- Custom renderers for platform-specific UI (BackupReminder, OfflineBanner)
+- NetInfo integration for offline detection via reactive data source
+
+### Extension Integration
+
+**Location:** `apps/extension/src/notification-service/`
+
+```
+apps/extension/src/notification-service/
+├── ExtensionNotificationServiceManager.tsx  # Service manager
+├── ExtensionNotificationService.tsx         # Service initialization
+├── createChromeStorageAdapter.ts            # Chrome Storage API tracker
+├── notification-renderer/
+│   ├── NotificationContainer.tsx
+│   └── notificationStore.ts
+├── renderers/
+│   ├── AppRatingModalRenderer.tsx
+│   └── StorageWarningModalRenderer.tsx
+├── triggers/
+│   ├── appRatingTrigger.ts
+│   └── createExtensionLocalTriggerDataSource.ts
+└── data-sources/
+    └── reactive/
+        └── storageWarningCondition.ts       # Storage quota monitoring
+```
+
+**Key features:**
+- Chrome Storage API for cross-session persistence
+- Storage quota monitoring via reactive data source
+- Special navigation handling (e.g., `unitag://` protocol)
+
+## Common Patterns
+
+### Creating a Local Trigger
+
+```typescript
+import { type TriggerCondition } from '@universe/notifications'
+
+export const REMINDER_NOTIFICATION_ID = 'local:my_reminder'
+
+interface CreateReminderTriggerContext {
+  getState: () => AppState
+  dispatch: (action: AnyAction) => void
+}
+
+export function createReminderTrigger(ctx: CreateReminderTriggerContext): TriggerCondition {
+  const { getState, dispatch } = ctx
+
+  return {
+    id: REMINDER_NOTIFICATION_ID,
+
+    shouldShow: async () => {
+      const state = getState()
+      const lastSeen = selectReminderLastSeen(state)
+      return Date.now() - lastSeen > ONE_DAY_MS
+    },
+
+    createNotification: () => new Notification({
+      id: REMINDER_NOTIFICATION_ID,
+      content: new Content({
+        style: ContentStyle.MODAL,
+        title: 'Reminder',
+        onDismissClick: new OnClick({
+          onClick: [OnClickAction.DISMISS, OnClickAction.ACK],
+        }),
+      }),
+    }),
+
+    onAcknowledge: () => {
+      dispatch(setReminderLastSeen(Date.now()))
+    },
+  }
+}
+```
+
+### Creating a Reactive Condition
+
+```typescript
+import { type ReactiveCondition } from '@universe/notifications'
+
+export const STATUS_NOTIFICATION_ID = 'local:session:status'
+
+interface StatusState {
+  isActive: boolean
+}
+
+export function createStatusCondition(ctx: { getState: () => AppState }): ReactiveCondition<StatusState> {
+  return {
+    notificationId: STATUS_NOTIFICATION_ID,
+
+    subscribe: (onStateChange) => {
+      // Subscribe to external state changes
+      const unsubscribe = someService.addEventListener((event) => {
+        onStateChange({ isActive: event.isActive })
+      })
+      return unsubscribe
+    },
+
+    shouldShow: (state) => state.isActive === false,
+
+    createNotification: (state) => new Notification({
+      id: STATUS_NOTIFICATION_ID,
+      content: new Content({
+        style: ContentStyle.SYSTEM_BANNER,
+        title: 'Service unavailable',
+        onDismissClick: new OnClick({
+          onClick: [OnClickAction.DISMISS, OnClickAction.ACK],
+        }),
+      }),
+    }),
+  }
+}
+```
+
+### Custom Renderer with Notification Routing
+
+```typescript
+import { createNotificationRenderer } from '@universe/notifications'
+
+function isMyCustomNotification(notification: InAppNotification): boolean {
+  return notification.id === 'local:my_custom'
+}
+
+const renderer = createNotificationRenderer({
+  canRender: (notification) => {
+    // Only one modal at a time
+    if (notification.content?.style === ContentStyle.MODAL) {
+      return !hasActiveModal()
+    }
+    return true
+  },
+
+  render: (notification) => {
+    // Route to appropriate renderer
+    if (isMyCustomNotification(notification)) {
+      return renderMyCustomModal(notification)
+    }
+    return renderDefaultNotification(notification)
+  },
+})
+```
+
+## Testing
+
+### Mock Data Source
+
+```typescript
+function createMockDataSource(): NotificationDataSource & {
+  emit: (notifications: InAppNotification[]) => void
+} {
+  let callback: ((notifications: InAppNotification[], source: string) => void) | null = null
+
+  return {
+    start: (onNotifications) => { callback = onNotifications },
+    stop: async () => { callback = null },
+    emit: (notifications) => callback?.(notifications, 'mock'),
+  }
+}
+
+// In tests
+const mockDataSource = createMockDataSource()
+const service = createNotificationService({
+  dataSources: [mockDataSource],
+  // ...
+})
+
+await service.initialize()
+mockDataSource.emit([testNotification])
+```
+
+### Mock Tracker
+
+```typescript
+function createMockTracker(): NotificationTracker {
+  const processed = new Set<string>()
+
+  return {
+    isProcessed: async (id) => processed.has(id),
+    getProcessedIds: async () => processed,
+    track: async (id) => { processed.add(id) },
+    cleanup: async () => { processed.clear() },
+  }
+}
+```
+
+### Mock Renderer
+
+```typescript
+function createMockRenderer(): NotificationRenderer & {
+  rendered: InAppNotification[]
+} {
+  const rendered: InAppNotification[] = []
+
+  return {
+    rendered,
+    canRender: () => true,
+    render: (notification) => {
+      rendered.push(notification)
+      return () => {
+        const index = rendered.indexOf(notification)
+        if (index > -1) rendered.splice(index, 1)
+      }
+    },
+  }
+}
+```
+
+## Troubleshooting
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Notification re-appears after dismiss | Using `DISMISS` without `ACK` | Add `ACK` to the onClick array |
+| Notification never shows | Already tracked as processed | Clear storage or use a new notification ID |
+| Chained notification not showing | Target not in chained map | Ensure API returns all chain members in same response |
+| Multiple modals appearing | `canRender` not checking active modals | Implement modal count check in renderer |
+| Session notification persists | Using `local:` instead of `local:session:` | Use `local:session:` prefix for session-scoped notifications |
+| Reactive condition not updating | Not calling `onStateChange` | Ensure subscribe callback is invoked on state changes |
+

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@luxexchange/notifications",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "dependencies": {
     "@bufbuild/protobuf": "1.10.0",
     "@tanstack/react-query": "5.90.20",
-    "@uniswap/client-notification-service": "0.0.11",
+    "@luxamm/client-notification-service": "0.0.114",
+    "@luxexchange/api": "workspace:*",
     "ms": "2.1.3",
     "react": "19.0.3",
     "react-i18next": "14.1.0",
@@ -12,7 +13,7 @@
   },
   "devDependencies": {
     "@types/node": "22.13.1",
-    "@typescript/native-preview": "7.0.0-dev.20260108.1",
+    "@typescript/native-preview": "7.0.0-dev.20260311.1",
     "@luxfi/eslint-config": "workspace:^",
     "@vitest/coverage-v8": "3.2.1",
     "depcheck": "1.4.7",
@@ -30,8 +31,7 @@
     "lint:fix": "nx lint:fix notifications",
     "typecheck": "nx typecheck notifications",
     "typecheck:tsgo": "nx typecheck:tsgo notifications",
-    "test": "nx test notifications",
-    "test:coverage": "nx test:coverage notifications"
+    "test": "nx test notifications"
   },
   "nx": {
     "includedScripts": []

package/project.json

@@ -1,5 +1,5 @@
 {
-  "name": "@luxfi/notifications",
+  "name": "@luxexchange/notifications",
   "$schema": "../../node_modules/nx/schemas/project-schema.json",
   "sourceRoot": "pkgs/notifications/src",
   "projectType": "library",
@@ -19,12 +19,6 @@
       "options": {
         "cwd": "{projectRoot}"
       }
-    },
-    "test:coverage": {
-      "command": "vitest run --coverage",
-      "options": {
-        "cwd": "{projectRoot}"
-      }
     }
   }
 }

package/src/notification-data-source/NotificationDataSource.ts

@@ -5,4 +5,6 @@ export interface NotificationDataSource {
   start(onNotifications: (notifications: InAppNotification[], source: string) => void): void
   // Stop receiving notifications and cleanup
   stop(): Promise<void>
+  // Trigger an immediate poll outside of the normal interval (optional)
+  refresh?(): Promise<void>
 }

package/src/notification-data-source/getNotificationQueryOptions.ts

@@ -1,11 +1,11 @@
 import { toPlainMessage } from '@bufbuild/protobuf'
 import { queryOptions } from '@tanstack/react-query'
-import { PlatformType } from '@uniswap/client-notification-service/dist/uniswap/notificationservice/v1/api_pb'
+import { PlatformType } from '@luxamm/client-notification-service/dist/uniswap/notificationservice/v1/api_pb'
 import type { InAppNotification, NotificationsApiClient } from '@luxexchange/api'
-import { getLogger } from '@luxfi/utilities/src/logger/logger'
-import { ReactQueryCacheKey } from '@luxfi/utilities/src/reactQuery/cache'
-import { type QueryOptionsResult } from '@luxfi/utilities/src/reactQuery/queryOptions'
-import { ONE_MINUTE_MS } from '@luxfi/utilities/src/time/time'
+import { getLogger } from 'utilities/src/logger/logger'
+import { ReactQueryCacheKey } from 'utilities/src/reactQuery/cache'
+import { type QueryOptionsResult } from 'utilities/src/reactQuery/queryOptions'
+import { ONE_MINUTE_MS } from 'utilities/src/time/time'
 
 const DEFAULT_POLL_INTERVAL_MS = 2 * ONE_MINUTE_MS
 

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

@@ -1,7 +1,7 @@
 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 { getLogger } from '@luxfi/utilities/src/logger/logger'
+import { getLogger } from 'utilities/src/logger/logger'
 
 interface CreateIntervalNotificationDataSourceContext {
   pollIntervalMs: number
@@ -69,5 +69,9 @@ export function createIntervalNotificationDataSource(
     currentCallback = null
   }
 
-  return createNotificationDataSource({ start, stop })
+  const refresh = async (): Promise<void> => {
+    await pollAndEmit('refresh')
+  }
+
+  return { ...createNotificationDataSource({ start, stop }), refresh }
 }

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

@@ -2,7 +2,7 @@ import {
   Content,
   Metadata,
   Notification,
-} from '@uniswap/client-notification-service/dist/uniswap/notificationservice/v1/api_pb'
+} from '@luxamm/client-notification-service/dist/uniswap/notificationservice/v1/api_pb'
 import type { InAppNotification } from '@luxexchange/api'
 import { ContentStyle } from '@luxexchange/api'
 import {

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

@@ -2,7 +2,7 @@ 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'
+import { getLogger } from 'utilities/src/logger/logger'
 
 /**
  * Configuration for a single trigger condition.

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

@@ -1,5 +1,5 @@
-import { type InAppNotification } from '@luxfi/api'
-import { type NotificationDataSource } from '@luxfi/notifications/src/notification-data-source/NotificationDataSource'
+import { type InAppNotification } from '@luxexchange/api'
+import { type NotificationDataSource } from '@luxexchange/notifications/src/notification-data-source/NotificationDataSource'
 
 /**
  * Basic implementation of the NotificationDataSource interface.

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

@@ -5,12 +5,12 @@ import {
   Metadata,
   Notification,
   PlatformType,
-} from '@uniswap/client-notification-service/dist/uniswap/notificationservice/v1/api_pb'
+} from '@luxamm/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 { ReactQueryCacheKey } from 'utilities/src/reactQuery/cache'
 import { afterEach, beforeEach, describe, expect, it, type Mock, vi } from 'vitest'
 
 function createMockNotification(id: string): InAppNotification {

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

@@ -1,9 +1,9 @@
 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'
+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 { getLogger } from 'utilities/src/logger/logger'
+import { type QueryOptionsResult } from 'utilities/src/reactQuery/queryOptions'
 
 interface CreatePollingNotificationDataSourceContext<TQueryKey extends QueryKey = QueryKey> {
   queryClient: QueryClient

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

@@ -3,7 +3,7 @@ import { createNotificationDataSource } from '@luxexchange/notifications/src/not
 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'
+import { getLogger } from 'utilities/src/logger/logger'
 
 export interface CreateReactiveDataSourceContext<TState> {
   /** The reactive condition that determines when to show the notification */

package/src/notification-processor/NotificationProcessor.ts

@@ -1,4 +1,4 @@
-import { type InAppNotification } from '@luxfi/api'
+import { type InAppNotification } from '@luxexchange/api'
 
 /**
  * Result of processing notifications, separating primary notifications

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

@@ -1,6 +1,6 @@
-import { ContentStyle, type InAppNotification, OnClickAction } from '@luxfi/api'
-import { createBaseNotificationProcessor } from '@luxfi/notifications/src/notification-processor/implementations/createBaseNotificationProcessor'
-import type { NotificationTracker } from '@luxfi/notifications/src/notification-tracker/NotificationTracker'
+import { ContentStyle, type InAppNotification, OnClickAction } from '@luxexchange/api'
+import { createBaseNotificationProcessor } from '@luxexchange/notifications/src/notification-processor/implementations/createBaseNotificationProcessor'
+import type { NotificationTracker } from '@luxexchange/notifications/src/notification-tracker/NotificationTracker'
 import { describe, expect, it } from 'vitest'
 
 describe('createBaseNotificationProcessor', () => {

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

@@ -5,7 +5,7 @@ import {
   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'
+import { getLogger } from 'utilities/src/logger/logger'
 
 /**
  * Creates a base notification processor that implements style-based deduplication and limiting,
@@ -43,12 +43,14 @@ export function createBaseNotificationProcessor(tracker: NotificationTracker): N
         }
       }
 
-      // Step 3: Filter out notifications that are locally tracked or don't have DISMISS action
+      // Step 3: Filter out notifications that are locally tracked or don't have DISMISS action.
+      // Required cards are exempt from the DISMISS check — they self-dismiss when their
+      // underlying data condition resolves (e.g. wallet receives funds).
       const filteredPrimary = primaryNotifications.filter((notification) => {
         if (processedIds.has(notification.id)) {
           return false
         }
-        if (!hasDismissAction(notification)) {
+        if (!isRequiredCard(notification) && !hasDismissAction(notification)) {
           getLogger().warn(
             'createBaseNotificationProcessor',
             'process',
@@ -64,7 +66,7 @@ export function createBaseNotificationProcessor(tracker: NotificationTracker): N
         if (processedIds.has(notification.id)) {
           return false
         }
-        if (!hasDismissAction(notification)) {
+        if (!isRequiredCard(notification) && !hasDismissAction(notification)) {
           getLogger().warn(
             'createBaseNotificationProcessor',
             'process',
@@ -93,6 +95,19 @@ export function createBaseNotificationProcessor(tracker: NotificationTracker): N
   })
 }
 
+/**
+ * Returns true if the notification is a required card — one that self-dismisses when its
+ * underlying data condition resolves rather than via explicit user action.
+ */
+function isRequiredCard(notification: InAppNotification): boolean {
+  try {
+    const extra = notification.content?.extra ? JSON.parse(notification.content.extra) : {}
+    return extra.cardType === 'required'
+  } catch {
+    return false
+  }
+}
+
 /**
  * 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.

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

@@ -1,5 +1,5 @@
-import type { InAppNotification } from '@luxfi/api'
-import { createNotificationProcessor } from '@luxfi/notifications/src/notification-processor/implementations/createNotificationProcessor'
+import type { InAppNotification } from '@luxexchange/api'
+import { createNotificationProcessor } from '@luxexchange/notifications/src/notification-processor/implementations/createNotificationProcessor'
 import { describe, expect, it, vi } from 'vitest'
 
 describe('createNotificationProcessor', () => {

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

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

package/src/notification-renderer/NotificationRenderer.ts

@@ -1,4 +1,4 @@
-import { type InAppNotification } from '@luxfi/api'
+import { type InAppNotification } from '@luxexchange/api'
 
 export interface NotificationRenderer {
   // Render a notification and return cleanup function

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

@@ -1,7 +1,7 @@
 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'
+import { Button, Flex, IconButton, styled, Text, useIsDarkMode } from 'ui/src'
+import { X } from 'ui/src/components/icons/X'
+import { zIndexes } from 'ui/src/theme'
 
 const BANNER_WIDTH = 260
 const BANNER_HEIGHT = 150

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

@@ -1,4 +1,4 @@
-import { BackgroundType } from '@uniswap/client-notification-service/dist/uniswap/notificationservice/v1/api_pb'
+import { BackgroundType } from '@luxamm/client-notification-service/dist/uniswap/notificationservice/v1/api_pb'
 import type { InAppNotification } from '@luxexchange/api'
 import {
   BannerTemplate,

package/src/notification-renderer/implementations/createNotificationRenderer.ts

@@ -1,5 +1,5 @@
-import { type InAppNotification } from '@luxfi/api'
-import { type NotificationRenderer } from '@luxfi/notifications/src/notification-renderer/NotificationRenderer'
+import { type InAppNotification } from '@luxexchange/api'
+import { type NotificationRenderer } from '@luxexchange/notifications/src/notification-renderer/NotificationRenderer'
 
 export function createNotificationRenderer(ctx: {
   render: (notification: InAppNotification) => () => void

package/src/notification-renderer/utils/iconUtils.ts

@@ -1,21 +1,21 @@
-import type { GeneratedIcon } from '@luxfi/ui/src/components/factories/createIcon'
-import { AlertTriangle } from '@luxfi/ui/src/components/icons/AlertTriangle'
-import { Bell } from '@luxfi/ui/src/components/icons/Bell'
-import { Chart } from '@luxfi/ui/src/components/icons/Chart'
-import { CheckCircleFilled } from '@luxfi/ui/src/components/icons/CheckCircleFilled'
-import { Coin } from '@luxfi/ui/src/components/icons/Coin'
-import { CoinConvert } from '@luxfi/ui/src/components/icons/CoinConvert'
-import { EthMini } from '@luxfi/ui/src/components/icons/EthMini'
-import { Gas } from '@luxfi/ui/src/components/icons/Gas'
-import { Gift } from '@luxfi/ui/src/components/icons/Gift'
-import { Globe } from '@luxfi/ui/src/components/icons/Globe'
-import { InfoCircleFilled } from '@luxfi/ui/src/components/icons/InfoCircleFilled'
-import { Lightning } from '@luxfi/ui/src/components/icons/Lightning'
-import { Rocket } from '@luxfi/ui/src/components/icons/Rocket'
-import { SendAction } from '@luxfi/ui/src/components/icons/SendAction'
-import { ShieldCheck } from '@luxfi/ui/src/components/icons/ShieldCheck'
-import { Star } from '@luxfi/ui/src/components/icons/Star'
-import { Wallet } from '@luxfi/ui/src/components/icons/Wallet'
+import type { GeneratedIcon } from 'ui/src/components/factories/createIcon'
+import { AlertTriangle } from 'ui/src/components/icons/AlertTriangle'
+import { Bell } from 'ui/src/components/icons/Bell'
+import { Chart } from 'ui/src/components/icons/Chart'
+import { CheckCircleFilled } from 'ui/src/components/icons/CheckCircleFilled'
+import { Coin } from 'ui/src/components/icons/Coin'
+import { CoinConvert } from 'ui/src/components/icons/CoinConvert'
+import { EthMini } from 'ui/src/components/icons/EthMini'
+import { Gas } from 'ui/src/components/icons/Gas'
+import { Gift } from 'ui/src/components/icons/Gift'
+import { Globe } from 'ui/src/components/icons/Globe'
+import { InfoCircleFilled } from 'ui/src/components/icons/InfoCircleFilled'
+import { Lightning } from 'ui/src/components/icons/Lightning'
+import { Rocket } from 'ui/src/components/icons/Rocket'
+import { SendAction } from 'ui/src/components/icons/SendAction'
+import { ShieldCheck } from 'ui/src/components/icons/ShieldCheck'
+import { Star } from 'ui/src/components/icons/Star'
+import { Wallet } from 'ui/src/components/icons/Wallet'
 
 /**
  * Map of custom icon names to their corresponding icon components.

package/src/notification-service/NotificationService.ts

@@ -42,6 +42,8 @@ export interface NotificationService {
    * @param notificationId - ID of the notification that was shown
    */
   onNotificationShown(notificationId: string): void
+  // Trigger an immediate re-poll on all data sources that support it
+  refresh(): Promise<void>
   // Cleanup and teardown
   destroy(): void
 }

package/src/notification-service/implementations/createNotificationService.test.ts

@@ -1,13 +1,13 @@
-import { type InAppNotification, OnClickAction } from '@luxfi/api'
-import type { NotificationDataSource } from '@luxfi/notifications/src/notification-data-source/NotificationDataSource'
-import type { NotificationProcessor } from '@luxfi/notifications/src/notification-processor/NotificationProcessor'
-import type { NotificationRenderer } from '@luxfi/notifications/src/notification-renderer/NotificationRenderer'
-import { createNotificationService } from '@luxfi/notifications/src/notification-service/implementations/createNotificationService'
+import { type InAppNotification, OnClickAction } from '@luxexchange/api'
+import type { NotificationDataSource } from '@luxexchange/notifications/src/notification-data-source/NotificationDataSource'
+import type { NotificationProcessor } from '@luxexchange/notifications/src/notification-processor/NotificationProcessor'
+import type { NotificationRenderer } from '@luxexchange/notifications/src/notification-renderer/NotificationRenderer'
+import { createNotificationService } from '@luxexchange/notifications/src/notification-service/implementations/createNotificationService'
 import type {
   NotificationTracker,
   TrackingMetadata,
-} from '@luxfi/notifications/src/notification-tracker/NotificationTracker'
-import { sleep } from '@luxfi/utilities/src/time/timing'
+} from '@luxexchange/notifications/src/notification-tracker/NotificationTracker'
+import { sleep } from 'utilities/src/time/timing'
 import { describe, expect, it, vi } from 'vitest'
 
 describe('createNotificationService', () => {

package/src/notification-service/implementations/createNotificationService.ts

@@ -5,7 +5,7 @@ import {
   type NotificationServiceConfig,
 } from '@luxfi/notifications/src/notification-service/NotificationService'
 import ms from 'ms'
-import { getLogger } from '@luxfi/utilities/src/logger/logger'
+import { getLogger } from 'utilities/src/logger/logger'
 
 // Module-level singletons to track notification telemetry across service recreations.
 // This prevents duplicate telemetry events when the service is destroyed
@@ -329,6 +329,10 @@ export function createNotificationService(config: NotificationServiceConfig): No
       })
     },
 
+    async refresh(): Promise<void> {
+      await Promise.all(dataSources.map((dataSource) => dataSource.refresh?.()))
+    },
+
     destroy(): void {
       // Clean up old tracked notifications on teardown
       const cleanupThreshold = Date.now() - CLEANUP_OLDER_THAN_MS

package/src/notification-telemetry/NotificationTelemetry.ts

@@ -1,4 +1,4 @@
-import { type ContentStyle } from '@luxfi/api'
+import { type ContentStyle } from '@luxexchange/api'
 
 /**
  * Telemetry interface for tracking notification lifecycle events

package/src/notification-telemetry/implementations/createNotificationTelemetry.test.ts

@@ -1,5 +1,5 @@
-import { ContentStyle } from '@luxfi/api'
-import { createNotificationTelemetry } from '@luxfi/notifications/src/notification-telemetry/implementations/createNotificationTelemetry'
+import { ContentStyle } from '@luxexchange/api'
+import { createNotificationTelemetry } from '@luxexchange/notifications/src/notification-telemetry/implementations/createNotificationTelemetry'
 import { describe, expect, it, vi } from 'vitest'
 
 describe('createNotificationTelemetry', () => {

package/src/notification-telemetry/implementations/createNotificationTelemetry.ts

@@ -1,5 +1,5 @@
-import { type NotificationTelemetry } from '@luxfi/notifications/src/notification-telemetry/NotificationTelemetry'
-import { formatNotificationType } from '@luxfi/notifications/src/utils/formatNotificationType'
+import { type NotificationTelemetry } from '@luxexchange/notifications/src/notification-telemetry/NotificationTelemetry'
+import { formatNotificationType } from '@luxexchange/notifications/src/utils/formatNotificationType'
 
 /**
  * Basic implementation of the NotificationTelemetry interface.

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

@@ -1,7 +1,7 @@
 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 type { NotificationsApiClient } from '@luxexchange/api'
+import { createApiNotificationTracker } from '@luxexchange/notifications/src/notification-tracker/implementations/createApiNotificationTracker'
+import type { TrackingMetadata } from '@luxexchange/notifications/src/notification-tracker/NotificationTracker'
 import { describe, expect, it, type Mock, vi } from 'vitest'
 
 describe('createApiNotificationTracker', () => {

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

@@ -1,12 +1,12 @@
 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 type { NotificationsApiClient } from '@luxexchange/api'
+import { createNotificationTracker } from '@luxexchange/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'
+} from '@luxexchange/notifications/src/notification-tracker/NotificationTracker'
+import { getLogger } from 'utilities/src/logger/logger'
+import { ReactQueryCacheKey } from 'utilities/src/reactQuery/cache'
 
 /**
  * Context for creating an API-based notification tracker
@@ -34,8 +34,8 @@ export interface ApiNotificationTrackerContext {
  *
  * Example usage:
  * ```typescript
- * import { createApiNotificationTracker } from '@luxfi/notifications'
- * import { createNotificationsApiClient } from '@luxfi/api'
+ * import { createApiNotificationTracker } from '@luxexchange/notifications'
+ * import { createNotificationsApiClient } from '@luxexchange/api'
  *
  * const apiClient = createNotificationsApiClient({
  *   fetchClient: myFetchClient,

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

@@ -1,15 +1,15 @@
-import { createNotificationTracker } from '@luxfi/notifications/src/notification-tracker/implementations/createNotificationTracker'
+import { createNotificationTracker } from '@luxexchange/notifications/src/notification-tracker/implementations/createNotificationTracker'
 import {
   NotificationTracker,
   TrackingMetadata,
-} from '@luxfi/notifications/src/notification-tracker/NotificationTracker'
+} from '@luxexchange/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'
+ * import { createNoopNotificationTracker } from '@luxexchange/notifications'
  *
  * const tracker = createNoopNotificationTracker()
  *

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

@@ -1,7 +1,7 @@
 import {
   NotificationTracker,
   TrackingMetadata,
-} from '@luxfi/notifications/src/notification-tracker/NotificationTracker'
+} from '@luxexchange/notifications/src/notification-tracker/NotificationTracker'
 
 /**
  * Basic implementation of the NotificationTracker interface.

package/src/utils/formatNotificationType.test.ts

@@ -1,5 +1,5 @@
-import { ContentStyle } from '@luxfi/api'
-import { formatNotificationType } from '@luxfi/notifications/src/utils/formatNotificationType'
+import { ContentStyle } from '@luxexchange/api'
+import { formatNotificationType } from '@luxexchange/notifications/src/utils/formatNotificationType'
 import { describe, expect, it } from 'vitest'
 
 describe('formatNotificationType', () => {

package/src/utils/formatNotificationType.ts

@@ -1,4 +1,4 @@
-import { ContentStyle } from '@luxfi/api'
+import { ContentStyle } from '@luxexchange/api'
 
 /**
  * Converts a ContentStyle enum value to a human-readable string for logging/telemetry

package/tsconfig.json

@@ -1,24 +1,34 @@
 {
   "extends": "../../config/tsconfig/app.json",
-  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.json", "../../index.d.ts"],
-  "exclude": ["src/**/*.spec.ts", "src/**/*.spec.tsx", "src/**/*.test.ts", "src/**/*.test.tsx"],
+  "include": [
+    "src/**/*.ts",
+    "src/**/*.tsx",
+    "src/**/*.json",
+    "../../index.d.ts"
+  ],
+  "exclude": [
+    "src/**/*.spec.ts",
+    "src/**/*.spec.tsx",
+    "src/**/*.test.ts",
+    "src/**/*.test.tsx"
+  ],
   "compilerOptions": {
     "emitDeclarationOnly": true,
     "noEmit": false,
     "paths": {
-      "@universe/notifications/*": ["./*"]
+      "@luxexchange/notifications/*": ["./*"]
     },
     "types": ["node", "vitest/globals"]
   },
   "references": [
     {
-      "path": "../utilities"
+      "path": "../ui"
     },
     {
       "path": "../api"
     },
     {
-      "path": "../ui"
+      "path": "../eslint-config"
     }
   ]
 }

package/tsconfig.lint.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "preserveSymlinks": true
+  },
+  "include": ["**/*.ts", "**/*.tsx", "**/*.json"],
+  "exclude": ["node_modules"]
+}

package/vitest-setup.ts

@@ -0,0 +1 @@
+export {}

package/vitest.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    setupFiles: ['./vitest-setup.ts'],
+    coverage: {
+      exclude: ['**/__generated__/**', '**/node_modules/**', '**/dist/**', '**/*.config.*', '**/scripts/**'],
+    },
+  },
+  resolve: {
+    extensions: ['.web.ts', '.web.tsx', '.ts', '.tsx', '.js', '.jsx', '.json'],
+  },
+})