fix(background-checks): fix 13 bugs across billing, webhooks, custom uploads, and UI

carhartlewis · claude · carhartlewis · commit d5df5db4dc4c · 2026-04-29T23:52:34.000+01:00
P1: Upload file before marking custom background check as completed, scope
refund to identity API failures only, reconcile state on duplicate webhook
events, and verify checkout session status before processing.

P2: Remove unnecessary buffer copy in raw body parsing, track SWR loading
state for custom attachments, handle numeric-string epoch timestamps, include
device task in totals while loading, add 30s timeout to Identity API calls,
assert 402 status in payment test, accept $0 prices in billing, and validate
whitespace-only employee names via DTO transform.

P3: Deduplicate BackgroundCheckStatus type definition.

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/apps/api/src/background-checks/background-check-billing.service.ts b/apps/api/src/background-checks/background-check-billing.service.ts
@@ -78,6 +78,10 @@ export class BackgroundCheckBillingService {
       expand: ['setup_intent'],
     });
 
+    if (session.status !== 'complete') {
+      throw new BadRequestException('Checkout session is not complete.');
+    }
+
     const stripeCustomerId = this.extractStripeId(session.customer);
     if (!stripeCustomerId) {
       throw new BadRequestException('Checkout session is missing a customer.');
@@ -192,7 +196,7 @@ export class BackgroundCheckBillingService {
 
     const stripe = this.stripeService.getClient();
     const price = await stripe.prices.retrieve(priceId);
-    if (!price.unit_amount) {
+    if (price.unit_amount === null || price.unit_amount === undefined) {
       throw new BadRequestException('Background check price has no unit amount.');
     }
 
diff --git a/apps/api/src/background-checks/background-check-custom.service.spec.ts b/apps/api/src/background-checks/background-check-custom.service.spec.ts
@@ -7,12 +7,14 @@ jest.mock('@db', () => ({
     background_check: 'background_check',
   },
   BackgroundCheckStatus: {
+    invited: 'invited',
     completed: 'completed',
   },
   db: {
     backgroundCheckRequest: {
       findUnique: jest.fn(),
       upsert: jest.fn(),
+      update: jest.fn(),
     },
     member: {
       findFirst: jest.fn(),
@@ -31,7 +33,7 @@ describe('BackgroundCheckCustomService', () => {
     jest.clearAllMocks();
   });
 
-  it('creates a completed background check and stores the uploaded report as an attachment', async () => {
+  it('creates a background check record, uploads the file, then marks completed', async () => {
     const uploadAttachment = jest.fn().mockResolvedValue({
       id: 'att_1',
       name: 'report.pdf',
@@ -53,8 +55,14 @@ describe('BackgroundCheckCustomService', () => {
       mockedDb.backgroundCheckRequest.upsert,
     ).mockResolvedValueOnce({
       id: 'bcr_1',
-      status: BackgroundCheckStatus.completed,
+      status: 'invited',
     } as Awaited<ReturnType<typeof db.backgroundCheckRequest.upsert>>);
+    mockAsync<Awaited<ReturnType<typeof db.backgroundCheckRequest.update>>>(
+      mockedDb.backgroundCheckRequest.update,
+    ).mockResolvedValueOnce({
+      id: 'bcr_1',
+      status: BackgroundCheckStatus.completed,
+    } as Awaited<ReturnType<typeof db.backgroundCheckRequest.update>>);
 
     await service.attachForMember({
       organizationId: 'org_1',
@@ -67,15 +75,17 @@ describe('BackgroundCheckCustomService', () => {
       userId: 'usr_1',
     });
 
+    // Record is created with non-completed status first
     expect(mockedDb.backgroundCheckRequest.upsert).toHaveBeenCalledWith(
       expect.objectContaining({
         create: expect.objectContaining({
           employeeName: 'Ada Lovelace',
           employeeEmail: 'ada@work.example',
-          status: BackgroundCheckStatus.completed,
+          status: 'invited',
         }),
       }),
     );
+    // Upload happens before marking completed
     expect(uploadAttachment).toHaveBeenCalledWith(
       'org_1',
       'bcr_1',
@@ -86,6 +96,15 @@ describe('BackgroundCheckCustomService', () => {
       }),
       'usr_1',
     );
+    // Only marked completed after successful upload
+    expect(mockedDb.backgroundCheckRequest.update).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: { id: 'bcr_1' },
+        data: expect.objectContaining({
+          status: BackgroundCheckStatus.completed,
+        }),
+      }),
+    );
   });
 
   it('returns custom attachments for an existing background check', async () => {
diff --git a/apps/api/src/background-checks/background-check-custom.service.ts b/apps/api/src/background-checks/background-check-custom.service.ts
@@ -57,28 +57,29 @@ export class BackgroundCheckCustomService {
       throw new NotFoundException('Member not found.');
     }
 
+    const resolvedName = employeeName?.trim() || member.user.name || member.user.email;
+    const resolvedEmail = employeeEmail?.trim().toLowerCase() || member.user.email;
+
+    // Create/update the record without marking it completed yet
     const record = await db.backgroundCheckRequest.upsert({
       where: { organizationId_memberId: { organizationId, memberId } },
       create: {
         organizationId,
         memberId,
-        employeeName: employeeName?.trim() || member.user.name || member.user.email,
-        employeeEmail: employeeEmail?.trim().toLowerCase() || member.user.email,
+        employeeName: resolvedName,
+        employeeEmail: resolvedEmail,
         requesterNotes,
-        status: BackgroundCheckStatus.completed,
+        status: BackgroundCheckStatus.invited,
         lastSyncedAt: new Date(),
-        reportSyncedAt: new Date(),
       },
       update: {
-        employeeName: employeeName?.trim() || member.user.name || member.user.email,
-        employeeEmail: employeeEmail?.trim().toLowerCase() || member.user.email,
+        employeeName: resolvedName,
+        employeeEmail: resolvedEmail,
         requesterNotes,
-        status: BackgroundCheckStatus.completed,
-        lastSyncedAt: new Date(),
-        reportSyncedAt: new Date(),
       },
     });
 
+    // Upload first — if this fails the record stays non-completed
     await this.attachmentsService.uploadAttachment(
       organizationId,
       record.id,
@@ -87,6 +88,14 @@ export class BackgroundCheckCustomService {
       userId,
     );
 
-    return record;
+    // Mark completed only after a successful upload
+    return db.backgroundCheckRequest.update({
+      where: { id: record.id },
+      data: {
+        status: BackgroundCheckStatus.completed,
+        lastSyncedAt: new Date(),
+        reportSyncedAt: new Date(),
+      },
+    });
   }
 }
diff --git a/apps/api/src/background-checks/background-check-identity.client.ts b/apps/api/src/background-checks/background-check-identity.client.ts
@@ -90,7 +90,10 @@ export class BackgroundCheckIdentityClient {
 
   private async fetchIdentity(url: string, init: RequestInit): Promise<Response> {
     try {
-      return await fetch(url, init);
+      return await fetch(url, {
+        ...init,
+        signal: init.signal ?? AbortSignal.timeout(30_000),
+      });
     } catch (error) {
       this.logger.error('Identity background check network request failed', {
         url,
diff --git a/apps/api/src/background-checks/background-check-payment.service.spec.ts b/apps/api/src/background-checks/background-check-payment.service.spec.ts
@@ -1,4 +1,4 @@
-import { HttpException } from '@nestjs/common';
+import { HttpException, HttpStatus } from '@nestjs/common';
 import { db } from '@db';
 import { StripeService } from '../stripe/stripe.service';
 import { BackgroundCheckBillingService } from './background-check-billing.service';
@@ -34,7 +34,11 @@ describe('BackgroundCheckPaymentService', () => {
 
     await expect(
       service.charge({ organizationId: 'org_1', memberId: 'mem_1' }),
-    ).rejects.toBeInstanceOf(HttpException);
+    ).rejects.toThrow(
+      expect.objectContaining({
+        status: HttpStatus.PAYMENT_REQUIRED,
+      }),
+    );
   });
 
   it('charges Stripe with payment-method scoped idempotency key', async () => {
diff --git a/apps/api/src/background-checks/background-check-webhook.service.spec.ts b/apps/api/src/background-checks/background-check-webhook.service.spec.ts
@@ -240,7 +240,7 @@ describe('BackgroundChecksService webhooks', () => {
     );
   });
 
-  it('dedupes webhook events', async () => {
+  it('reconciles state even on duplicate webhook events', async () => {
     const payload = webhookPayload();
     const rawBody = JSON.stringify(payload);
     const timestamp = String(Date.now());
@@ -259,8 +259,11 @@ describe('BackgroundChecksService webhooks', () => {
         clientVersion: 'test',
       }),
     );
+    const identityClient = {
+      getBackgroundCheck: jest.fn().mockResolvedValue({ status: 'completed_with_flags' }),
+    };
     const service = new BackgroundChecksService(
-      {} as unknown as BackgroundCheckIdentityClient,
+      identityClient as unknown as BackgroundCheckIdentityClient,
       {} as unknown as BackgroundCheckPaymentService,
     );
 
@@ -273,6 +276,13 @@ describe('BackgroundChecksService webhooks', () => {
     });
 
     expect(result).toEqual({ ok: true, duplicate: true });
-    expect(mockedDb.backgroundCheckRequest.update).not.toHaveBeenCalled();
+    // State reconciliation still happens on duplicates
+    expect(mockedDb.backgroundCheckRequest.update).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({
+          status: 'completed_with_flags',
+        }),
+      }),
+    );
   });
 });
diff --git a/apps/api/src/background-checks/background-checks.controller.ts b/apps/api/src/background-checks/background-checks.controller.ts
@@ -56,7 +56,7 @@ export class PeopleBackgroundChecksController {
     return this.backgroundChecksService.requestForMember({
       organizationId,
       memberId,
-      employeeName: body.employeeName.trim(),
+      employeeName: body.employeeName,
       employeeEmail: body.employeeEmail.trim().toLowerCase(),
       requesterNotes: body.requesterNotes?.trim() || undefined,
       requesterEmail: authContext.userEmail ?? 'api-key@trycomp.ai',
diff --git a/apps/api/src/background-checks/background-checks.service.ts b/apps/api/src/background-checks/background-checks.service.ts
@@ -97,47 +97,17 @@ export class BackgroundChecksService {
       },
     });
 
+    let identityResult;
     try {
-      const identityResult = await this.identityClient.createBackgroundCheck({
+      identityResult = await this.identityClient.createBackgroundCheck({
         organizationId,
         memberId,
         employeeName,
         employeeEmail,
         requesterEmail,
       });
-
-      return db.backgroundCheckRequest.upsert({
-        where: { organizationId_memberId: { organizationId, memberId } },
-        create: {
-          organizationId,
-          memberId,
-          employeeName,
-          employeeEmail,
-          requesterNotes,
-          identityBackgroundCheckId: identityResult.id,
-          candidateUrl: identityResult.candidateUrl ?? null,
-          status: identityResult.status,
-          stripePaymentIntentId: payment.paymentIntentId,
-          stripePaymentStatus: payment.status,
-          stripeAmountCents: payment.amount,
-          stripeCurrency: payment.currency,
-          lastSyncedAt: new Date(),
-        },
-        update: {
-          employeeName,
-          employeeEmail,
-          requesterNotes,
-          identityBackgroundCheckId: identityResult.id,
-          candidateUrl: identityResult.candidateUrl ?? null,
-          status: identityResult.status,
-          stripePaymentIntentId: payment.paymentIntentId,
-          stripePaymentStatus: payment.status,
-          stripeAmountCents: payment.amount,
-          stripeCurrency: payment.currency,
-          lastSyncedAt: new Date(),
-        },
-      });
     } catch (error) {
+      // Only refund when the identity API call itself fails — not on DB errors
       const refundId = await this.paymentService.refund({
         organizationId,
         memberId,
@@ -169,6 +139,38 @@ export class BackgroundChecksService {
 
       throw error;
     }
+
+    return db.backgroundCheckRequest.upsert({
+      where: { organizationId_memberId: { organizationId, memberId } },
+      create: {
+        organizationId,
+        memberId,
+        employeeName,
+        employeeEmail,
+        requesterNotes,
+        identityBackgroundCheckId: identityResult.id,
+        candidateUrl: identityResult.candidateUrl ?? null,
+        status: identityResult.status,
+        stripePaymentIntentId: payment.paymentIntentId,
+        stripePaymentStatus: payment.status,
+        stripeAmountCents: payment.amount,
+        stripeCurrency: payment.currency,
+        lastSyncedAt: new Date(),
+      },
+      update: {
+        employeeName,
+        employeeEmail,
+        requesterNotes,
+        identityBackgroundCheckId: identityResult.id,
+        candidateUrl: identityResult.candidateUrl ?? null,
+        status: identityResult.status,
+        stripePaymentIntentId: payment.paymentIntentId,
+        stripePaymentStatus: payment.status,
+        stripeAmountCents: payment.amount,
+        stripeCurrency: payment.currency,
+        lastSyncedAt: new Date(),
+      },
+    });
   }
 
   async getById({
@@ -231,6 +233,7 @@ export class BackgroundChecksService {
       throw new NotFoundException('Background check request not found.');
     }
 
+    let isDuplicate = false;
     try {
       await db.backgroundCheckWebhookEvent.create({
         data: {
@@ -243,9 +246,10 @@ export class BackgroundChecksService {
       });
     } catch (error) {
       if (this.isUniqueConstraintError(error)) {
-        return { ok: true, duplicate: true };
+        isDuplicate = true;
+      } else {
+        throw error;
       }
-      throw error;
     }
 
     const reportSnapshot = await fetchCompletedReportSnapshot({
@@ -278,7 +282,7 @@ export class BackgroundChecksService {
       },
     });
 
-    return { ok: true };
+    return { ok: true, ...(isDuplicate ? { duplicate: true } : {}) };
   }
 
   private isUniqueConstraintError(error: unknown): boolean {
diff --git a/apps/api/src/background-checks/dto/request-background-check.dto.ts b/apps/api/src/background-checks/dto/request-background-check.dto.ts
@@ -1,8 +1,10 @@
-import { IsEmail, IsOptional, IsString, MaxLength, MinLength } from 'class-validator';
+import { IsEmail, IsNotEmpty, IsOptional, IsString, MaxLength } from 'class-validator';
+import { Transform } from 'class-transformer';
 
 export class RequestBackgroundCheckDto {
   @IsString()
-  @MinLength(1)
+  @Transform(({ value }) => (typeof value === 'string' ? value.trim() : value))
+  @IsNotEmpty({ message: 'employeeName must not be empty' })
   employeeName: string;
 
   @IsEmail()
diff --git a/apps/api/src/main.ts b/apps/api/src/main.ts
@@ -100,7 +100,7 @@ async function bootstrap(): Promise<void> {
   const jsonParserWithRaw = express.json({
     limit: '150mb',
     verify: (req, _res, buf) => {
-      (req as express.Request).rawBody = Buffer.from(buf);
+      (req as express.Request).rawBody = buf;
     },
   });
   const jsonParser = express.json({ limit: '150mb' });
diff --git a/apps/app/src/app/(app)/[orgId]/people/[employeeId]/components/BackgroundCheckReport.tsx b/apps/app/src/app/(app)/[orgId]/people/[employeeId]/components/BackgroundCheckReport.tsx
@@ -231,7 +231,14 @@ function eventTimestamp(event: unknown): number {
   const record = toRecord(event);
   if (!record) return 0;
   const value = record.createdAt ?? record.timestamp ?? record.processedAt;
-  if (typeof value === 'number' || typeof value === 'string') {
+  if (typeof value === 'number') {
+    return value;
+  }
+  if (typeof value === 'string') {
+    const numeric = Number(value);
+    if (!Number.isNaN(numeric) && value.trim() !== '') {
+      return numeric;
+    }
     const timestamp = new Date(value).getTime();
     return Number.isNaN(timestamp) ? 0 : timestamp;
   }
diff --git a/apps/app/src/app/(app)/[orgId]/people/[employeeId]/components/BackgroundCheckStatusView.tsx b/apps/app/src/app/(app)/[orgId]/people/[employeeId]/components/BackgroundCheckStatusView.tsx
diff --git a/apps/app/src/app/(app)/[orgId]/people/all/components/MemberRow.tsx b/apps/app/src/app/(app)/[orgId]/people/all/components/MemberRow.tsx
diff --git a/apps/app/src/app/(app)/[orgId]/people/all/components/TeamMembers.tsx b/apps/app/src/app/(app)/[orgId]/people/all/components/TeamMembers.tsx
