Merge branch 'PM-1143_handle-taxForm-status-updated' into HEAD

Author: vas3a

prisma/migrations/20250425134520_truncate_tax_forms/migration.sql

@@ -8,7 +8,7 @@ ALTER TABLE "user_tax_form_associations" DROP CONSTRAINT "user_tax_form_associat
 DROP TABLE "user_tax_form_associations";
 DROP TYPE "tax_form_status";
 
-CREATE TYPE "tax_form_status" AS ENUM ('incomplete', 'submitted', 'reviewed', 'voided');
+CREATE TYPE "tax_form_status" AS ENUM ('ACTIVE', 'INACTIVE');
 
 -- CreateTable
 CREATE TABLE "user_tax_form_associations" (

prisma/schema.prisma

@@ -249,10 +249,8 @@ enum reference_type {
 }
 
 enum tax_form_status {
-  incomplete
-  submitted
-  reviewed
-  voided
+  ACTIVE
+  INACTIVE
 }
 
 enum transaction_status {

src/api/repository/taxForm.repo.ts

@@ -1,5 +1,5 @@
 import { Injectable } from '@nestjs/common';
-import { TaxFormStatus } from 'src/dto/adminWinning.dto';
+import { tax_form_status } from '@prisma/client';
 import { PrismaService } from 'src/shared/global/prisma.service';
 
 @Injectable()
@@ -16,7 +16,7 @@ export class TaxFormRepository {
     const count = await this.prisma.user_tax_form_associations.count({
       where: {
         user_id: userId,
-        tax_form_status: TaxFormStatus.Reviewed,
+        tax_form_status: tax_form_status.ACTIVE,
       },
     });
 

src/api/webhooks/trolley/handlers/index.ts

@@ -1,5 +1,6 @@
 import { Provider } from '@nestjs/common';
 import { PaymentHandler } from './payment.handler';
+import { TaxFormHandler } from './tax-form.handler';
 import { getWebhooksEventHandlersProvider } from '../../webhooks.event-handlers.provider';
 
 export const TrolleyWebhookHandlers: Provider[] = [
@@ -9,9 +10,13 @@ export const TrolleyWebhookHandlers: Provider[] = [
   ),
 
   PaymentHandler,
+  TaxFormHandler,
   {
     provide: 'TrolleyWebhookHandlers',
-    useFactory: (paymentHandler: PaymentHandler) => [paymentHandler],
-    inject: [PaymentHandler],
+    inject: [PaymentHandler, TaxFormHandler],
+    useFactory: (
+      paymentHandler: PaymentHandler,
+      taxFormHandler: TaxFormHandler,
+    ) => [paymentHandler, taxFormHandler],
   },
 ];

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

@@ -0,0 +1,106 @@
+import { Injectable } from '@nestjs/common';
+import { WebhookEvent } from '../../webhooks.decorators';
+import {
+  TrolleyTaxFormStatus,
+  TaxFormStatusUpdatedEvent,
+  TaxFormStatusUpdatedEventData,
+  TrolleyWebhookEvent,
+} from '../trolley.types';
+import { PrismaService } from 'src/shared/global/prisma.service';
+import { tax_form_status, trolley_recipient } from '@prisma/client';
+
+@Injectable()
+export class TaxFormHandler {
+  constructor(private readonly prisma: PrismaService) {}
+
+  getDbRecipientById(id: string) {
+    return this.prisma.trolley_recipient.findUnique({
+      where: { trolley_id: id },
+    });
+  }
+
+  async createOrUpdateTaxFormAssociation(
+    taxFormId: string,
+    recipient: trolley_recipient,
+    taxFormData: TaxFormStatusUpdatedEventData,
+  ) {
+    const taxFormStatus =
+      taxFormData.status === TrolleyTaxFormStatus.Reviewed
+        ? tax_form_status.ACTIVE
+        : tax_form_status.INACTIVE;
+
+    const existingFormAssociation =
+      await this.prisma.user_tax_form_associations.findFirst({
+        where: {
+          user_id: recipient.user_id,
+          tax_form_id: taxFormId,
+          tax_form_status: tax_form_status.ACTIVE,
+        },
+      });
+
+    // voided forms associations are removed from DB
+    if (
+      taxFormData.status === TrolleyTaxFormStatus.Voided &&
+      existingFormAssociation
+    ) {
+      return this.prisma.user_tax_form_associations.delete({
+        where: {
+          id: existingFormAssociation.id,
+        },
+      });
+    }
+
+    if (!existingFormAssociation) {
+      return this.prisma.user_tax_form_associations.create({
+        data: {
+          user_id: recipient.user_id,
+          tax_form_status: taxFormStatus,
+          date_filed: taxFormData.signedAt,
+          tax_form_id: taxFormId,
+        },
+      });
+    }
+
+    return this.prisma.user_tax_form_associations.update({
+      where: { id: existingFormAssociation?.id },
+      data: {
+        tax_form_status: taxFormStatus,
+        date_filed: taxFormData.signedAt,
+      },
+    });
+  }
+
+  /**
+   * Handles the "TaxFormStatusUpdated" event by processing the tax form data
+   * and updating the associated recipient information in the database.
+   *
+   * @param payload - The event payload containing the updated tax form data.
+   * @returns A promise that resolves when the operation is complete.
+   *
+   * @remarks
+   * - If the recipient associated with the tax form cannot be found in the database,
+   *   an error is logged and the operation is terminated.
+   * - If the recipient is found, the tax form association is created or updated
+   *   in the database.
+   */
+  @WebhookEvent(TrolleyWebhookEvent.taxFormStatusUpdated)
+  async handleTaxFormStatusUpdated(
+    payload: TaxFormStatusUpdatedEvent,
+  ): Promise<void> {
+    const taxFormData = payload.taxForm.data;
+    const recipient = await this.getDbRecipientById(taxFormData.recipientId);
+
+    if (!recipient) {
+      console.error(
+        `Recipient not found for recipientId '${taxFormData.recipientId}' in taxForm with id '${taxFormData.taxFormId}'`,
+      );
+      return;
+    }
+
+    await this.createOrUpdateTaxFormAssociation(
+      taxFormData.taxFormId,
+      recipient,
+      taxFormData,
+    );
+  }
+}

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

@@ -4,7 +4,7 @@ import { trolley_webhook_log, webhook_status } from '@prisma/client';
 import { PrismaService } from 'src/shared/global/prisma.service';
 import { ENV_CONFIG } from 'src/config';
 
-enum TrolleyHeaders {
+export enum TrolleyHeaders {
   id = 'x-paymentrails-delivery',
   signature = 'x-paymentrails-signature',
   created = 'x-paymentrails-created',

src/api/webhooks/trolley/trolley.types.ts

@@ -1,6 +1,41 @@
 export enum TrolleyWebhookEvent {
   paymentCreated = 'payment.created',
   paymentUpdated = 'payment.updated',
+  taxFormStatusUpdated = 'taxForm.status_updated',
 }
 
 export type TrolleyEventHandler = (eventPayload: any) => Promise<unknown>;
+
+export enum TrolleyTaxFormStatus {
+  Incomplete = 'incomplete',
+  Submitted = 'submitted',
+  Reviewed = 'reviewed',
+  Voided = 'voided',
+}
+
+export interface TaxFormStatusUpdatedEventData {
+  recipientId: string;
+  taxFormId: string;
+  status: TrolleyTaxFormStatus;
+  taxFormType: string;
+  taxFormAddressCountry: string;
+  mailingAddressCountry: string | null;
+  registrationCountry: string | null;
+  createdAt: string;
+  signedAt: string;
+  reviewedAt: string;
+  reviewedBy: string;
+  voidedAt: string | null;
+  voidReason: string | null;
+  voidedBy: string | null;
+  tinStatus: string;
+}
+
+export interface TaxFormStatusUpdatedEvent {
+  taxForm: {
+    previousFields: {
+      status: TrolleyTaxFormStatus;
+    };
+    data: TaxFormStatusUpdatedEventData;
+  };
+}

src/api/webhooks/webhooks.controller.ts

@@ -6,7 +6,7 @@ import {
   ForbiddenException,
 } from '@nestjs/common';
 import { ApiTags } from '@nestjs/swagger';
-import { TrolleyService } from './trolley/trolley.service';
+import { TrolleyHeaders, TrolleyService } from './trolley/trolley.service';
 import { Public } from 'src/core/auth/decorators';
 
 @Public()
@@ -39,6 +39,9 @@ export class WebhooksController {
 
     // do not proceed any further if event has already been processed
     if (!(await this.trolleyService.validateUnique(request.headers))) {
+      console.info(
+        `Webhook event '${request.headers[TrolleyHeaders.id]}' has already been processed!`,
+      );
       return;
     }
 

src/dto/adminWinning.dto.ts

@@ -92,13 +92,6 @@ export enum WinningsCategory {
   TASK_COPILOT_PAYMENT = 'TASK_COPILOT_PAYMENT',
 }
 
-export enum TaxFormStatus {
-  Incomplete = 'incomplete',
-  Submitted = 'submitted',
-  Reviewed = 'reviewed',
-  Voided = 'voided',
-}
-
 export enum PaymentStatus {
   PAID = 'PAID',
   ON_HOLD = 'ON_HOLD',

src/dto/taxForm.dto.ts

@@ -1,9 +1,9 @@
-import { TaxFormStatus } from './adminWinning.dto';
+import { tax_form_status } from '@prisma/client';
 
 export class TaxFormQueryResult {
   id: string;
   user_id: string;
   tax_form_id: string;
   date_filed: Date;
-  tax_form_status: TaxFormStatus;
+  tax_form_status: tax_form_status;
 }