[Frontend/Backend] Native Web Push Notifications & Telegram/Discord Stream Activity Bot #1474

Overview & Background

Users cannot keep browser tabs open continuously to monitor payment streams. Critical events—such as receiving a new stream, reaching a vesting cliff, approaching stream depletion (runway < 24 hours), or receiving a withdrawal confirmation—require direct external communication channels. Adding native Web Push notifications and an official Telegram/Discord alerting bot allows users to receive instant notifications on their preferred devices.

Detailed Problem Statement

1. Missed Low-Runway Warnings:
   • Stream senders frequently fail to notice when an active payroll stream is about to run out of funds, resulting in unexpected stream halts and payroll delays.
2. Delayed Cliff & Vesting Discovery:
   • Recipients entitled to claim large token tranches upon cliff arrival often do not know when their tokens become claimable without manually checking the site.
3. No Direct Mobile Alerting Channel:
   • Without mobile push or chat bot notifications, mobile users miss real-time payment activities.

Technical Specification & Architecture

1. Web Push Notification Integration (VAPID & Service Worker)

• Frontend:
  • Register Service Worker public/sw.js handling push and notificationclick events.
  • Expose Notification Permission Prompt component in UI settings:

    const subscription = await registration.pushManager.subscribe({
      userVisibleOnly: true,
      applicationServerKey: urlBase64ToUint8Array(VAPID_PUBLIC_KEY),
    });

  • Send push subscription credentials to POST /api/v1/notifications/subscribe.
• Backend:
  • Implement web-push delivery worker triggered by stream lifecycle events.

2. Telegram & Discord Alerting Bot

• Provide /settings/notifications page allowing users to link their account via a one-time verification code:
  • Telegram Bot: User starts @FlowFiAlertsBot /link <code> to subscribe their chat ID to their Stellar address.
  • Discord Webhook: User pastes custom Discord webhook URL for DAO channel alerts.
• Event Triggers:
  • STREAM_CREATED: "🌊 You are receiving a new stream of 500 USDC/mo from GABC...!"
  • CLIFF_REACHED: "🎯 Vesting cliff reached! 10,000 FLOW tokens are now claimable."
  • RUNWAY_WARNING: "⚠️ Warning: Stream #42 has less than 24 hours of runway remaining. Refuel now."
  • TOKENS_CLAIMED: "✅ Successfully withdrawn 250 USDC to your wallet."

Target Files

• frontend/public/sw.js
• frontend/src/app/settings/notifications/page.tsx
• frontend/src/components/notifications/PushNotificationToggle.tsx
• backend/src/services/notification.service.ts
• backend/src/workers/notification-bot.worker.ts
• backend/prisma/schema.prisma

Acceptance Criteria

• Users can subscribe to native browser Web Push notifications with valid VAPID keys.
• Account linking flow securely associates Telegram Chat IDs or Discord Webhooks with a verified Stellar address.
• Background worker dispatches alerts for low runway, cliff reached, and stream receipt events.
• Users can configure notification granular preferences (enable/disable specific event types).
• Service worker opens relevant stream detail URL when notification banner is clicked.