Merge branch 'main' into fix/move-stripe-auto-approve-to-api

Author: tofikwest

apps/api/src/billing/billing.service.spec.ts

@@ -208,6 +208,87 @@ describe('BillingService', () => {
     );
   });
 
+  it('aggregates wallet credit balances per product in getStatus', async () => {
+    // The customer-facing /v1/billing/status response is the only
+    // surface the pentest + BG-check UIs read from. If we ever stop
+    // including creditBalances here, both UIs silently regress to
+    // paywalling users whose admin-granted credits would be consumed
+    // by the create endpoint. Lock the contract with this test.
+    const listBalances = jest.fn().mockResolvedValue([
+      {
+        id: 'bcb_1',
+        productKey: 'pentest',
+        skuKey: null,
+        balance: 3,
+        totalGranted: 5,
+        totalConsumed: 2,
+        totalRefunded: 0,
+        lastSource: 'manual',
+        updatedAt: '2026-05-01T00:00:00.000Z',
+      },
+      {
+        id: 'bcb_2',
+        productKey: 'pentest',
+        skuKey: 'pentest_monthly_1',
+        balance: 2,
+        totalGranted: 2,
+        totalConsumed: 0,
+        totalRefunded: 0,
+        lastSource: 'topup',
+        updatedAt: '2026-05-01T00:00:00.000Z',
+      },
+      {
+        id: 'bcb_3',
+        productKey: 'background_check',
+        skuKey: null,
+        balance: 4,
+        totalGranted: 4,
+        totalConsumed: 0,
+        totalRefunded: 0,
+        lastSource: 'manual',
+        updatedAt: '2026-05-01T00:00:00.000Z',
+      },
+    ]);
+    const service = new BillingService(
+      mockStripeService({
+        invoices: { list: jest.fn().mockResolvedValue({ data: [] }) },
+        customers: { retrieve: jest.fn().mockResolvedValue({}) },
+        paymentMethods: { retrieve: jest.fn() },
+      }),
+      { syncSubscriptionItem: jest.fn() } as never,
+      { listBalances } as never,
+    );
+
+    const result = await service.getStatus('org_1');
+
+    expect(listBalances).toHaveBeenCalledWith('org_1');
+    expect(result.creditBalances).toEqual(
+      expect.arrayContaining([
+        { productKey: 'pentest', balance: 5 },
+        { productKey: 'background_check', balance: 4 },
+      ]),
+    );
+    expect(result.creditBalances).toHaveLength(2);
+  });
+
+  it('returns an empty creditBalances array when no credits service is wired in', async () => {
+    // BillingCreditsService is @Optional() so unit tests can keep
+    // hand-constructing BillingService without it. Verify the absent-
+    // dependency branch produces a typesafe empty array, not undefined.
+    const service = new BillingService(
+      mockStripeService({
+        invoices: { list: jest.fn().mockResolvedValue({ data: [] }) },
+        customers: { retrieve: jest.fn().mockResolvedValue({}) },
+        paymentMethods: { retrieve: jest.fn() },
+      }),
+      { syncSubscriptionItem: jest.fn() } as never,
+    );
+
+    const result = await service.getStatus('org_1');
+
+    expect(result.creditBalances).toEqual([]);
+  });
+
   it('marks trial eligibility false after any product subscription history', async () => {
     organizationBillingSubscriptionFindMany.mockResolvedValue([
       {

apps/api/src/billing/billing.service.ts

@@ -2,6 +2,7 @@ import {
   BadRequestException,
   Injectable,
   NotFoundException,
+  Optional,
 } from '@nestjs/common';
 import { db } from '@db';
 import {
@@ -12,6 +13,7 @@ import {
   isSubscriptionBillingSkuKey,
 } from '@trycompai/billing';
 import { StripeService } from '../stripe/stripe.service';
+import { BillingCreditsService } from './billing-credits.service';
 import { findOrCreateBillingCustomer } from './billing-customer';
 import { BillingEntitlementsService } from './billing-entitlements.service';
 import { listBillingInvoices } from './billing-invoices';
@@ -38,6 +40,10 @@ export class BillingService {
   constructor(
     private readonly stripeService: StripeService,
     private readonly entitlements: BillingEntitlementsService,
+    // Optional so existing unit tests that hand-construct BillingService
+    // (without a credits service) keep working. In production the
+    // BillingModule always provides it.
+    @Optional() private readonly credits?: BillingCreditsService,
   ) {}
 
   async getStatus(organizationId: string): Promise<BillingStatus> {
@@ -67,18 +73,31 @@ export class BillingService {
       db.backgroundCheckRequest.count({ where: { organizationId } }),
       db.securityPenetrationTestRun.count({ where: { organizationId } }),
     ]);
-    const [invoices, preferences, usageRows] = await Promise.all([
-      listBillingInvoices({
-        stripeService: this.stripeService,
-        stripeCustomerId: billing?.stripeCustomerId ?? null,
-      }),
-      getBillingPreferences({
-        stripeService: this.stripeService,
-        stripeCustomerId: billing?.stripeCustomerId ?? null,
-        fallbackCompanyName: organization.name,
-      }),
-      listBillingUsageRows({ organizationId, subscriptions }),
-    ]);
+    const [invoices, preferences, usageRows, creditBalances] =
+      await Promise.all([
+        listBillingInvoices({
+          stripeService: this.stripeService,
+          stripeCustomerId: billing?.stripeCustomerId ?? null,
+        }),
+        getBillingPreferences({
+          stripeService: this.stripeService,
+          stripeCustomerId: billing?.stripeCustomerId ?? null,
+          fallbackCompanyName: organization.name,
+        }),
+        listBillingUsageRows({ organizationId, subscriptions }),
+        // Sum wallet balances per product. There can be multiple
+        // BillingCreditBalance rows per (org, product) when grants are
+        // scoped to a specific SKU, so we aggregate before returning.
+        this.credits
+          ? this.credits.listBalances(organizationId)
+          : Promise.resolve([]),
+      ]);
+
+    const creditBalancesByProduct = new Map<BillingProductKey, number>();
+    for (const balance of creditBalances) {
+      const current = creditBalancesByProduct.get(balance.productKey) ?? 0;
+      creditBalancesByProduct.set(balance.productKey, current + balance.balance);
+    }
 
     return {
       hasBilling: !!billing,
@@ -98,6 +117,9 @@ export class BillingService {
         currentPeriodEnd: subscription.currentPeriodEnd?.toISOString() ?? null,
         cancelAtPeriodEnd: subscription.cancelAtPeriodEnd,
       })),
+      creditBalances: Array.from(creditBalancesByProduct.entries()).map(
+        ([productKey, balance]) => ({ productKey, balance }),
+      ),
       invoices,
     };
   }

apps/api/src/billing/billing.types.ts

@@ -1,3 +1,4 @@
+import type { BillingProductKey } from '@trycompai/billing';
 import type { BillingInvoice } from './billing-invoices';
 import type { BillingPreferences } from './billing-preferences';
 
@@ -24,6 +25,15 @@ export interface BillingStatus {
     currentPeriodEnd: string | null;
     cancelAtPeriodEnd: boolean;
   }>;
+  // Aggregated wallet balance per product. Mirrors what
+  // `BillingEntitlementsService.tryConsumeIncludedUsageForProduct` falls
+  // back to when a Stripe subscription is missing or exhausted, so the UI
+  // can keep its allowance display in sync with the backend's actual
+  // consumption decision.
+  creditBalances: Array<{
+    productKey: BillingProductKey;
+    balance: number;
+  }>;
   invoices: BillingInvoice[];
 }
 

apps/app/src/app/(app)/[orgId]/people/[employeeId]/components/backgroundCheckTypes.ts

@@ -43,6 +43,13 @@ export interface BackgroundCheckBillingStatus {
     currentPeriodEnd: string | null;
     cancelAtPeriodEnd: boolean;
   }>;
+  // Wallet credits per product. Optional because older API responses
+  // and existing test fixtures don't set it; treated as zero balance
+  // when absent.
+  creditBalances?: Array<{
+    productKey: 'pentest' | 'background_check';
+    balance: number;
+  }>;
 }
 
 export function isCompletedBackgroundCheck(status: BackgroundCheckStatus): boolean {

apps/app/src/app/(app)/[orgId]/people/[employeeId]/components/useEmployeeBackgroundCheckData.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, it } from 'vitest';
+import type { BackgroundCheckBillingStatus } from './backgroundCheckTypes';
+import { getBackgroundChecksRemaining } from './useEmployeeBackgroundCheckData';
+
+function status(
+  overrides: Partial<BackgroundCheckBillingStatus> = {},
+): BackgroundCheckBillingStatus {
+  return {
+    hasPaymentMethod: false,
+    setupAt: null,
+    ...overrides,
+  };
+}
+
+describe('getBackgroundChecksRemaining', () => {
+  it('returns null when billing status has not loaded', () => {
+    expect(getBackgroundChecksRemaining({ billingStatus: undefined })).toBeNull();
+  });
+
+  it('returns null when no subscription and no wallet credits exist', () => {
+    expect(getBackgroundChecksRemaining({ billingStatus: status() })).toBeNull();
+  });
+
+  it('returns subscription remainder when an active subscription exists', () => {
+    expect(
+      getBackgroundChecksRemaining({
+        billingStatus: status({
+          subscriptions: [
+            {
+              skuKey: 'background_checks_monthly_3',
+              status: 'active',
+              includedQuantity: 3,
+              usedQuantity: 1,
+              currentPeriodStart: null,
+              currentPeriodEnd: null,
+              cancelAtPeriodEnd: false,
+            },
+          ],
+        }),
+      }),
+    ).toBe(2);
+  });
+
+  it('returns wallet balance when no subscription but wallet credits exist', () => {
+    // Admin grant flow: organization has no subscription, platform
+    // admin granted 5 BG-check credits. Backend would consume from
+    // wallet on POST, so the wizard must allow the request.
+    expect(
+      getBackgroundChecksRemaining({
+        billingStatus: status({
+          creditBalances: [{ productKey: 'background_check', balance: 5 }],
+        }),
+      }),
+    ).toBe(5);
+  });
+
+  it('sums subscription remainder and wallet credits', () => {
+    expect(
+      getBackgroundChecksRemaining({
+        billingStatus: status({
+          subscriptions: [
+            {
+              skuKey: 'background_checks_monthly_3',
+              status: 'trialing',
+              includedQuantity: 3,
+              usedQuantity: 3,
+              currentPeriodStart: null,
+              currentPeriodEnd: null,
+              cancelAtPeriodEnd: false,
+            },
+          ],
+          creditBalances: [{ productKey: 'background_check', balance: 5 }],
+        }),
+      }),
+    ).toBe(5);
+  });
+
+  it('ignores pentest wallet credits when computing background-check allowance', () => {
+    expect(
+      getBackgroundChecksRemaining({
+        billingStatus: status({
+          creditBalances: [{ productKey: 'pentest', balance: 10 }],
+        }),
+      }),
+    ).toBeNull();
+  });
+
+  it('ignores cancelled subscriptions', () => {
+    expect(
+      getBackgroundChecksRemaining({
+        billingStatus: status({
+          subscriptions: [
+            {
+              skuKey: 'background_checks_monthly_3',
+              status: 'canceled',
+              includedQuantity: 3,
+              usedQuantity: 0,
+              currentPeriodStart: null,
+              currentPeriodEnd: null,
+              cancelAtPeriodEnd: false,
+            },
+          ],
+          creditBalances: [{ productKey: 'background_check', balance: 2 }],
+        }),
+      }),
+    ).toBe(2);
+  });
+});

apps/app/src/app/(app)/[orgId]/people/[employeeId]/components/useEmployeeBackgroundCheckData.ts

@@ -54,11 +54,31 @@ export function getBackgroundChecksRemaining({
 }: {
   billingStatus: BackgroundCheckBillingStatus | undefined;
 }): number | null {
-  const subscription = (billingStatus?.subscriptions ?? []).find(
+  if (!billingStatus) return null;
+  const subscription = (billingStatus.subscriptions ?? []).find(
     (item) =>
       getBillingSkuProductKey(item.skuKey) === 'background_check' &&
       (item.status === 'active' || item.status === 'trialing'),
   );
-  if (!subscription) return null;
-  return Math.max(subscription.includedQuantity - subscription.usedQuantity, 0);
+  // Wallet credits granted by platform admins. The backend's
+  // `BillingEntitlementsService.tryConsumeIncludedUsageForProduct`
+  // falls back to this wallet when no active subscription exists or
+  // the subscription's included usage is exhausted, so we mirror that
+  // logic here — otherwise the wizard paywalls users whose admin-
+  // granted credits would actually be consumed by the create call.
+  const walletBalance =
+    (billingStatus.creditBalances ?? []).find(
+      (entry) => entry.productKey === 'background_check',
+    )?.balance ?? 0;
+  if (!subscription) {
+    // Returning `null` keeps the existing "no allowance — go pick a
+    // plan" wizard path. We only have a positive allowance if there
+    // are wallet credits to consume.
+    return walletBalance > 0 ? walletBalance : null;
+  }
+  const subscriptionRemaining = Math.max(
+    subscription.includedQuantity - subscription.usedQuantity,
+    0,
+  );
+  return subscriptionRemaining + walletBalance;
 }