@luxexchange/notifications 1.0.0 → 1.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luxexchange/notifications",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "dependencies": {
     "@bufbuild/protobuf": "1.10.0",
     "@tanstack/react-query": "5.90.20",
@@ -8,12 +8,12 @@
     "ms": "2.1.3",
     "react": "19.0.3",
     "react-i18next": "14.1.0",
-    "@luxfi/ui": "^1.0.0"
+    "@luxfi/ui": "workspace:^"
   },
   "devDependencies": {
     "@types/node": "22.13.1",
     "@typescript/native-preview": "7.0.0-dev.20260108.1",
-    "@luxfi/eslint-config": "^1.0.0",
+    "@luxfi/eslint-config": "workspace:^",
     "@vitest/coverage-v8": "3.2.1",
     "depcheck": "1.4.7",
     "eslint": "8.57.1",

package/.depcheckrc

@@ -1,14 +0,0 @@
-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

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

package/README.md

@@ -1,548 +0,0 @@
-# @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/tsconfig.lint.json

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

package/vitest-setup.ts

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

package/vitest.config.ts

@@ -1,14 +0,0 @@
-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'],
-  },
-})