[comp] Production Deploy

apps/api/src/background-checks/background-check-custom.service.ts

@@ -57,8 +57,10 @@ 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;
+    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({

apps/api/src/background-checks/background-check-identity.client.spec.ts

@@ -0,0 +1,61 @@
+import { BackgroundCheckIdentityClient } from './background-check-identity.client';
+
+describe('BackgroundCheckIdentityClient idempotency key', () => {
+  const originalEnv = { ...process.env };
+  const originalFetch = global.fetch;
+
+  beforeEach(() => {
+    process.env = {
+      ...originalEnv,
+      BACKGROUND_CHECK_API_KEY: 'bc_test',
+      BACKGROUND_CHECK_API_BASE_URL: 'https://identity.test',
+    };
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+    global.fetch = originalFetch;
+  });
+
+  function mockFetchOk() {
+    const fetchMock = jest.fn().mockResolvedValue({
+      ok: true,
+      text: async () => JSON.stringify({ id: 'check_1', status: 'invited' }),
+    });
+    global.fetch = fetchMock as unknown as typeof fetch;
+    return fetchMock;
+  }
+
+  function keyFrom(fetchMock: jest.Mock): string {
+    const init = fetchMock.mock.calls[0][1] as {
+      headers: Record<string, string>;
+    };
+    return init.headers['Idempotency-Key'];
+  }
+
+  const params = {
+    organizationId: 'org_1',
+    memberId: 'mem_1',
+    employeeName: 'Ada',
+    employeeEmail: 'ada@example.com',
+    requesterEmail: 'admin@example.com',
+  };
+
+  it('forwards the provided idempotency key as the Idempotency-Key header', async () => {
+    const fetchMock = mockFetchOk();
+    await new BackgroundCheckIdentityClient().createBackgroundCheck({
+      ...params,
+      idempotencyKey: 'comp-background-check:bcr_1',
+    });
+    expect(keyFrom(fetchMock)).toBe('comp-background-check:bcr_1');
+  });
+
+  it('forwards a per-attempt retry idempotency key unchanged', async () => {
+    const fetchMock = mockFetchOk();
+    await new BackgroundCheckIdentityClient().createBackgroundCheck({
+      ...params,
+      idempotencyKey: 'comp-background-check:bcr_1:2',
+    });
+    expect(keyFrom(fetchMock)).toBe('comp-background-check:bcr_1:2');
+  });
+});

apps/api/src/background-checks/background-check-identity.client.ts

@@ -14,51 +14,61 @@ export class BackgroundCheckIdentityClient {
     employeeName: string;
     employeeEmail: string;
     requesterEmail: string;
+    idempotencyKey: string;
   }): Promise<IdentityCreateResponse> {
     const apiKey = process.env.BACKGROUND_CHECK_API_KEY;
     if (!apiKey) {
-      throw new BadRequestException('Background check service is not configured. Contact support.');
+      throw new BadRequestException(
+        'Background check service is not configured. Contact support.',
+      );
     }
 
     const baseUrl = this.baseUrl();
     const callbackUrl = this.callbackUrl();
 
-    const response = await this.fetchIdentity(`${baseUrl}/v1/background-checks`, {
-      method: 'POST',
-      headers: {
-        Authorization: `Bearer ${apiKey}`,
-        'Content-Type': 'application/json',
-        'Idempotency-Key': `comp-background-check:${params.memberId}`,
-      },
-      body: JSON.stringify({
-        candidate: {
-          name: params.employeeName,
-          email: params.employeeEmail,
-        },
-        requester: {
-          email: params.requesterEmail,
-        },
-        employmentHistory: [],
-        references: [],
-        metadata: {
-          source: 'comp',
-          compOrganizationId: params.organizationId,
-          compMemberId: params.memberId,
+    const response = await this.fetchIdentity(
+      `${baseUrl}/v1/background-checks`,
+      {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+          'Content-Type': 'application/json',
+          'Idempotency-Key': params.idempotencyKey,
         },
-        callbackUrl,
-      }),
-    });
+        body: JSON.stringify({
+          candidate: {
+            name: params.employeeName,
+            email: params.employeeEmail,
+          },
+          requester: {
+            email: params.requesterEmail,
+          },
+          employmentHistory: [],
+          references: [],
+          metadata: {
+            source: 'comp',
+            compOrganizationId: params.organizationId,
+            compMemberId: params.memberId,
+          },
+          callbackUrl,
+        }),
+      },
+    );
 
     const json = await this.readJson(response);
     if (!response.ok) {
       this.logger.error('Identity background check request failed', json);
-      throw new BadRequestException('Identity background check request failed.');
+      throw new BadRequestException(
+        'Identity background check request failed.',
+      );
     }
 
     return identityCreateResponseSchema.parse(json);
   }
 
-  async getBackgroundCheck(identityBackgroundCheckId: string): Promise<unknown> {
+  async getBackgroundCheck(
+    identityBackgroundCheckId: string,
+  ): Promise<unknown> {
     const apiKey = process.env.BACKGROUND_CHECK_API_KEY;
     if (!apiKey) return null;
 
@@ -76,19 +86,22 @@ export class BackgroundCheckIdentityClient {
 
   private baseUrl(): string {
     const baseUrl =
-      process.env.BACKGROUND_CHECK_API_BASE_URL ?? 'https://glad-sturgeon-729.convex.site';
+      process.env.BACKGROUND_CHECK_API_BASE_URL ??
+      'https://glad-sturgeon-729.convex.site';
     return baseUrl.replace(/\/+$/, '');
   }
 
   private callbackUrl(): string {
     const endpoint = process.env.BACKGROUND_WH_ENDPOINT?.trim();
-    return (endpoint || 'https://api.trycomp.ai/v1/background-checks/webhook').replace(
-      /\/+$/,
-      '',
-    );
+    return (
+      endpoint || 'https://api.trycomp.ai/v1/background-checks/webhook'
+    ).replace(/\/+$/, '');
   }
 
-  private async fetchIdentity(url: string, init: RequestInit): Promise<Response> {
+  private async fetchIdentity(
+    url: string,
+    init: RequestInit,
+  ): Promise<Response> {
     try {
       return await fetch(url, {
         ...init,

apps/api/src/background-checks/background-check-report-snapshot.ts

@@ -40,7 +40,9 @@ export async function fetchCompletedReportSnapshot({
   }
 
   try {
-    const snapshot = await identityClient.getBackgroundCheck(identityBackgroundCheckId);
+    const snapshot = await identityClient.getBackgroundCheck(
+      identityBackgroundCheckId,
+    );
     return toInputJsonValue(snapshot);
   } catch {
     return null;

apps/api/src/background-checks/background-check-retry.ts

@@ -0,0 +1,145 @@
+import { BadRequestException, NotFoundException } from '@nestjs/common';
+import { BackgroundCheckStatus, db, Prisma } from '@db';
+import type { BackgroundCheckIdentityClient } from './background-check-identity.client';
+
+type GetForMemberFn = (params: {
+  organizationId: string;
+  memberId: string;
+}) => Promise<{
+  id: string;
+  rerunCount: number;
+  employeeName: string;
+  employeeEmail: string;
+  status: BackgroundCheckStatus;
+} | null>;
+
+export function assertTransitionAllowed(
+  action: 'cancel' | 'retry',
+  status: BackgroundCheckStatus,
+): void {
+  const allowed: Record<'cancel' | 'retry', BackgroundCheckStatus[]> = {
+    cancel: [
+      BackgroundCheckStatus.invited,
+      BackgroundCheckStatus.in_progress,
+      BackgroundCheckStatus.in_review,
+    ],
+    retry: [BackgroundCheckStatus.failed, BackgroundCheckStatus.cancelled],
+  };
+  if (!allowed[action].includes(status)) {
+    throw new BadRequestException(
+      `Cannot ${action} a background check in '${status}' status.`,
+    );
+  }
+}
+
+export async function cancelForMember({
+  organizationId,
+  memberId,
+  getForMember,
+}: {
+  organizationId: string;
+  memberId: string;
+  getForMember: GetForMemberFn;
+}) {
+  const existing = await getForMember({ organizationId, memberId });
+  if (!existing) {
+    throw new NotFoundException('Background check not found.');
+  }
+  assertTransitionAllowed('cancel', existing.status);
+
+  return db.backgroundCheckRequest.update({
+    where: { organizationId_memberId: { organizationId, memberId } },
+    data: {
+      status: BackgroundCheckStatus.cancelled,
+      lastSyncedAt: new Date(),
+    },
+  });
+}
+
+export async function deleteForMember({
+  organizationId,
+  memberId,
+  getForMember,
+}: {
+  organizationId: string;
+  memberId: string;
+  getForMember: GetForMemberFn;
+}): Promise<{ ok: true }> {
+  const existing = await getForMember({ organizationId, memberId });
+  if (!existing) {
+    throw new NotFoundException('Background check not found.');
+  }
+  // Hard delete; webhookEvents cascade via the FK. Frees the
+  // @@unique([organizationId, memberId]) constraint for a fresh request.
+  await db.backgroundCheckRequest.delete({
+    where: { organizationId_memberId: { organizationId, memberId } },
+  });
+  return { ok: true };
+}
+
+export async function retryForMember({
+  organizationId,
+  memberId,
+  requesterEmail,
+  identityClient,
+  getForMember,
+}: {
+  organizationId: string;
+  memberId: string;
+  requesterEmail: string;
+  identityClient: BackgroundCheckIdentityClient;
+  getForMember: GetForMemberFn;
+}) {
+  const existing = await getForMember({ organizationId, memberId });
+  if (!existing) {
+    throw new NotFoundException('Background check not found.');
+  }
+  assertTransitionAllowed('retry', existing.status);
+
+  const attempt = existing.rerunCount + 1;
+  const where = { organizationId_memberId: { organizationId, memberId } };
+
+  // Free retry: no charge. Create a fresh Identity check first (varied
+  // idempotency key) so a late webhook from the prior check cannot match
+  // the row after we swap in the new id.
+  let identityResult;
+  try {
+    identityResult = await identityClient.createBackgroundCheck({
+      organizationId,
+      memberId,
+      employeeName: existing.employeeName,
+      employeeEmail: existing.employeeEmail,
+      requesterEmail,
+      // Per-record, per-attempt key so each retry creates a fresh vendor
+      // check rather than colliding with a prior attempt's idempotency key.
+      idempotencyKey: `comp-background-check:${existing.id}:${attempt}`,
+    });
+  } catch (error) {
+    // Restore the prior status (retry is only allowed from 'failed' or
+    // 'cancelled'). Forcing 'failed' here would strip a cancelled check of the
+    // webhook terminal-guard and let a late vendor webhook resurrect it.
+    await db.backgroundCheckRequest.update({
+      where,
+      data: { status: existing.status, lastSyncedAt: new Date() },
+    });
+    throw error;
+  }
+
+  return db.backgroundCheckRequest.update({
+    where,
+    data: {
+      identityBackgroundCheckId: identityResult.id,
+      candidateUrl: identityResult.candidateUrl ?? null,
+      status: identityResult.status,
+      rerunCount: attempt,
+      identityStatus: null,
+      employmentStatus: null,
+      referenceStatus: null,
+      rightToWorkStatus: null,
+      adjudicationStatus: null,
+      reportSnapshot: Prisma.JsonNull,
+      reportSyncedAt: null,
+      lastSyncedAt: new Date(),
+    },
+  });
+}

apps/api/src/background-checks/background-check-webhook-signature.ts

@@ -22,7 +22,10 @@ export function verifyBackgroundCheckWebhookSignature({
   }
 
   const timestamp = Number(timestampHeader);
-  if (!Number.isFinite(timestamp) || Math.abs(Date.now() - timestamp) > WEBHOOK_MAX_SKEW_MS) {
+  if (
+    !Number.isFinite(timestamp) ||
+    Math.abs(Date.now() - timestamp) > WEBHOOK_MAX_SKEW_MS
+  ) {
     throw new UnauthorizedException('Webhook timestamp is invalid.');
   }