feat(billing): add payment recovery and operations(Phase 7 Reconcile + Ops)

apps/api/src/admin/admin.module.ts

@@ -6,6 +6,7 @@
 
 import { Module } from '@nestjs/common'
 import { AdminObservabilityController } from './controllers/observability.controller'
+import { AdminBillingController } from './controllers/billing.controller'
 import { AdminOverviewController } from './controllers/overview.controller'
 import { AdminRunnerController } from './controllers/runner.controller'
 import { AdminBoxController } from './controllers/box.controller'
@@ -25,10 +26,17 @@ import { OrganizationModule } from '../organization/organization.module'
 import { UserModule } from '../user/user.module'
 import { AuditModule } from '../audit/audit.module'
 import { AuditService } from '../audit/services/audit.service'
+import { BillingModule } from '../billing/billing.module'
 
 @Module({
-  imports: [BoxModule, RegionModule, OrganizationModule, UserModule, AuditModule],
-  controllers: [AdminRunnerController, AdminBoxController, AdminOverviewController, AdminObservabilityController],
+  imports: [BoxModule, RegionModule, OrganizationModule, UserModule, AuditModule, BillingModule],
+  controllers: [
+    AdminRunnerController,
+    AdminBoxController,
+    AdminOverviewController,
+    AdminObservabilityController,
+    AdminBillingController,
+  ],
   providers: [
     AdminOverviewService,
     AdminObservabilityService,

apps/api/src/admin/controllers/billing.controller.spec.ts

@@ -0,0 +1,47 @@
+/*
+ * Copyright BoxLite AI, 2026
+ * SPDX-License-Identifier: AGPL-3.0
+ */
+
+import { GUARDS_METADATA } from '@nestjs/common/constants'
+import { Request } from 'express'
+import { AUDIT_CONTEXT_KEY, AuditContext } from '../../audit/decorators/audit.decorator'
+import { AuditAction } from '../../audit/enums/audit-action.enum'
+import { AuditTarget } from '../../audit/enums/audit-target.enum'
+import { CombinedAuthGuard } from '../../auth/combined-auth.guard'
+import { SystemActionGuard } from '../../auth/system-action.guard'
+import { RequiredApiRole } from '../../common/decorators/required-role.decorator'
+import { SystemRole } from '../../user/enums/system-role.enum'
+import { AdminBillingController } from './billing.controller'
+
+describe('AdminBillingController', () => {
+  const health = { collectHealth: jest.fn() }
+  const payments = {
+    scheduledPaymentRecovery: jest.fn(),
+    reconcileTopUp: jest.fn(),
+    reconcilePaymentSetup: jest.fn(),
+  }
+  const controller = new AdminBillingController(health as never, payments as never)
+
+  beforeEach(() => jest.clearAllMocks())
+
+  it('requires authenticated Admin API access', () => {
+    expect(Reflect.getMetadata(GUARDS_METADATA, AdminBillingController)).toEqual([CombinedAuthGuard, SystemActionGuard])
+    expect(Reflect.getMetadata(RequiredApiRole.KEY, AdminBillingController)).toEqual([SystemRole.ADMIN])
+  })
+
+  it('audits targeted top-up reconciliation without exposing provider secrets', async () => {
+    payments.reconcileTopUp.mockResolvedValue(true)
+    await expect(controller.reconcileTopUp('top-up-1')).resolves.toEqual({ claimed: true })
+    expect(payments.reconcileTopUp).toHaveBeenCalledWith('top-up-1', expect.any(Date), true)
+
+    const context = Reflect.getMetadata(
+      AUDIT_CONTEXT_KEY,
+      AdminBillingController.prototype.reconcileTopUp,
+    ) as AuditContext
+    expect(context).toMatchObject({ action: AuditAction.UPDATE, targetType: AuditTarget.OBSERVABILITY })
+    expect(context.targetIdFromRequest?.({ params: { topUpId: 'top-up-1' } } as unknown as Request)).toBe(
+      'billing:top-up:top-up-1',
+    )
+  })
+})

apps/api/src/admin/controllers/billing.controller.ts

@@ -0,0 +1,78 @@
+/*
+ * Copyright BoxLite AI, 2026
+ * SPDX-License-Identifier: AGPL-3.0
+ */
+
+import { Controller, Get, HttpCode, Param, ParseUUIDPipe, Post, UseGuards } from '@nestjs/common'
+import { ApiBearerAuth, ApiOAuth2, ApiOperation, ApiTags } from '@nestjs/swagger'
+import { Audit } from '../../audit/decorators/audit.decorator'
+import { AuditAction } from '../../audit/enums/audit-action.enum'
+import { AuditTarget } from '../../audit/enums/audit-target.enum'
+import { CombinedAuthGuard } from '../../auth/combined-auth.guard'
+import { SystemActionGuard } from '../../auth/system-action.guard'
+import { BillingOpsService } from '../../billing/billing-ops.service'
+import { PaymentService } from '../../billing/payment/payment.service'
+import { RequiredApiRole } from '../../common/decorators/required-role.decorator'
+import { SystemRole } from '../../user/enums/system-role.enum'
+
+@ApiTags('admin')
+@Controller('admin/billing')
+@UseGuards(CombinedAuthGuard, SystemActionGuard)
+@RequiredApiRole([SystemRole.ADMIN])
+@ApiOAuth2(['openid', 'profile', 'email'])
+@ApiBearerAuth()
+export class AdminBillingController {
+  constructor(
+    private readonly billingOps: BillingOpsService,
+    private readonly payments: PaymentService,
+  ) {}
+
+  @Get('health')
+  @HttpCode(200)
+  @ApiOperation({ summary: 'Get Billing recovery and ledger health', operationId: 'adminGetBillingHealth' })
+  @Audit({
+    action: AuditAction.READ,
+    targetType: AuditTarget.OBSERVABILITY,
+    targetIdFromRequest: () => 'billing:health',
+  })
+  health() {
+    return this.billingOps.collectHealth()
+  }
+
+  @Post('reconcile')
+  @HttpCode(200)
+  @ApiOperation({ summary: 'Run due Billing recovery work', operationId: 'adminReconcileBilling' })
+  @Audit({
+    action: AuditAction.UPDATE,
+    targetType: AuditTarget.OBSERVABILITY,
+    targetIdFromRequest: () => 'billing:reconcile',
+  })
+  async reconcile() {
+    await this.payments.scheduledPaymentRecovery()
+    return this.billingOps.collectHealth()
+  }
+
+  @Post('reconcile/top-up/:topUpId')
+  @HttpCode(200)
+  @ApiOperation({ summary: 'Force provider reconciliation for one top-up', operationId: 'adminReconcileTopUp' })
+  @Audit({
+    action: AuditAction.UPDATE,
+    targetType: AuditTarget.OBSERVABILITY,
+    targetIdFromRequest: (request) => `billing:top-up:${request.params.topUpId}`,
+  })
+  async reconcileTopUp(@Param('topUpId', ParseUUIDPipe) topUpId: string) {
+    return { claimed: await this.payments.reconcileTopUp(topUpId, new Date(), true) }
+  }
+
+  @Post('reconcile/setup/:organizationId')
+  @HttpCode(200)
+  @ApiOperation({ summary: 'Force provider reconciliation for one payment setup', operationId: 'adminReconcileSetup' })
+  @Audit({
+    action: AuditAction.UPDATE,
+    targetType: AuditTarget.OBSERVABILITY,
+    targetIdFromRequest: (request) => `billing:setup:${request.params.organizationId}`,
+  })
+  async reconcileSetup(@Param('organizationId', ParseUUIDPipe) organizationId: string) {
+    return { claimed: await this.payments.reconcilePaymentSetup(organizationId, new Date(), true) }
+  }
+}