Merge branch 'dev' into PM-5043

Author: jmgasper

.circleci/config.yml

@@ -76,6 +76,7 @@ workflows:
                               - dev
                               - engagements
                               - PM-4789_payment-migrations
+                              - PM-5149
             - 'build-prod':
                   context: org-global
                   filters:

src/api/admin/admin.service.spec.ts

@@ -151,6 +151,48 @@ describe('AdminService', () => {
     );
   });
 
+  it('returns paymentApproverHandle for engagement payments from audit trail', async () => {
+    prisma.winnings.findFirst.mockResolvedValue({
+      winning_id: 'winning-1',
+      category: 'ENGAGEMENT_PAYMENT',
+      created_by: '654321',
+      external_id: 'assignment-1',
+      attributes: {},
+    });
+    topcoderEngagementsService.getAssignmentContextById.mockResolvedValue({
+      assignmentId: 'assignment-1',
+      engagementId: 'engagement-1',
+      engagementTitle: 'May 19 pvt eng',
+      projectId: '100575',
+      projectName: 'Ai Reviewer Wf testing',
+      ratePerHour: '2.99',
+      standardHoursPerWeek: 11,
+      startDate: '2026-05-23T12:00:00.000Z',
+      durationMonths: 2,
+    });
+    prisma.audit.findMany.mockResolvedValue([
+      {
+        id: 'audit-1',
+        winnings_id: 'winning-1',
+        user_id: '654321',
+        action: 'status updated from ON_HOLD_ADMIN to OWED',
+        note: null,
+        created_at: new Date(),
+      },
+    ]);
+
+    const result = await service.getWinningPaymentDetails(
+      'winning-1',
+      '123456',
+      ['Payment Admin'],
+    );
+
+    expect(result.data?.engagementDetails?.paymentApproverHandle).toBe(
+      'payment-manager',
+    );
+    expect(result.data?.engagementDetails?.assignmentId).toBe('assignment-1');
+  });
+
   it('returns work-log and engagement details for engagement payments', async () => {
     prisma.winnings.findFirst.mockResolvedValue({
       winning_id: 'winning-1',
@@ -200,9 +242,12 @@ describe('AdminService', () => {
         engagementId: 'engagement-1',
         engagementTitle: 'Senior Frontend Engineer',
         otherRemarks: 'Complete onboarding within the first week.',
+        paymentApproverHandle: undefined,
+        paymentCycle: 'WEEKLY',
         projectId: 'project-1',
         projectName: 'Platform Modernization',
         ratePerHour: '75.50',
+        standardHoursPerDay: 8,
         standardHoursPerWeek: 40,
       },
       paymentCreatorHandle: 'payment-manager',
@@ -296,9 +341,12 @@ describe('AdminService', () => {
         engagementId: 'engagement-1',
         engagementTitle: 'Senior Frontend Engineer',
         otherRemarks: 'Working EST overlap.',
+        paymentApproverHandle: undefined,
+        paymentCycle: 'WEEKLY',
         projectId: 'project-1',
         projectName: 'Platform Modernization',
         ratePerHour: '82.50',
+        standardHoursPerDay: 7,
         standardHoursPerWeek: 35,
       },
       paymentCreatorHandle: 'payment-manager',

src/api/admin/admin.service.ts

@@ -33,8 +33,11 @@ import {
   TopcoderChallengeInfo,
   TopcoderChallengesService,
 } from 'src/shared/topcoder/challenges.service';
-import { WinningPaymentDetailsDto } from './dto/payment-details.dto';
 import { resolveChallengeMemberPaymentAmount } from 'src/shared/payments/challenge-payment-amount.util';
+import {
+  PaymentCycle,
+  WinningPaymentDetailsDto,
+} from './dto/payment-details.dto';
 
 const PAYMENT_DECIMAL_PLACES = 2;
 const BUDGET_LEDGER_DECIMAL_PLACES = 4;
@@ -262,6 +265,13 @@ export class AdminService {
       assignment.standardHoursPerWeek !== null
         ? Number(assignment.standardHoursPerWeek)
         : undefined;
+    const standardHoursPerDay =
+      assignment?.standardHoursPerDay !== undefined &&
+      assignment.standardHoursPerDay !== null
+        ? Number(assignment.standardHoursPerDay)
+        : Number.isFinite(standardHoursPerWeek)
+          ? Number(((standardHoursPerWeek ?? 0) / 5).toFixed(2))
+          : undefined;
     const projectId = engagement.projectId ?? engagement.project?.id;
     const projectName =
       (engagement.projectName ?? engagement.project?.name)?.trim() ?? undefined;
@@ -289,6 +299,11 @@ export class AdminService {
         ? durationMonths
         : undefined,
       ratePerHour: assignment?.ratePerHour?.trim() ?? undefined,
+      paymentCycle: (assignment?.paymentCycle?.trim() ||
+        'WEEKLY') as PaymentCycle,
+      standardHoursPerDay: Number.isFinite(standardHoursPerDay)
+        ? standardHoursPerDay
+        : undefined,
       standardHoursPerWeek: Number.isFinite(standardHoursPerWeek)
         ? standardHoursPerWeek
         : undefined,
@@ -1187,6 +1202,38 @@ export class AdminService {
     return result;
   }
 
+  /**
+   * Resolves the payment approver handle from the audit entry that moved the
+   * winning from `ON_HOLD_ADMIN` to `OWED`.
+   */
+  private async resolvePaymentApproverHandleFromAudit(
+    winningsId: string,
+  ): Promise<string | undefined> {
+    try {
+      const audits = await this.prisma.audit.findMany({
+        where: { winnings_id: winningsId },
+        orderBy: { created_at: 'desc' },
+        take: 200,
+      });
+      const approverAudit = audits.find(
+        (audit) =>
+          typeof audit.action === 'string' &&
+          audit.action.includes('ON_HOLD_ADMIN') &&
+          audit.action.includes('OWED') &&
+          audit.action.indexOf('ON_HOLD_ADMIN') < audit.action.indexOf('OWED'),
+      );
+
+      if (!approverAudit?.user_id) {
+        return undefined;
+      }
+
+      return this.getPaymentCreatorHandle(String(approverAudit.user_id));
+    } catch {
+      // approver is optional — ignore failures
+      return undefined;
+    }
+  }
+
   private async buildTaskDetails(
     winningsId: string,
     externalId: string | undefined,
@@ -1220,27 +1267,8 @@ export class AdminService {
       }
     }
 
-    try {
-      const audits = await this.prisma.audit.findMany({
-        where: { winnings_id: winningsId },
-        orderBy: { created_at: 'desc' },
-        take: 200,
-      });
-      const approverAudit = audits.find(
-        (a) =>
-          typeof a.action === 'string' &&
-          a.action.includes('ON_HOLD_ADMIN') &&
-          a.action.includes('OWED') &&
-          a.action.indexOf('ON_HOLD_ADMIN') < a.action.indexOf('OWED'),
-      );
-      if (approverAudit?.user_id) {
-        const userId = String(approverAudit.user_id);
-        const handle = await this.getPaymentCreatorHandle(userId);
-        taskDetails.paymentApproverHandle = handle ?? undefined;
-      }
-    } catch {
-      // approver is optional — ignore failures
-    }
+    taskDetails.paymentApproverHandle =
+      await this.resolvePaymentApproverHandleFromAudit(winningsId);
 
     return taskDetails;
   }
@@ -1294,13 +1322,15 @@ export class AdminService {
       return result;
     }
 
+    const paymentApproverHandle =
+      await this.resolvePaymentApproverHandleFromAudit(winningsId);
+
     if (assignmentLookupId) {
       try {
         const assignmentContext =
           await this.topcoderEngagementsService.getAssignmentContextById(
             assignmentLookupId,
           );
-
         result.data.engagementDetails = {
           assignmentId: assignmentContext.assignmentId,
           engagementId: assignmentContext.engagementId,
@@ -1312,9 +1342,18 @@ export class AdminService {
             : undefined,
           durationMonths: assignmentContext.durationMonths ?? undefined,
           ratePerHour: assignmentContext.ratePerHour ?? undefined,
+          paymentCycle: (assignmentContext.paymentCycle ??
+            'WEEKLY') as PaymentCycle,
+          standardHoursPerDay:
+            assignmentContext.standardHoursPerDay ??
+            (assignmentContext.standardHoursPerWeek !== undefined &&
+            assignmentContext.standardHoursPerWeek !== null
+              ? Number((assignmentContext.standardHoursPerWeek / 5).toFixed(2))
+              : undefined),
           standardHoursPerWeek:
             assignmentContext.standardHoursPerWeek ?? undefined,
           otherRemarks: assignmentContext.otherRemarks ?? undefined,
+          paymentApproverHandle,
         };
 
         return result;
@@ -1339,11 +1378,14 @@ export class AdminService {
         assignmentId,
       );
 
-      result.data.engagementDetails = this.buildEngagementDetailsFromEngagement(
-        engagement,
-        assignment,
-        assignmentId,
-      );
+      result.data.engagementDetails = {
+        ...this.buildEngagementDetailsFromEngagement(
+          engagement,
+          assignment,
+          assignmentId,
+        ),
+        paymentApproverHandle,
+      };
     } catch (error) {
       this.logger.warn(
         `Failed to enrich winning ${winningsId} with engagement details`,

src/api/admin/dto/payment-details.dto.ts

@@ -1,5 +1,7 @@
 import { ApiPropertyOptional } from '@nestjs/swagger';
 
+export type PaymentCycle = 'WEEKLY' | 'FORTNIGHTLY' | 'MONTHLY';
+
 export class PaymentEngagementDetailsDto {
   @ApiPropertyOptional({
     description: 'The assignment ID associated with the payment',
@@ -49,6 +51,19 @@ export class PaymentEngagementDetailsDto {
   })
   ratePerHour?: string;
 
+  @ApiPropertyOptional({
+    description: 'Assignment payment cycle',
+    enum: ['WEEKLY', 'FORTNIGHTLY', 'MONTHLY'],
+    example: 'WEEKLY',
+  })
+  paymentCycle?: PaymentCycle;
+
+  @ApiPropertyOptional({
+    description: 'Assignment standard hours per day',
+    example: 8,
+  })
+  standardHoursPerDay?: number;
+
   @ApiPropertyOptional({
     description: 'Assignment standard hours per week',
     example: 40,
@@ -60,6 +75,13 @@ export class PaymentEngagementDetailsDto {
     example: 'Complete onboarding within the first week.',
   })
   otherRemarks?: string;
+
+  @ApiPropertyOptional({
+    description:
+      'The Topcoder handle of the wallet-admin user who approved this payment',
+    example: 'payment_approver_handle',
+  })
+  paymentApproverHandle?: string;
 }
 
 export class PaymentWorkLogDto {

src/api/challenges/challenges.service.spec.ts

@@ -260,6 +260,53 @@ describe('ChallengesService', () => {
     });
   });
 
+  it.each([
+    ['regular', undefined],
+    ['TAAS', [{ name: 'payment_type', value: 'taas' }]],
+    ['Topgear', [{ name: 'payment_type', value: 'topgear' }]],
+  ])(
+    'defaults %s task copilot payments to OWED status',
+    async (_, metadata) => {
+      const service = new ChallengesService(
+        {} as any,
+        {} as any,
+        {} as any,
+        {} as any,
+        {} as any,
+      );
+
+      jest.spyOn(service, 'getChallengeResources').mockResolvedValue({
+        copilot: [{ memberHandle: 'copilot', memberId: '40158995' }],
+      } as any);
+      jest.spyOn(service, 'getChallengeReviews').mockResolvedValue([]);
+
+      const winnings = await service.getChallengePayments({
+        id: '11111111-1111-1111-1111-111111111111',
+        name: 'Task Challenge',
+        type: 'Task',
+        task: { isTask: true },
+        billing: { billingAccountId: '1234', markup: 0.2 },
+        metadata,
+        winners: [],
+        checkpointWinners: [],
+        reviewers: [],
+        phases: [],
+        prizeSets: [
+          { type: 'PLACEMENT', prizes: [{ type: PrizeType.USD, value: 500 }] },
+          { type: 'COPILOT', prizes: [{ type: PrizeType.USD, value: 100 }] },
+        ],
+      } as any);
+
+      expect(winnings).toEqual([
+        expect.objectContaining({
+          category: WinningsCategory.COPILOT_PAYMENT,
+          status: PaymentStatus.OWED,
+          winnerId: '40158995',
+        }),
+      ]);
+    },
+  );
+
   it('does not force ON_HOLD_ADMIN status for non-task challenge winnings', async () => {
     const service = new ChallengesService(
       {} as any,

src/api/challenges/challenges.service.ts

@@ -63,6 +63,11 @@ const PAYMENT_TYPE_TO_CATEGORY: Record<string, WinningsCategory> = {
   taas: WinningsCategory.TAAS_PAYMENT,
   topgear: WinningsCategory.TOPGEAR_PAYMENT,
 };
+const OWED_TASK_PAYMENT_CATEGORIES = new Set<WinningsCategory>([
+  WinningsCategory.TAAS_PAYMENT,
+  WinningsCategory.COPILOT_PAYMENT,
+  WinningsCategory.TASK_COPILOT_PAYMENT,
+]);
 
 const CANCELLED_CHALLENGE_STATUSES = [
   ChallengeStatuses.Canceled,
@@ -155,8 +160,9 @@ export class ChallengesService {
    * @param challenge Challenge details returned by challenge-api-v6.
    * @param category Winnings category selected for the generated payment.
    * @param currency Prize currency selected for the generated payment.
-   * @returns OWED for USD TAAS task payments, ON_HOLD_ADMIN for other USD task
-   * payments, and undefined when standard payout-readiness rules should apply.
+   * @returns OWED for USD TAAS task payments and task copilot payments,
+   * ON_HOLD_ADMIN for other USD task payments, and undefined when standard
+   * payout-readiness rules should apply.
    * @throws This method does not throw.
    */
   private getTaskPaymentStatus(
@@ -168,7 +174,7 @@ export class ChallengesService {
       return undefined;
     }
 
-    return category === WinningsCategory.TAAS_PAYMENT
+    return OWED_TASK_PAYMENT_CATEGORIES.has(category)
       ? PaymentStatus.OWED
       : PaymentStatus.ON_HOLD_ADMIN;
   }