refactor(payment): centralize invoice processing with detailed tracking and configurable logging

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

@@ -49,7 +49,6 @@ const DEFAULT_DUE_DAYS = 14;
 
 /** Statuses an invoice can still be settled (paid/refunded/cancelled) from. */
 const OPEN_STATUSES: Freight.InvoiceStatus[] = [
-  Freight.InvoiceStatus.Draft,
   Freight.InvoiceStatus.Issued,
   Freight.InvoiceStatus.Pending,
   Freight.InvoiceStatus.PartiallyPaid,
@@ -285,20 +284,15 @@ export class BillingService {
 
   /**
    * 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}).
+   * ownership, then charges the invoice directly by ID (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,
-    );
+    await this.findByIdForUser(id, userId);
+    return this.payInvoice(id, opts);
   }
 
   /** Sealed invoice PDF for one of the customer's own invoices (ownership-checked). */
@@ -422,23 +416,39 @@ export class BillingService {
   // ── State transitions ────────────────────────────────────────────────────────
 
   /**
-   * Mark an invoice paid and link the gateway payment, then emit
-   * `${source}.invoice.paid`. Full-payment only — no partial settlement.
-   * No-op when the invoice is already paid. Pass `manager` to enlist in a
-   * caller's transaction.
+   * Mark an invoice paid, stamp the paid timestamp, sync paid/balance amounts,
+   * link the gateway payment, then emit `${source}.invoice.paid`. Full-payment
+   * only — no partial settlement. No-op when the invoice is already paid.
+   * Pass `manager` to enlist in a caller's transaction.
    */
   async markInvoiceAsPaid(
     invoiceId: string,
     paymentId: string | null = null,
     manager?: EntityManager,
   ): Promise<Invoice | null> {
-    return this.transition(
-      invoiceId,
-      Freight.InvoiceStatus.Paid,
-      "paid",
-      { paymentId: paymentId ?? undefined },
-      manager,
-    );
+    const mg = manager ?? this.dataSource.manager;
+    const invoice = await mg.findOne(Invoice, { where: { id: invoiceId } });
+    if (!invoice) throw new NotFoundException(`Invoice ${invoiceId} not found`);
+    if (invoice.status === Freight.InvoiceStatus.Paid) return invoice;
+
+    await mg.update(Invoice, { id: invoiceId }, {
+      status: Freight.InvoiceStatus.Paid,
+      paymentId,
+      paidAt: invoice.paidAt ?? new Date(),
+      paidAmount: invoice.totalAmount,
+      balanceAmount: 0,
+    } as never);
+
+    const updated = {
+      ...invoice,
+      status: Freight.InvoiceStatus.Paid,
+      paymentId,
+      paidAt: invoice.paidAt ?? new Date(),
+      paidAmount: invoice.totalAmount,
+      balanceAmount: 0,
+    } as Invoice;
+    this.emitInvoiceEvent("paid", updated);
+    return updated;
   }
 
   /**
@@ -628,56 +638,24 @@ export class BillingService {
   }
 
   /**
-   * Settle a source's currently-open invoice as paid and link the gateway
-   * payment, then emit `${source}.invoice.paid`. Resolves the open invoice then
-   * delegates to {@link markInvoiceAsPaid}. Full-payment only — no partial
-   * settlement. No-op (returns null) when the source has no open invoice.
-   *
-   * Type-blind by design: settles whichever invoice is due; any per-type reaction
-   * belongs in the `${source}.invoice.paid` handler, which reads `invoice.type`.
-   * Pass the caller's transaction `manager` to enlist in its DB transaction.
-   *
-   * NOTE: the booking flow settles via {@link payInvoice} + the `payment.succeeded`
-   * event ({@link settleByPaymentId}); this source-keyed settle is a generic helper
-   * for callers that settle by source rather than by gateway intent id.
+   * Pass `type` to select a specific invoice when a source carries several (e.g.
+   * a booking's up-front vs final charge); omit it to settle whichever single
+   * invoice is currently open. Returns the most recent matching open (unpaid,
+   * non-cancelled) invoice.
    */
-  async settlePayable(
+  findInvoice(
     source: Freight.InvoiceSource,
     sourceId: string,
-    paymentId: string | null,
-    manager?: EntityManager,
+    type?: string,
   ): Promise<Invoice | null> {
-    const mg = manager ?? this.dataSource.manager;
-    const invoice = await mg.findOne(Invoice, {
-      where: { source, sourceId, status: In(OPEN_STATUSES) },
+    return this.dataSource.getRepository(Invoice).findOne({
+      where: {
+        source,
+        sourceId,
+        ...(type ? { type } : {}),
+      },
       order: { issuedAt: "DESC" },
     });
-    if (!invoice) return null;
-
-    return this.markInvoiceAsPaid(invoice.id, paymentId, mg);
-  }
-
-  /**
-   * Refund a source's paid invoice, then emit `${source}.invoice.refunded`.
-   * Resolves the paid invoice then delegates to {@link markInvoiceAsRefunded}.
-   * No-op (returns null) when the source has no paid invoice.
-   *
-   * Pass the caller's transaction `manager` (e.g. from `payment.service.refund`)
-   * to enlist in its DB transaction.
-   */
-  async refundPayable(
-    source: Freight.InvoiceSource,
-    sourceId: string,
-    manager?: EntityManager,
-  ): Promise<Invoice | null> {
-    const mg = manager ?? this.dataSource.manager;
-    const invoice = await mg.findOne(Invoice, {
-      where: { source, sourceId, status: Freight.InvoiceStatus.Paid },
-      order: { issuedAt: "DESC" },
-    });
-    if (!invoice) return null;
-
-    return this.markInvoiceAsRefunded(invoice.id, mg);
   }
 
   /**
@@ -693,11 +671,17 @@ export class BillingService {
   async expirePayable(
     source: Freight.InvoiceSource,
     sourceId: string,
+    type?: string,
     manager?: EntityManager,
   ): Promise<Invoice | null> {
     const mg = manager ?? this.dataSource.manager;
     const invoice = await mg.findOne(Invoice, {
-      where: { source, sourceId, status: In(OPEN_STATUSES) },
+      where: {
+        source,
+        sourceId,
+        status: In(OPEN_STATUSES),
+        ...(type ? { type } : {}),
+      },
       order: { issuedAt: "DESC" },
     });
     if (!invoice) return null;
@@ -721,11 +705,17 @@ export class BillingService {
     source: Freight.InvoiceSource,
     sourceId: string,
     dueAt: Date,
+    type?: string,
     manager?: EntityManager,
   ): Promise<void> {
     const mg = manager ?? this.dataSource.manager;
     const invoice = await mg.findOne(Invoice, {
-      where: { source, sourceId, status: In(OPEN_STATUSES) },
+      where: {
+        source,
+        sourceId,
+        status: In(OPEN_STATUSES),
+        ...(type ? { type } : {}),
+      },
       order: { issuedAt: "DESC" },
     });
     if (!invoice) return;
@@ -749,19 +739,20 @@ export class BillingService {
   // ── Payment initiation & settlement (the gateway boundary) ───────────────────
 
   /**
-   * Charge a source's open invoice through the payment gateway. Billing is the
-   * single place that turns "what is owed" (the invoice) into a payment intent —
-   * the domain never talks to the payment service directly. Resolves the open
-   * invoice, opens an intent for `invoice.totalAmount`, records the intent id on
-   * the invoice (the settlement correlation key), and returns the client action.
+   * Charge an invoice through the payment gateway. Billing is the single place
+   * that turns "what is owed" (the invoice) into a payment intent — the domain
+   * never talks to the payment service directly. Resolves the invoice by ID,
+   * opens an intent for `invoice.balanceAmount` (so partial payments are honored),
+   * records the intent id on the invoice (the settlement correlation key), and
+   * returns the client action.
    *
    * When the provider settles synchronously, the invoice is settled inline here —
    * after the intent id is stored — so the `payment.succeeded` correlation can
-   * never fire before the link exists. Throws when the source has no open invoice.
+   * never fire before the link exists. Throws when the invoice is not found or
+   * not in an open/payable status.
    */
   async payInvoice(
-    source: Freight.InvoiceSource,
-    sourceId: string,
+    invoiceId: string,
     opts: {
       method?: string;
       platform?: "web" | "mobile";
@@ -770,15 +761,17 @@ export class BillingService {
       failureUrl?: string;
     } = {},
   ): Promise<InitiateResponseDto> {
-    const invoice = await this.findPayable(source, sourceId);
+    const invoice = await this.dataSource.getRepository(Invoice).findOne({
+      where: { id: invoiceId, status: In(OPEN_STATUSES) },
+    });
     if (!invoice) {
       throw new NotFoundException(
-        `No open invoice to charge for ${source}:${sourceId}`,
+        `Invoice ${invoiceId} not found or not in a payable status`,
       );
     }
 
     const result = await this.payment.initiate({
-      referenceId: sourceId,
+      referenceId: invoice.sourceId,
       source: invoice.source,
       // Freight payments settle under the generic SHIPMENT reference — how the
       // payment service attributes them to the freight API. The payment ↔ invoice
@@ -787,7 +780,7 @@ export class BillingService {
       // service branches on a domain-specific reference type.
       referenceType: PaymentReferenceType.SHIPMENT,
       orderRef: invoice.invoiceNumber,
-      amountMinor: Math.round(Number(invoice.totalAmount)),
+      amountMinor: Math.round(Number(invoice.balanceAmount)),
       currency: invoice.currency,
       reason: `Payment for invoice ${invoice.invoiceNumber}`,
       method: opts.method ?? "TELEBIRR",