PM-1263 - notify users via email about payment setup required

package.json

@@ -32,6 +32,7 @@
     "csv": "^6.3.11",
     "csv-stringify": "^6.5.2",
     "dotenv": "^16.5.0",
+    "json-stringify-safe": "^5.0.1",
     "jsonwebtoken": "^9.0.2",
     "jwks-rsa": "^3.2.0",
     "lodash": "^4.17.21",
@@ -50,6 +51,7 @@
     "@swc/core": "^1.10.7",
     "@types/express": "^5.0.0",
     "@types/jest": "^29.5.14",
+    "@types/json-stringify-safe": "^5.0.3",
     "@types/lodash": "^4.17.16",
     "@types/node": "^22.13.1",
     "@types/supertest": "^6.0.2",

src/api/admin/admin.service.ts

@@ -3,7 +3,6 @@ import {
   HttpStatus,
   NotFoundException,
   BadRequestException,
-  Logger,
 } from '@nestjs/common';
 
 import { Prisma } from '@prisma/client';
@@ -18,6 +17,7 @@ import {
   AdminPaymentUpdateData,
   TopcoderChallengesService,
 } from 'src/shared/topcoder/challenges.service';
+import { Logger } from 'src/shared/global';
 
 /**
  * The admin winning service.

src/api/health-check/healthCheck.controller.ts

@@ -1,13 +1,8 @@
-import {
-  Controller,
-  Get,
-  Logger,
-  Version,
-  VERSION_NEUTRAL,
-} from '@nestjs/common';
+import { Controller, Get, Version, VERSION_NEUTRAL } from '@nestjs/common';
 import { ApiOperation, ApiProperty, ApiTags } from '@nestjs/swagger';
 import { Public } from 'src/core/auth/decorators';
 import { PrismaService } from 'src/shared/global/prisma.service';
+import { Logger } from 'src/shared/global';
 
 export enum HealthCheckStatus {
   healthy = 'healthy',

src/api/repository/winnings.repo.ts

@@ -1,4 +1,4 @@
-import { HttpStatus, Injectable, Logger } from '@nestjs/common';
+import { HttpStatus, Injectable } from '@nestjs/common';
 import {
   payment_status,
   Prisma,
@@ -15,6 +15,7 @@ import {
   WinningsCategory,
 } from 'src/dto/winning.dto';
 import { PrismaService } from 'src/shared/global/prisma.service';
+import { Logger } from 'src/shared/global';
 
 const ONE_DAY = 24 * 60 * 60 * 1000;
 

src/api/wallet/wallet.service.ts

@@ -1,4 +1,4 @@
-import { Injectable, HttpStatus, Logger } from '@nestjs/common';
+import { Injectable, HttpStatus } from '@nestjs/common';
 
 import { PrismaService } from 'src/shared/global/prisma.service';
 
@@ -8,6 +8,7 @@ import { WinningsType } from 'src/dto/winning.dto';
 import { TaxFormRepository } from '../repository/taxForm.repo';
 import { PaymentMethodRepository } from '../repository/paymentMethod.repo';
 import { TrolleyService } from 'src/shared/global/trolley.service';
+import { Logger } from 'src/shared/global';
 
 /**
  * The winning service.

src/api/webhooks/trolley/handlers/payment.handler.ts

@@ -1,4 +1,4 @@
-import { Injectable, Logger } from '@nestjs/common';
+import { Injectable } from '@nestjs/common';
 import {
   PaymentProcessedEventData,
   PaymentProcessedEventStatus,
@@ -9,6 +9,7 @@ import { PaymentsService } from 'src/shared/payments';
 import { payment_status } from '@prisma/client';
 import { PrismaService } from 'src/shared/global/prisma.service';
 import { JsonObject } from '@prisma/client/runtime/library';
+import { Logger } from 'src/shared/global';
 
 @Injectable()
 export class PaymentHandler {

src/api/webhooks/trolley/handlers/recipient-account.handler.ts

@@ -1,4 +1,4 @@
-import { Injectable, Logger } from '@nestjs/common';
+import { Injectable } from '@nestjs/common';
 import { WebhookEvent } from '../../webhooks.decorators';
 import { PrismaService } from 'src/shared/global/prisma.service';
 import {
@@ -8,6 +8,7 @@ import {
 } from './recipient-account.types';
 import { payment_method_status } from '@prisma/client';
 import { PaymentsService } from 'src/shared/payments';
+import { Logger } from 'src/shared/global';
 
 @Injectable()
 export class RecipientAccountHandler {

src/api/webhooks/trolley/handlers/tax-form.handler.ts

@@ -1,4 +1,4 @@
-import { Injectable, Logger } from '@nestjs/common';
+import { Injectable } from '@nestjs/common';
 import { WebhookEvent } from '../../webhooks.decorators';
 import { PrismaService } from 'src/shared/global/prisma.service';
 import {
@@ -13,6 +13,7 @@ import {
   TaxFormStatusUpdatedEventData,
   TaxFormWebhookEvent,
 } from './tax-form.types';
+import { Logger } from 'src/shared/global';
 
 @Injectable()
 export class TaxFormHandler {

src/api/webhooks/trolley/trolley.service.ts

@@ -1,8 +1,9 @@
 import crypto from 'crypto';
-import { Inject, Injectable, Logger } from '@nestjs/common';
+import { Inject, Injectable } from '@nestjs/common';
 import { trolley_webhook_log, webhook_status } from '@prisma/client';
 import { PrismaService } from 'src/shared/global/prisma.service';
 import { ENV_CONFIG } from 'src/config';
+import { Logger } from 'src/shared/global';
 
 export enum TrolleyHeaders {
   id = 'x-paymentrails-delivery',

src/api/webhooks/webhooks.controller.ts

@@ -4,11 +4,11 @@ import {
   Req,
   RawBodyRequest,
   ForbiddenException,
-  Logger,
 } from '@nestjs/common';
 import { ApiTags } from '@nestjs/swagger';
 import { TrolleyHeaders, TrolleyService } from './trolley/trolley.service';
 import { Public } from 'src/core/auth/decorators';
+import { Logger } from 'src/shared/global';
 
 @Public()
 @ApiTags('Webhooks')

src/api/winnings/winnings.module.ts

@@ -5,9 +5,10 @@ import { OriginRepository } from '../repository/origin.repo';
 import { WinningsRepository } from '../repository/winnings.repo';
 import { TaxFormRepository } from '../repository/taxForm.repo';
 import { PaymentMethodRepository } from '../repository/paymentMethod.repo';
+import { TopcoderModule } from 'src/shared/topcoder/topcoder.module';
 
 @Module({
-  imports: [],
+  imports: [TopcoderModule],
   controllers: [WinningsController],
   providers: [
     WinningsService,

src/api/winnings/winnings.service.ts

@@ -1,4 +1,4 @@
-import { Injectable, HttpStatus, Logger } from '@nestjs/common';
+import { Injectable, HttpStatus } from '@nestjs/common';
 import {
   Prisma,
   payment,
@@ -14,6 +14,11 @@ import { PaymentStatus } from 'src/dto/payment.dto';
 import { OriginRepository } from '../repository/origin.repo';
 import { TaxFormRepository } from '../repository/taxForm.repo';
 import { PaymentMethodRepository } from '../repository/paymentMethod.repo';
+import { TopcoderMembersService } from 'src/shared/topcoder/members.service';
+import { BASIC_MEMBER_FIELDS } from 'src/shared/topcoder';
+import { ENV_CONFIG } from 'src/config';
+import { Logger } from 'src/shared/global';
+import { TopcoderEmailService } from 'src/shared/topcoder/tc-email.service';
 
 /**
  * The winning service.
@@ -31,8 +36,55 @@ export class WinningsService {
     private readonly taxFormRepo: TaxFormRepository,
     private readonly paymentMethodRepo: PaymentMethodRepository,
     private readonly originRepo: OriginRepository,
+    private readonly tcMembersService: TopcoderMembersService,
+    private readonly tcEmailService: TopcoderEmailService,
   ) {}
 
+  private async sendSetupEmailNotification(userId: string, amount: number) {
+    this.logger.debug(`Fetching member info for user handle: ${userId}`);
+    const member = await this.tcMembersService.getMemberInfoByUserId(userId, {
+      fields: BASIC_MEMBER_FIELDS,
+    });
+
+    if (!member) {
+      this.logger.warn(
+        `No member information found for user handle: ${userId}`,
+      );
+      return;
+    }
+
+    this.logger.debug(
+      `Member info retrieved successfully for user handle: ${userId}`,
+      { member },
+    );
+
+    this.logger.debug(
+      `Preparing to send payment setup reminder email to: ${member.email}`,
+    );
+
+    try {
+      await this.tcEmailService.sendEmail(
+        member.email,
+        ENV_CONFIG.SENDGRID_TEMPLATE_ID_PAYMENT_SETUP_NOTIFICATION,
+        {
+          data: {
+            user_name: member.firstName || member.handle || member.lastName,
+            amount_won: amount,
+          },
+        },
+      );
+
+      this.logger.debug(
+        `Payment setup reminder email sent successfully to: ${member.email}`,
+      );
+    } catch (error) {
+      this.logger.error(
+        `Failed to send payment setup reminder email to: ${member.email}. Error: ${error.message}`,
+        error,
+      );
+    }
+  }
+
   private async setPayrollPaymentMethod(userId: string) {
     const payrollPaymentMethod = await this.prisma.payment_method.findFirst({
       where: {
@@ -86,6 +138,11 @@ export class WinningsService {
   ): Promise<ResponseDto<string>> {
     const result = new ResponseDto<string>();
 
+    this.logger.debug(
+      `Creating winning with payments for user ${userId}`,
+      body,
+    );
+
     return this.prisma.$transaction(async (tx) => {
       const originId = await this.originRepo.getOriginIdByName(body.origin, tx);
 
@@ -114,6 +171,8 @@ export class WinningsService {
         },
       };
 
+      this.logger.debug('Constructed winning model', { winningModel });
+
       const payrollPayment = (body.attributes || {})['payroll'] === true;
 
       const hasActiveTaxForm = await this.taxFormRepo.hasActiveTaxForm(
@@ -142,23 +201,51 @@ export class WinningsService {
             : PaymentStatus.ON_HOLD;
 
         if (payrollPayment) {
+          this.logger.debug(
+            `Payroll payment detected. Setting payment status to PAID for user ${body.winnerId}`,
+          );
           paymentModel.payment_status = PaymentStatus.PAID;
           await this.setPayrollPaymentMethod(body.winnerId);
         }
 
         winningModel.payment.create.push(paymentModel);
+        this.logger.debug('Added payment model to winning model', {
+          paymentModel,
+        });
       }
-      // use prisma nested writes to avoid foreign key checks
+
+      this.logger.debug('Attempting to create winning with nested payments.');
       const createdWinning = await this.prisma.winnings.create({
         data: winningModel as any,
       });
+
       if (!createdWinning) {
+        this.logger.error('Failed to create winning!');
         result.error = {
           code: HttpStatus.INTERNAL_SERVER_ERROR,
           message: 'Failed to create winning!',
         };
+      } else {
+        this.logger.debug('Successfully created winning', { createdWinning });
+      }
+
+      if (
+        !payrollPayment &&
+        (!hasConnectedPaymentMethod || !hasActiveTaxForm)
+      ) {
+        const amount = body.details.find(
+          (d) => d.installmentNumber === 1,
+        )?.totalAmount;
+
+        if (amount) {
+          this.logger.debug(
+            `Sending setup email notification for user ${body.winnerId} with amount ${amount}`,
+          );
+          void this.sendSetupEmailNotification(body.winnerId, amount);
+        }
       }
 
+      this.logger.debug('Transaction completed successfully.');
       return result;
     });
   }

src/api/withdrawal/withdrawal.service.ts

@@ -1,4 +1,4 @@
-import { Injectable, Logger } from '@nestjs/common';
+import { Injectable } from '@nestjs/common';
 import { ENV_CONFIG } from 'src/config';
 import { PrismaService } from 'src/shared/global/prisma.service';
 import { TaxFormRepository } from '../repository/taxForm.repo';
@@ -12,6 +12,7 @@ import {
 } from 'src/shared/topcoder/challenges.service';
 import { TopcoderMembersService } from 'src/shared/topcoder/members.service';
 import { MEMBER_FIELDS } from 'src/shared/topcoder';
+import { Logger } from 'src/shared/global';
 
 const TROLLEY_MINIMUM_PAYMENT_AMOUNT =
   ENV_CONFIG.TROLLEY_MINIMUM_PAYMENT_AMOUNT;

src/config/config.env.ts

@@ -1,5 +1,11 @@
 import { Transform } from 'class-transformer';
-import { IsBoolean, IsInt, IsOptional, IsString } from 'class-validator';
+import {
+  IsBoolean,
+  IsInt,
+  IsNotEmpty,
+  IsOptional,
+  IsString,
+} from 'class-validator';
 
 export class ConfigEnv {
   @IsString()
@@ -65,4 +71,20 @@ export class ConfigEnv {
     return false;
   })
   ACCEPT_CUSTOM_PAYMENTS_MEMO;
+
+  @IsString()
+  @IsOptional()
+  TC_EMAIL_NOTIFICATIONS_TOPIC = 'external.action.email';
+
+  @IsString()
+  @IsOptional()
+  TC_EMAIL_FROM_NAME = 'Topcoder';
+
+  @IsString()
+  @IsNotEmpty()
+  TC_EMAIL_FROM_EMAIL: string;
+
+  @IsString()
+  SENDGRID_TEMPLATE_ID_PAYMENT_SETUP_NOTIFICATION =
+    'd-919e01f1314e44439bc90971b55f7db7';
 }

src/config/config.loader.ts

@@ -1,8 +1,10 @@
 import * as dotenv from 'dotenv';
 import { plainToInstance } from 'class-transformer';
 import { validateSync } from 'class-validator';
-import { Logger } from '@nestjs/common';
 import { ConfigEnv } from './config.env';
+import { Logger } from 'src/shared/global';
+
+const logger = new Logger('ENV_CONFIG');
 
 /**
  * Loads and validates environment variables into a `ConfigEnv` instance.
@@ -31,13 +33,17 @@ function loadAndValidateEnv(): ConfigEnv {
   });
 
   if (errors.length > 0) {
-    const logger = new Logger('Config');
     for (const err of errors) {
-      logger.error(JSON.stringify(err.constraints));
+      logger.error(
+        'Invalid or missing environment variables!',
+        err.constraints,
+      );
     }
     throw new Error('Invalid environment variables');
   }
 
+  logger.debug(`Environment config vars successfully loaded and validated!`);
+
   return env;
 }
 

src/core/auth/jwt.ts

@@ -1,7 +1,7 @@
-import { Logger } from '@nestjs/common';
 import { decode } from 'jsonwebtoken';
 import { JwksClient } from 'jwks-rsa';
 import { ENV_CONFIG } from 'src/config';
+import { Logger } from 'src/shared/global';
 
 const logger = new Logger(`auth/jwks`);
 
@@ -26,7 +26,7 @@ const client = new JwksClient({
 export const getSigningKey = (token: string) => {
   const tokenHeader = decode(token, { complete: true })?.header;
 
-  return new Promise((resolve, reject) => {
+  return new Promise<string>((resolve, reject) => {
     if (!tokenHeader || !tokenHeader.kid) {
       logger.error('Invalid token: Missing key ID');
       return reject(new Error('Invalid token: Missing key ID'));