feat: ( payment ) implement cbe payment

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

@@ -995,6 +995,7 @@ export class BillingService {
   ): Promise<InitiateResponseDto> {
     const invoice = await this.dataSource.getRepository(Invoice).findOne({
       where: { id: invoiceId, status: In(OPEN_STATUSES) },
+      relations: { company: true },
     });
     if (!invoice) {
       throw new NotFoundException(
@@ -1023,6 +1024,10 @@ export class BillingService {
       method: opts.method ?? "TELEBIRR",
       platform: opts.platform,
       payerAccount: opts.payerAccount,
+      // CBE_BILL: payer identity + the invoice's own due date as the bill expiry
+      // (docs/cbe/CBE_IMPLEMENTATION_PLAN.md §6.4).
+      payerName: invoice.company?.name,
+      expiresAt: invoice.dueAt?.toISOString(),
       returnUrl: opts.returnUrl,
       failureUrl: opts.failureUrl,
     });
@@ -1033,8 +1038,9 @@ export class BillingService {
       .update({ id: invoice.id }, { paymentId: result.intentId });
 
     // Settlement is driven by the payment API (webhook/outbox → payment.succeeded);
-    // billing must not simulate it. Kept commented for local demos only.
-    if (!result.immediateSuccess) {
+    // billing must not simulate it. Kept for local demos only. NEVER for CBE_BILL —
+    // its bill must stay open until CBE actually settles it via /cbe/payment.
+    if (!result.immediateSuccess && opts.method !== "CBE_BILL") {
       await this.payment.handlePaymentEvent({
         eventType: "payment.succeeded",
         eventId: `demo-${result.intentId}`,
@@ -1079,4 +1085,52 @@ export class BillingService {
       paidAt,
     });
   }
+
+  /**
+   * CBE bill-query (docs/cbe/CBE_IMPLEMENTATION_PLAN.md Phase 4): live still-payable check for
+   * the invoice behind a payment reference. `referenceId` is the gateway intent's referenceId,
+   * i.e. the invoice `sourceId`. Read-only; called while a CBE teller/app is waiting.
+   */
+  async billQuery(referenceId: string): Promise<{
+    stillPayable: boolean;
+    payerName?: string | null;
+    currentAmountMinor?: number | null;
+    currency?: string | null;
+    reason?: string | null;
+  }> {
+    const repo = this.dataSource.getRepository(Invoice);
+    const open = await repo.findOne({
+      where: { sourceId: referenceId, status: In(OPEN_STATUSES) },
+      relations: { company: true },
+      order: { issuedAt: "DESC" },
+    });
+
+    if (open) {
+      const balance = Math.round(Number(open.balanceAmount ?? open.totalAmount));
+      const expired = open.dueAt && open.dueAt.getTime() < Date.now();
+      return {
+        stillPayable: balance > 0 && !expired,
+        payerName: open.company?.name ?? null,
+        currentAmountMinor: balance,
+        currency: open.currency,
+        reason: expired ? "EXPIRED" : balance > 0 ? null : "ALREADY_PAID",
+      };
+    }
+
+    const latest = await repo.findOne({
+      where: { sourceId: referenceId },
+      relations: { company: true },
+      order: { createdAt: "DESC" },
+    });
+    return {
+      stillPayable: false,
+      payerName: latest?.company?.name ?? null,
+      currentAmountMinor: latest ? Math.round(Number(latest.totalAmount)) : null,
+      currency: latest?.currency ?? null,
+      reason:
+        latest?.status === Freight.InvoiceStatus.Paid
+          ? "ALREADY_PAID"
+          : "CANCELLED",
+    };
+  }
 }