# Notifications

## Overview

This journey covers the in-app notification system that keeps customers informed about important events related to their account, orders, billing, and services. Notifications are stored in the portal's own database and are triggered by events from Salesforce (via Platform Events), WHMCS (via the fulfillment process), and the portal itself. Customers access notifications through a bell icon in the navigation bar.

## Portal Flow

### The Notification Bell

1. The **bell icon** appears in the top navigation bar on every page when the customer is logged in.
2. When there are **unread notifications**, a badge appears on the bell showing the count (e.g., "3"). If the count exceeds 9, it shows "9+."
3. The unread count refreshes automatically every 60 seconds.
4. Clicking the bell opens a **dropdown panel**.

### Notification Dropdown

1. Clicking the bell opens a dropdown showing the most recent 10 notifications (both read and unread).
2. Each notification shows:
   - An **icon** indicating the type (green checkmark for positive events, amber warning for issues, blue info for general updates)
   - The notification **title** (bold for unread, normal weight for read)
   - A short **message** with details (up to 2 lines)
   - A **relative timestamp** (e.g., "2 hours ago")
   - An **unread indicator** (small blue dot) for notifications that haven't been read
3. At the top of the dropdown, a **"Mark all read"** button appears when there are unread notifications.
4. Each notification can be individually **dismissed** using an X button that appears on hover.
5. Clicking a notification:
   - Marks it as read
   - If the notification has an action link, navigates to the relevant page
6. At the bottom of the dropdown, a **"View all notifications"** link navigates to the full notifications page (`/account/notifications`).
7. The dropdown closes when clicking outside it or pressing the Escape key.

### Notification Types

The following notification types can appear in the portal:

| Type                   | Title                                      | Triggered By                   | Links To                   |
| ---------------------- | ------------------------------------------ | ------------------------------ | -------------------------- |
| Internet Eligible      | "Good news! Internet service is available" | Eligibility check completed    | Internet services page     |
| Internet Ineligible    | "Internet service not available"           | Eligibility check completed    | Support page               |
| ID Verified            | "ID verification complete"                 | Agent approves residence card  | Continue checkout          |
| ID Rejected            | "ID verification requires attention"       | Agent rejects residence card   | Verification resubmit page |
| Order Approved         | "Order approved"                           | Order approved in Salesforce   | Orders page                |
| Service Activated      | "Service activated"                        | WHMCS provisioning complete    | Services page              |
| Order Failed           | "Order requires attention"                 | Fulfillment error              | Support page               |
| Cancellation Scheduled | "Cancellation scheduled"                   | Customer requests cancellation | Services page              |
| Invoice Due            | "Invoice due"                              | Invoice due within 7 days      | Invoices page              |

### How Notifications Are Triggered

**From Salesforce (via Platform Events):**

- When a Salesforce agent updates the `Internet_Eligibility_Status__c` field on an Account to "Eligible" or "Ineligible," a Platform Event fires. The portal receives this event and creates a notification.
- When a Salesforce agent updates the `Id_Verification_Status__c` field to "Verified" or "Rejected," the same mechanism creates a notification.
- Notifications are only created for **final states** (Eligible/Ineligible, Verified/Rejected) -- intermediate states like "Pending" or "Submitted" do not generate notifications.

**From the fulfillment process:**

- When an order is approved, activated, or fails during the fulfillment workflow, the portal creates a notification.
- When a customer requests a cancellation (internet or SIM), a "Cancellation scheduled" notification is created.

**From the dashboard check:**

- When the customer loads their dashboard, the portal checks if any invoices are due within 7 days or overdue. If so, an "Invoice due" notification is created.

### Deduplication

The notification system prevents duplicate notifications:

- Most notification types use a 1-hour deduplication window -- the same type and source combination will not create a second notification within 1 hour.
- Invoice due, payment method expiring, and system announcements use a 24-hour deduplication window.

### Reading and Dismissing Notifications

- **Mark as read**: Click any notification to mark it as read. The bold text becomes normal and the blue dot disappears.
- **Mark all as read**: Click "Mark all read" at the top of the dropdown to mark all notifications as read at once.
- **Dismiss**: Hover over a notification and click the X button to dismiss it. Dismissed notifications no longer appear in the list.

## What Happens in WHMCS

- WHMCS does not store portal notifications directly.
- However, WHMCS events can **indirectly trigger** notifications. For example:
  - When the fulfillment process provisions a service in WHMCS and succeeds, a "Service activated" notification is created.
  - When a WHMCS invoice is approaching its due date, the dashboard check creates an "Invoice due" notification.

## What Happens in Salesforce

- Salesforce events trigger notifications via **Platform Events**:
  - The `Account_Update__e` Platform Event fires when eligibility or verification fields change on the Account.
  - The portal's event subscriber receives this, checks which fields changed, and creates the appropriate notification.
- Salesforce does **not** store portal notification records. Notifications live in the portal's own database.
- To verify Salesforce-triggered notifications, change the relevant field on the Account in Salesforce and check that the notification appears in the portal.

## Key Things to Verify

- **Bell icon and count**: Verify the bell icon shows the correct unread count. Create a trigger event (e.g., approve an ID verification in Salesforce) and verify the count increments.
- **Dropdown displays correctly**: Click the bell and verify notifications appear with correct titles, messages, icons, and timestamps.
- **Mark as read**: Click a notification and verify the unread indicator disappears and the text style changes from bold to normal.
- **Mark all as read**: Click "Mark all read" and verify all unread indicators disappear and the badge count resets to zero.
- **Dismiss**: Hover over a notification, click X, and verify it disappears from the list.
- **Navigation**: Click a notification with an action link (e.g., "ID verification complete") and verify it navigates to the correct page (e.g., the verification page).
- **Eligibility notifications**: Change `Internet_Eligibility_Status__c` to "Eligible" in Salesforce and verify a "Good news! Internet service is available" notification appears in the portal.
- **Verification notifications**: Change `Id_Verification_Status__c` to "Rejected" in Salesforce and verify a "ID verification requires attention" notification appears.
- **Order notifications**: Process an order through fulfillment and verify "Order approved" and "Service activated" notifications appear at the appropriate stages.
- **Invoice due notification**: Ensure a customer has an invoice due within 7 days, load the dashboard, and verify an "Invoice due" notification is created.
- **Deduplication**: Trigger the same event twice within an hour and verify only one notification is created.
- **Real-time delivery**: When a Salesforce event triggers a notification, it should appear in the portal within a few seconds without needing a page refresh (via server-sent events).
