@l.x/notifications 1.0.3 → 1.0.5

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/LICENSE

@@ -0,0 +1,122 @@
+Lux Ecosystem License
+Version 1.2, December 2025
+
+Copyright (c) 2020-2025 Lux Industries Inc.
+All rights reserved.
+
+TECHNOLOGY PORTFOLIO - PATENT APPLICATIONS PLANNED
+Contact: licensing@lux.network
+
+================================================================================
+                          TERMS AND CONDITIONS
+================================================================================
+
+1. DEFINITIONS
+
+   "Lux Primary Network" means the official Lux blockchain with Network ID=1
+   and EVM Chain ID=96369.
+   
+   "Authorized Network" means the Lux Primary Network, official testnets/devnets,
+   and any L1/L2/L3 chain descending from the Lux Primary Network.
+   
+   "Descending Chain" means an L1/L2/L3 chain built on, anchored to, or deriving
+   security from the Lux Primary Network or its authorized testnets.
+   
+   "Research Use" means non-commercial academic research, education, personal
+   study, or evaluation purposes.
+   
+   "Commercial Use" means any use in connection with a product or service
+   offered for sale or fee, internal use by a for-profit entity, or any use
+   to generate revenue.
+
+2. GRANT OF LICENSE
+
+   Subject to these terms, Lux Industries Inc grants you a non-exclusive,
+   royalty-free license to:
+   
+   (a) Use for Research Use without restriction;
+   
+   (b) Operate on the Lux Primary Network (Network ID=1, EVM Chain ID=96369);
+   
+   (c) Operate on official Lux testnets and devnets;
+   
+   (d) Operate L1/L2/L3 chains descending from the Lux Primary Network;
+   
+   (e) Build applications within the Lux ecosystem;
+   
+   (f) Contribute improvements back to the original repositories.
+
+3. RESTRICTIONS
+
+   Without a commercial license from Lux Industries Inc, you may NOT:
+   
+   (a) Fork the Lux Network or any Lux software;
+   
+   (b) Create competing networks not descending from Lux Primary Network;
+   
+   (c) Use for Commercial Use outside the Lux ecosystem;
+   
+   (d) Sublicense or transfer rights outside the Lux ecosystem;
+   
+   (e) Use to create competing blockchain networks, exchanges, custody
+       services, or cryptographic systems outside the Lux ecosystem.
+
+4. NO FORKS POLICY
+
+   Lux Industries Inc maintains ZERO TOLERANCE for unauthorized forks.
+   Any fork or deployment on an unauthorized network constitutes:
+   
+   (a) Breach of this license;
+   (b) Grounds for immediate legal action.
+
+5. RIGHTS RESERVATION
+
+   All rights not explicitly granted are reserved by Lux Industries Inc.
+   
+   We plan to apply for patent protection for the technology in this
+   repository. Any implementation outside the Lux ecosystem may require
+   a separate commercial license.
+
+6. DISCLAIMER OF WARRANTY
+
+   THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+7. LIMITATION OF LIABILITY
+
+   IN NO EVENT SHALL LUX INDUSTRIES INC BE LIABLE FOR ANY CLAIM, DAMAGES
+   OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+   ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE.
+
+8. TERMINATION
+
+   This license terminates immediately upon any breach, including but not
+   limited to deployment on unauthorized networks or creation of forks.
+
+9. GOVERNING LAW
+
+   This License shall be governed by the laws of the State of Delaware.
+
+10. COMMERCIAL LICENSING
+
+    For commercial use outside the Lux ecosystem:
+    
+    Lux Industries Inc.
+    Email: licensing@lux.network
+    Subject: Commercial License Request
+
+================================================================================
+                              TL;DR
+================================================================================
+
+- Research/academic use = OK
+- Lux Primary Network (Network ID=1, Chain ID=96369) = OK
+- L1/L2/L3 chains descending from Lux Primary Network = OK
+- Commercial products outside Lux ecosystem = Contact licensing@lux.network
+- Forks = Absolutely not
+
+================================================================================
+
+See LP-0012 for full licensing documentation:
+https://github.com/luxfi/lps/blob/main/LPs/lp-0012-ecosystem-licensing.md

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 |
+