feat: setup the invoice backend

apps/edr-freight-api/src/modules/billing/billing.service.ts

@@ -9,6 +9,16 @@ import { InvoiceRepository } from "./invoice.repository";
 import { InvoiceLineRepository } from "./invoice-line.repository";
 import { PaymentService } from "../payment/payment.service";
 import { InitiateResponseDto } from "../payment/payments.dto";
+import { CompaniesService } from "../companies/companies.service";
+
+/** Options forwarded to the payment gateway when settling an invoice. */
+export interface PayInvoiceOptions {
+  method?: string;
+  platform?: "web" | "mobile";
+  payerAccount?: string;
+  returnUrl?: string;
+  failureUrl?: string;
+}
 
 /** Default invoice payment-term window, in days, used to compute `dueAt`. */
 const DEFAULT_DUE_DAYS = 14;
@@ -84,6 +94,7 @@ export class BillingService {
     private readonly events: EventEmitter2,
     @Inject(forwardRef(() => PaymentService))
     private readonly payment: PaymentService,
+    private readonly companies: CompaniesService,
   ) { }
 
   // ── Reads ──────────────────────────────────────────────────────────────────
@@ -104,6 +115,64 @@ export class BillingService {
     return { ...invoice, lines } as Invoice & { lines: InvoiceLine[] };
   }
 
+  // ── Customer-scoped reads (portal) ───────────────────────────────────────────
+
+  /** Resolve the customer's company id from their IAM user id (null if none). */
+  async resolveCompanyId(userId: string): Promise<string | null> {
+    try {
+      const { company } = await this.companies.getCompanyInfoByUserId(userId);
+      return company?.id ?? null;
+    } catch {
+      return null;
+    }
+  }
+
+  /** Every invoice billed to a company, newest first, with billing relations. */
+  findByCompany(companyId: string): Promise<Invoice[]> {
+    return this.invoices.findAll({
+      where: { companyId },
+      relations: { company: true, companyProfile: true },
+      order: { createdAt: "DESC" },
+    });
+  }
+
+  /** Invoices for the signed-in customer; empty when they have no company. */
+  async findForUser(userId: string): Promise<Invoice[]> {
+    const companyId = await this.resolveCompanyId(userId);
+    return companyId ? this.findByCompany(companyId) : [];
+  }
+
+  /** Company-scoped invoice detail (+ lines); 404 when not owned by the user. */
+  async findByIdForUser(
+    id: string,
+    userId: string,
+  ): Promise<Invoice & { lines: InvoiceLine[] }> {
+    const companyId = await this.resolveCompanyId(userId);
+    const invoice = await this.findById(id);
+    if (!companyId || invoice.companyId !== companyId) {
+      throw new NotFoundException(`Invoice ${id} not found`);
+    }
+    return invoice;
+  }
+
+  /**
+   * Initiate gateway payment for one of the customer's own invoices. Verifies
+   * ownership, then charges whichever open invoice the source currently has
+   * (see {@link payInvoice}).
+   */
+  async payInvoiceForUser(
+    id: string,
+    userId: string,
+    opts: PayInvoiceOptions = {},
+  ): Promise<InitiateResponseDto> {
+    const invoice = await this.findByIdForUser(id, userId);
+    return this.payInvoice(
+      invoice.source as Freight.InvoiceSource,
+      invoice.sourceId,
+      opts,
+    );
+  }
+
   // ── Generation ───────────────────────────────────────────────────────────────
 
   /** `FRT-YYYYMMDD-00001` — sequential per day, within the active transaction. */