feat: add real-time toast notifications for ride events (draft)

Author: jxchen21

.env.example

@@ -21,8 +21,15 @@ JUNO_BASE_URL=your-juno-url
 JUNO_EMAIL_SENDER_EMAIL=bitsgood85@gmail.com
 JUNO_EMAIL_SENDER_NAME=Able Alliance
 
-# WebSocket server for real-time chat
+# WebSocket server for real-time chat and toast notifications
 NEXT_PUBLIC_WS_URL=http://localhost:4000
+# Server-to-server URL for the Next.js app to reach the websocket server
+# (e.g. http://websocket:4000 when running in Docker)
+WEBSOCKET_INTERNAL_URL=http://localhost:4000
+# Shared secret authorizing the Next.js app to push notifications via the
+# websocket server's internal /notify endpoint. Must match the value the
+# websocket server is started with.
+WEBSOCKET_INTERNAL_SECRET=dev-internal-secret-change-in-production
 
 NEXT_PUBLIC_MAPBOX_TOKEN="put token here"
 

docker-compose.yml

@@ -16,6 +16,8 @@ services:
       SUPERADMIN_LASTNAME: "Admin"
       WATCHPACK_POLLING: "true"
       NEXT_PUBLIC_WS_URL: "http://localhost:4000"
+      WEBSOCKET_INTERNAL_URL: "http://websocket:4000"
+      WEBSOCKET_INTERNAL_SECRET: "dev-internal-secret-change-in-production"
     develop:
       watch:
         - action: rebuild
@@ -93,6 +95,7 @@ services:
     environment:
       - MONGODB_URI=mongodb://mongo:27017/able-alliance?replicaSet=rs0
       - NEXTAUTH_SECRET=dev-secret-change-in-production
+      - WEBSOCKET_INTERNAL_SECRET=dev-internal-secret-change-in-production
     networks:
       - able-alliance-net
 

package-lock.json

@@ -41,6 +41,7 @@
     "next-auth": "^5.0.0-beta.30",
     "react": "19.2.3",
     "react-dom": "19.2.3",
+    "react-toast": "^1.0.3",
     "react-use": "^17.6.0",
     "socket.io": "^4.8.3",
     "socket.io-client": "^4.8.3",

package.json

@@ -1,11 +1,12 @@
 "use client";
 
 import { SessionProvider } from "next-auth/react";
+import NotificationProvider from "@/components/NotificationProvider/NotificationProvider";
 
 export default function Providers({ children }: { children: React.ReactNode }) {
   return (
     <SessionProvider refetchOnWindowFocus={false} refetchInterval={5 * 60}>
-      {children}
+      <NotificationProvider>{children}</NotificationProvider>
     </SessionProvider>
   );
 }

src/app/providers.tsx

@@ -0,0 +1,52 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+import { useSession } from "next-auth/react";
+import { io, type Socket } from "socket.io-client";
+import { ToastContainer, toast } from "react-toast";
+
+type ToastNotification = {
+  type: "success" | "error" | "info" | "warn";
+  message: string;
+};
+
+export default function NotificationProvider({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const { data: session } = useSession();
+  const socketRef = useRef<Socket | null>(null);
+
+  useEffect(() => {
+    const accessToken = session?.user?.accessToken;
+    const wsUrl = process.env.NEXT_PUBLIC_WS_URL;
+    if (!accessToken || !wsUrl || socketRef.current) return;
+
+    const socket = io(`${wsUrl}/notifications`, {
+      auth: { token: accessToken },
+      transports: ["websocket", "polling"],
+      reconnection: true,
+      reconnectionDelay: 1000,
+      reconnectionDelayMax: 30000,
+      reconnectionAttempts: 20,
+    });
+    socketRef.current = socket;
+
+    socket.on("notification", ({ type, message }: ToastNotification) => {
+      toast[type](message);
+    });
+
+    return () => {
+      socket.disconnect();
+      socketRef.current = null;
+    };
+  }, [session?.user?.accessToken]);
+
+  return (
+    <>
+      <ToastContainer position="top-right" />
+      {children}
+    </>
+  );
+}

src/components/NotificationProvider/NotificationProvider.tsx

@@ -18,6 +18,26 @@ import {
   formatEstTime,
 } from "@/utils/dateEst";
 import { EmailNotifications } from "@/server/email/EmailAction";
+import { emitToast } from "@/server/notifications/emitToast";
+
+// Runs an email send alongside the toast emit rather than before it, so a
+// slow/failing email provider can't delay real-time toast delivery.
+async function sendEmailSafely(label: string, send: () => Promise<void>) {
+  try {
+    await send();
+  } catch (error) {
+    console.error(`Failed to send ${label} email`, error);
+  }
+}
+
+// Fires email + toast without blocking the caller. Both already swallow
+// their own errors (sendEmailSafely, emitToast) — this must never make the
+// route-status API response wait on a slow/broken notification provider.
+function dispatchNotifications(tasks: Promise<void>[]) {
+  Promise.all(tasks).catch((error) => {
+    console.error("Notification dispatch failed", error);
+  });
+}
 
 export async function createRoute(data: CreateRouteInput) {
   await connectMongoDB();
@@ -163,14 +183,22 @@ export async function completeRoute(routeId: string) {
       }
     ).settings?.notifications?.rideCompleted
   ) {
-    await EmailNotifications.rideCompleted(
-      studentUser.email,
-      studentUser.preferredName ??
-        `${studentUser.firstName} ${studentUser.lastName}`,
-      {
-        rideId: route._id.toString(),
-      },
-    );
+    dispatchNotifications([
+      sendEmailSafely("rideCompleted", () =>
+        EmailNotifications.rideCompleted(
+          studentUser.email,
+          studentUser.preferredName ??
+            `${studentUser.firstName} ${studentUser.lastName}`,
+          {
+            rideId: route._id.toString(),
+          },
+        ),
+      ),
+      emitToast(studentUser._id.toString(), {
+        type: "success",
+        message: "Your ride has been completed. Thank you for riding with us!",
+      }),
+    ]);
   }
 
   await archiveChatlogForRoute(routeId);
@@ -199,12 +227,23 @@ export async function cancelRoute(routeId: string, status?: string) {
       }
     ).settings?.notifications?.rideCancelled
   ) {
-    await EmailNotifications.rideCancelled(
-      studentUser.email,
-      studentUser.preferredName ??
-        `${studentUser.firstName} ${studentUser.lastName}`,
-      { rideId: route._id.toString(), reason: `Ride status: ${route.status}` },
-    );
+    dispatchNotifications([
+      sendEmailSafely("rideCancelled", () =>
+        EmailNotifications.rideCancelled(
+          studentUser.email,
+          studentUser.preferredName ??
+            `${studentUser.firstName} ${studentUser.lastName}`,
+          {
+            rideId: route._id.toString(),
+            reason: `Ride status: ${route.status}`,
+          },
+        ),
+      ),
+      emitToast(studentUser._id.toString(), {
+        type: "error",
+        message: "Your ride has been cancelled.",
+      }),
+    ]);
   }
 
   if (route.driver?._id) {
@@ -217,15 +256,23 @@ export async function cancelRoute(routeId: string, status?: string) {
         }
       ).settings?.notifications?.rideCancelled
     ) {
-      await EmailNotifications.rideCancelled(
-        driverUser.email,
-        driverUser.preferredName ??
-          `${driverUser.firstName} ${driverUser.lastName}`,
-        {
-          rideId: route._id.toString(),
-          reason: `Ride status: ${route.status}`,
-        },
-      );
+      dispatchNotifications([
+        sendEmailSafely("rideCancelled", () =>
+          EmailNotifications.rideCancelled(
+            driverUser.email,
+            driverUser.preferredName ??
+              `${driverUser.firstName} ${driverUser.lastName}`,
+            {
+              rideId: route._id.toString(),
+              reason: `Ride status: ${route.status}`,
+            },
+          ),
+        ),
+        emitToast(driverUser._id.toString(), {
+          type: "error",
+          message: "Your ride has been cancelled.",
+        }),
+      ]);
     }
   }
 
@@ -252,18 +299,26 @@ export async function startRoute(routeId: string) {
       }
     ).settings?.notifications?.driverEnRoute
   ) {
-    await EmailNotifications.driverEnRoute(
-      studentUser.email,
-      studentUser.preferredName ??
-        `${studentUser.firstName} ${studentUser.lastName}`,
-      {
-        name: route.driver
-          ? `${route.driver.firstName} ${route.driver.lastName}`
-          : "Driver",
-        eta: formatEstTime(route.scheduledPickupTime),
-        vehicle: route.vehicle?.licensePlate ?? "Assigned vehicle",
-      },
-    );
+    dispatchNotifications([
+      sendEmailSafely("driverEnRoute", () =>
+        EmailNotifications.driverEnRoute(
+          studentUser.email,
+          studentUser.preferredName ??
+            `${studentUser.firstName} ${studentUser.lastName}`,
+          {
+            name: route.driver
+              ? `${route.driver.firstName} ${route.driver.lastName}`
+              : "Driver",
+            eta: formatEstTime(route.scheduledPickupTime),
+            vehicle: route.vehicle?.licensePlate ?? "Assigned vehicle",
+          },
+        ),
+      ),
+      emitToast(studentUser._id.toString(), {
+        type: "info",
+        message: "Your driver is on the way!",
+      }),
+    ]);
   }
 
   return route.toObject();
@@ -377,32 +432,48 @@ export async function scheduleRoute(
       }
     ).settings?.notifications?.driverAssigned
   ) {
-    await EmailNotifications.driverAssigned(
-      studentUser.email,
-      studentUser.preferredName ??
-        `${studentUser.firstName} ${studentUser.lastName}`,
-      {
-        name: `${driver.firstName} ${driver.lastName}`,
-        vehicle: vehicle.licensePlate,
-      },
-    );
+    dispatchNotifications([
+      sendEmailSafely("driverAssigned", () =>
+        EmailNotifications.driverAssigned(
+          studentUser.email,
+          studentUser.preferredName ??
+            `${studentUser.firstName} ${studentUser.lastName}`,
+          {
+            name: `${driver.firstName} ${driver.lastName}`,
+            vehicle: vehicle.licensePlate,
+          },
+        ),
+      ),
+      emitToast(studentUser._id.toString(), {
+        type: "success",
+        message: `Your driver ${driver.firstName} ${driver.lastName} has been assigned.`,
+      }),
+    ]);
   }
 
   if (
     driver &&
     (driver as { settings?: { notifications?: { rideAssigned?: boolean } } })
       .settings?.notifications?.rideAssigned
   ) {
-    await EmailNotifications.rideAssigned(
-      driver.email,
-      driver.preferredName ?? `${driver.firstName} ${driver.lastName}`,
-      {
-        rideId: route._id.toString(),
-        pickup: route.pickupLocation.toString(),
-        dropoff: route.dropoffLocation.toString(),
-        time: `${formatEstDate(route.scheduledPickupTime)} ${formatEstTime(route.scheduledPickupTime)}`,
-      },
-    );
+    dispatchNotifications([
+      sendEmailSafely("rideAssigned", () =>
+        EmailNotifications.rideAssigned(
+          driver.email,
+          driver.preferredName ?? `${driver.firstName} ${driver.lastName}`,
+          {
+            rideId: route._id.toString(),
+            pickup: route.pickupLocation.toString(),
+            dropoff: route.dropoffLocation.toString(),
+            time: `${formatEstDate(route.scheduledPickupTime)} ${formatEstTime(route.scheduledPickupTime)}`,
+          },
+        ),
+      ),
+      emitToast(driver._id.toString(), {
+        type: "info",
+        message: "You have been assigned a new ride.",
+      }),
+    ]);
   }
 
   // Upsert (not create) so this is safe even if a chat record already