feat(backend): implement push notification delivery service via FCM

- Fix env.fcm as plain object (read at import time) → convert to getter
  so FCM_ENABLED is evaluated at runtime after .env is loaded
- Scope stale token cleanup in sendToUser to user_address to avoid
  deleting tokens belonging to other users sharing the same device token
- Fix push-notification spec mock: select().eq() now returns a Promise
  matching the real Supabase async chain instead of a plain object
- Add @UsePipes(DeviceTokenSchema) to DELETE /notifications/device-token
  which was missing body validation
- Add Swagger decorators (@apitags, @ApiBearerAuth, @apioperation,
  @apiresponse) to all notification endpoints

Closes: push notification delivery service issue

Author: od-hunter

backend/src/api/rest/notifications/notifications.controller.ts

@@ -10,12 +10,15 @@ import {
   HttpStatus,
   UsePipes,
 } from '@nestjs/common';
+import { ApiTags, ApiOperation, ApiBearerAuth, ApiResponse } from '@nestjs/swagger';
 import { CurrentUser } from '../../../auth/decorators/current-user.decorator';
 import { NotificationsService } from './notifications.service';
 import { SubscribeSchema, type SubscribeDto } from './dto';
 import { DeviceTokenSchema, type DeviceTokenDto } from './dto/device-token.dto';
 import { createZodPipe } from '../raffles/pipes/zod-validation.pipe';
 
+@ApiTags('Notifications')
+@ApiBearerAuth()
 @Controller('notifications')
 export class NotificationsController {
   constructor(private readonly notificationsService: NotificationsService) {}
@@ -25,6 +28,8 @@ export class NotificationsController {
    * Requires JWT (SIWS)
    */
   @Post('subscribe')
+  @ApiOperation({ summary: 'Subscribe to raffle notifications' })
+  @ApiResponse({ status: 201, description: 'Subscription created or returned if already exists' })
   @UsePipes(new (createZodPipe(SubscribeSchema))())
   async subscribe(
     @Body() dto: SubscribeDto,
@@ -42,6 +47,8 @@ export class NotificationsController {
    * Requires JWT (SIWS)
    */
   @Delete('subscribe/:raffleId')
+  @ApiOperation({ summary: 'Unsubscribe from raffle notifications' })
+  @ApiResponse({ status: 204, description: 'Unsubscribed successfully' })
   @HttpCode(HttpStatus.NO_CONTENT)
   async unsubscribe(
     @Param('raffleId', ParseIntPipe) raffleId: number,
@@ -55,6 +62,8 @@ export class NotificationsController {
    * Requires JWT (SIWS)
    */
   @Get('subscriptions')
+  @ApiOperation({ summary: 'Get all raffle subscriptions for the authenticated user' })
+  @ApiResponse({ status: 200, description: 'List of subscriptions' })
   async getUserSubscriptions(@CurrentUser('address') userAddress: string) {
     return this.notificationsService.getUserSubscriptions(userAddress);
   }
@@ -64,6 +73,8 @@ export class NotificationsController {
    * Requires JWT (SIWS)
    */
   @Post('device-token')
+  @ApiOperation({ summary: 'Register a FCM device token for push notifications' })
+  @ApiResponse({ status: 201, description: 'Token registered' })
   @UsePipes(new (createZodPipe(DeviceTokenSchema))())
   async registerDeviceToken(
     @Body() dto: DeviceTokenDto,
@@ -81,6 +92,9 @@ export class NotificationsController {
    * Requires JWT (SIWS)
    */
   @Delete('device-token')
+  @ApiOperation({ summary: 'Unregister a FCM device token' })
+  @ApiResponse({ status: 200, description: 'Token removed' })
+  @UsePipes(new (createZodPipe(DeviceTokenSchema))())
   async unregisterDeviceToken(
     @Body() dto: DeviceTokenDto,
     @CurrentUser('address') userAddress: string,

backend/src/config/env.config.ts

@@ -27,9 +27,11 @@ export const env = {
       domain: process.env.SIWS_DOMAIN ?? "tikka.io",
     };
   },
-  fcm: {
-    enabled: process.env.FCM_ENABLED === 'true',
-    serviceAccountJson: process.env.FCM_SERVICE_ACCOUNT_JSON ?? undefined,
-    serviceAccountPath: process.env.FCM_SERVICE_ACCOUNT_PATH ?? undefined,
+  get fcm() {
+    return {
+      enabled: process.env.FCM_ENABLED === 'true',
+      serviceAccountJson: process.env.FCM_SERVICE_ACCOUNT_JSON ?? undefined,
+      serviceAccountPath: process.env.FCM_SERVICE_ACCOUNT_PATH ?? undefined,
+    };
   },
 } as const;

backend/src/services/push-notification.service.spec.ts

@@ -2,27 +2,40 @@ import { Test, TestingModule } from '@nestjs/testing';
 import { NotFoundException, InternalServerErrorException } from '@nestjs/common';
 import { PushNotificationService } from './push-notification.service';
 import { SUPABASE_CLIENT } from './supabase.provider';
-import { env } from '../config/env.config';
 
 describe('PushNotificationService', () => {
   let service: PushNotificationService;
-  const mockSelect = jest.fn();
+
+  // Tracks what mockSelect should resolve to for the next call
+  let selectResult: { data: unknown; error: unknown } = { data: [], error: null };
+
+  const mockEq = jest.fn();
+  const mockIn = jest.fn();
   const mockSingle = jest.fn();
   const mockUpsert = jest.fn(() => ({ select: () => ({ single: mockSingle }) }));
-  const mockDelete = jest.fn(() => ({ eq: jest.fn().mockReturnThis(), in: jest.fn().mockReturnThis() }));
+  const mockDelete = jest.fn(() => ({
+    eq: jest.fn().mockReturnThis(),
+    in: jest.fn().mockResolvedValue({ error: null }),
+  }));
+
+  // select('*').eq(...) must return a Promise
+  const mockSelect = jest.fn(() => ({
+    eq: jest.fn().mockResolvedValue(selectResult),
+  }));
 
   const supabaseMock = {
     from: jest.fn(() => ({
       upsert: mockUpsert,
       delete: mockDelete,
       select: mockSelect,
-      eq: jest.fn().mockReturnThis(),
-      in: jest.fn().mockReturnThis(),
+      eq: mockEq,
+      in: mockIn,
     })),
   };
 
   beforeEach(async () => {
     jest.clearAllMocks();
+    selectResult = { data: [], error: null };
 
     const module: TestingModule = await Test.createTestingModule({
       providers: [
@@ -46,29 +59,28 @@ describe('PushNotificationService', () => {
   });
 
   it('unregisters a device token', async () => {
-    mockDelete.mockReturnValue({ eq: jest.fn().mockReturnThis(), in: jest.fn().mockReturnThis() });
     await service.unregisterDeviceToken('GABC', 'tok');
     expect(supabaseMock.from).toHaveBeenCalledWith('push_tokens');
     expect(mockDelete).toHaveBeenCalled();
   });
 
   it('gets device tokens for a user', async () => {
-    mockSelect.mockReturnValue({ eq: jest.fn().mockReturnThis(), data: [{ user_address: 'GABC', device_token: 'tok', platform: 'fcm' }], error: null });
+    selectResult = { data: [{ user_address: 'GABC', device_token: 'tok', platform: 'fcm' }], error: null };
 
     const tokens = await service.getDeviceTokens('GABC');
 
     expect(tokens).toEqual([{ user_address: 'GABC', device_token: 'tok', platform: 'fcm' }]);
     expect(supabaseMock.from).toHaveBeenCalledWith('push_tokens');
+    expect(mockSelect).toHaveBeenCalledWith('*');
   });
 
   it('throws NotFoundException when sendToUser has no tokens', async () => {
-    mockSelect.mockReturnValue({ eq: jest.fn().mockReturnThis(), data: [], error: null });
+    selectResult = { data: [], error: null };
     await expect(service.sendToUser('GABC', { title: 'hi', body: 'hello' })).rejects.toThrow(NotFoundException);
   });
 
   it('throws InternalServerErrorException when FCM is not configured', async () => {
-    mockSelect.mockReturnValue({ eq: jest.fn().mockReturnThis(), data: [{ user_address: 'GABC', device_token: 'tok', platform: 'fcm' }], error: null });
-
+    selectResult = { data: [{ user_address: 'GABC', device_token: 'tok', platform: 'fcm' }], error: null };
     await expect(service.sendToUser('GABC', { title: 'hi', body: 'hello' })).rejects.toThrow(InternalServerErrorException);
   });
 });

backend/src/services/push-notification.service.ts

@@ -176,6 +176,7 @@ export class PushNotificationService {
       await this.client
         .from(TABLE)
         .delete()
+        .eq('user_address', userAddress)
         .in('device_token', invalidTokens);
 
       this.logger.log(`Removed ${invalidTokens.length} stale FCM token(s)`);