Merge remote-tracking branch 'origin/staging' into freight/fix/pay

# Conflicts:
#	apps/edr-freight-api/src/modules/billing/billing.service.ts
#	apps/edr-freight-web/portal/src/pages/billing/InvoiceDetailPage.tsx
#	apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/PaymentMethodModal.tsx
#	pnpm-lock.yaml

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

@@ -55,6 +55,27 @@ const OPEN_STATUSES: Freight.InvoiceStatus[] = [
   Freight.InvoiceStatus.Overdue,
 ];
 
+/**
+ * Why a non-open invoice can no longer be paid, in the vocabulary the payment service's CBE
+ * bill-query mapper understands. Kept specific: CBE reads this back to the payer at the counter,
+ * so "cancelled" must not stand in for "already paid" or "refunded".
+ */
+function closedInvoiceReason(status: Freight.InvoiceStatus): string {
+  switch (status) {
+    case Freight.InvoiceStatus.Paid:
+      return "ALREADY_PAID";
+    case Freight.InvoiceStatus.Refunded:
+      return "REFUNDED";
+    case Freight.InvoiceStatus.Cancelled:
+      return "CANCELLED";
+    case Freight.InvoiceStatus.Expired:
+      return "EXPIRED";
+    // Draft — issued to nobody yet, so there is nothing honest to say beyond "not payable".
+    default:
+      return "NOT_PAYABLE";
+  }
+}
+
 /** A single line to bill on a generated invoice. */
 export interface InvoiceLineInput {
   chargeType: string;
@@ -1034,6 +1055,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(
@@ -1090,6 +1112,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,
     });
@@ -1100,12 +1126,14 @@ 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.
+    // billing must not simulate it. Kept for local demos only.
     // An OTP intent (CAC Bank) is NOT paid yet — the payer still has to enter the
-    // code — so the demo shortcut must never fire for it.
+    // code — so the demo shortcut must never fire for it. Same for CBE_BILL: its
+    // bill must stay open until CBE actually settles it via /cbe/payment.
     if (
       !result.immediateSuccess &&
-      result.response.clientAction?.type !== "COLLECT_OTP"
+      result.response.clientAction?.type !== "COLLECT_OTP" &&
+      opts.method !== "CBE_BILL"
     ) {
       await this.payment.handlePaymentEvent({
         eventType: "payment.succeeded",
@@ -1151,4 +1179,67 @@ 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;
+    paymentReason?: 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,
+        // CBE shows this beside the amount on the confirmation screen — the invoice number
+        // the payer is holding, not our internal reference.
+        paymentReason: `Freight invoice ${open.invoiceNumber}`,
+        // Settled-in-full wins over past-due: an invoice with nothing left to pay is paid, not
+        // expired, and that is what the payer at the CBE counter must be told.
+        reason: balance > 0 ? (expired ? "EXPIRED" : null) : "ALREADY_PAID",
+      };
+    }
+
+    const latest = await repo.findOne({
+      where: { sourceId: referenceId },
+      relations: { company: true },
+      order: { createdAt: "DESC" },
+    });
+    // A bill reference whose invoice no longer exists at all — a data problem, not a
+    // cancellation the payer did anything to cause.
+    if (!latest) {
+      return {
+        stillPayable: false,
+        payerName: null,
+        currentAmountMinor: null,
+        currency: null,
+        reason: "NOT_FOUND",
+      };
+    }
+    return {
+      stillPayable: false,
+      payerName: latest.company?.name ?? null,
+      currentAmountMinor: Math.round(Number(latest.totalAmount)),
+      currency: latest.currency,
+      paymentReason: `Freight invoice ${latest.invoiceNumber}`,
+      reason: closedInvoiceReason(latest.status),
+    };
+  }
 }

apps/edr-freight-api/src/modules/payment/entities/payment.entity.ts

@@ -4,7 +4,7 @@ import { PaymentRefundEntity } from "./payment-refund.entity";
 
 /** Invoice source that owns the intent ('booking', 'demurrage', …) — caller-supplied. */
 type PaymentType = string
-type PaymentMethod = "telebirr" | "cbe-birr" | "ebirr" | "waafi" | "card" | "dmoney" | "cac-bank"
+type PaymentMethod = "telebirr" | "cbe-birr" | "ebirr" | "waafi" | "card" | "dmoney" | "cac-bank" | "cbe-bill"
 type Currency = "ETB" | "USD"
 export type PaymentStatus = "action-required" | "processing" | "success" | "failed" | "canceled" | "refunded"
 
@@ -22,7 +22,7 @@ export class PaymentEntity extends BaseEntity {
     @Column({ type: "varchar", length: 40, nullable: true, name: "reference_type" })
     referenceType?: string;
 
-    @Column({ type: "enum", enum: ["telebirr", "cbe-birr", "ebirr", "waafi", "card", "dmoney", "cac-bank"] })
+    @Column({ type: "enum", enum: ["telebirr", "cbe-birr", "ebirr", "waafi", "card", "dmoney", "cac-bank", "cbe-bill"] })
     method!: PaymentMethod
 
     @Column({ type: "enum", enum: ["ETB", "USD"] })

apps/edr-freight-api/src/modules/payment/internal-payment.controller.ts

@@ -1,30 +1,42 @@
 import {
   Body,
   Controller,
+  forwardRef,
   HttpCode,
   HttpStatus,
+  Inject,
   Logger,
   Post,
+  UseGuards,
 } from "@nestjs/common";
 import { ApiOperation, ApiTags } from "@nestjs/swagger";
-import { Public } from "@edr/api-common";
-import { PaymentEventDto, MarkPaidResponseDto } from "./internal-payment.dto";
+import {
+  PaymentEventDto,
+  MarkPaidResponseDto,
+  BillQueryRequestDto,
+  BillQueryResponseDto,
+} from "./internal-payment.dto";
 import { PaymentService } from "./payment.service";
+import { BillingService } from "../billing/billing.service";
+import { ServiceAuthGuard } from "../../common/guards/service-auth.guard";
 
 /**
- * Consumer side of the payment microservice's outbox relay.
- * WARNING: currently unauthenticated — anyone who can reach the API can mark
- * payments as paid. Re-add ServiceAuthGuard before exposing beyond a trusted network.
+ * Consumer side of the payment microservice's outbox relay. Only the payment service may
+ * call this (shared service token — restored per docs/cbe/CBE_IMPLEMENTATION_PLAN.md R8).
  * Idempotent by design — the relay delivers at-least-once, so duplicates must be harmless.
  * Becomes a queue consumer via PaymentEventsConsumer when RabbitMQ is available;
  * this HTTP endpoint remains as a transport-agnostic fallback.
  */
 @ApiTags("Internal Payments")
-@Public()
+@UseGuards(ServiceAuthGuard)
 @Controller("internal/payments")
 export class InternalPaymentController {
   private readonly logger = new Logger(InternalPaymentController.name);
-  constructor(private readonly paymentService: PaymentService) { }
+  constructor(
+    private readonly paymentService: PaymentService,
+    @Inject(forwardRef(() => BillingService))
+    private readonly billingService: BillingService,
+  ) { }
 
   @Post("mark-paid")
   @HttpCode(HttpStatus.OK)
@@ -36,4 +48,16 @@ export class InternalPaymentController {
     this.logger.log(`Marking payment ${event} as PAID`);
     return this.paymentService.handlePaymentEvent(event);
   }
+
+  @Post("bill-query")
+  @HttpCode(HttpStatus.OK)
+  @ApiOperation({
+    summary:
+      "Live still-payable check + payer name for a CBE bill (called while CBE is on the line)",
+  })
+  async billQuery(
+    @Body() request: BillQueryRequestDto,
+  ): Promise<BillQueryResponseDto> {
+    return this.billingService.billQuery(request.referenceId);
+  }
 }

apps/edr-freight-api/src/modules/payment/internal-payment.dto.ts

@@ -51,3 +51,30 @@ export class MarkPaidResponseDto {
     @ApiPropertyOptional() alreadyFinalized?: boolean;
     @ApiPropertyOptional() reason?: string;
 }
+
+/**
+ * CBE bill-query hop (docs/cbe/CBE_IMPLEMENTATION_PLAN.md Phase 4): the payment service asks
+ * "is this invoice still payable, by whom, for how much" while a CBE channel is on the line.
+ */
+export class BillQueryRequestDto {
+    // Typed `string`, not the enum: the @nestjs/swagger CLI plugin resolves an enum-typed
+    // property to a relative require() into packages/types, which does not exist inside the
+    // Docker image (only /app is copied) and crashes at boot with MODULE_NOT_FOUND. The
+    // decorators below still give us enum docs + runtime validation.
+    @ApiProperty({ enum: PaymentReferenceType })
+    @IsEnum(PaymentReferenceType)
+    referenceType!: string;
+
+    @ApiProperty() @IsString() referenceId!: string;
+}
+
+export class BillQueryResponseDto {
+    @ApiProperty() stillPayable!: boolean;
+    @ApiPropertyOptional() payerName?: string | null;
+    @ApiPropertyOptional() currentAmountMinor?: number | null;
+    @ApiPropertyOptional() currency?: string | null;
+    /** When stillPayable=false: "ALREADY_PAID" | "CANCELLED" | "REFUNDED" | "EXPIRED" | "NOT_FOUND" | "NOT_PAYABLE". */
+    @ApiPropertyOptional() reason?: string | null;
+    /** What the payer is paying for — CBE renders it beside the amount (Payment_Reason). */
+    @ApiPropertyOptional() paymentReason?: string | null;
+}

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

@@ -51,6 +51,10 @@ export interface InitiateIntentInput {
   payerAccount?: string;
   returnUrl?: string;
   failureUrl?: string;
+  /** CBE_BILL: payer full name snapshot (feeds CBE's mandatory Full_Name). */
+  payerName?: string;
+  /** CBE_BILL: intent expiry, ISO-8601 — the invoice due date, never a session TTL. */
+  expiresAt?: string;
 }
 
 export interface InitiateIntentResult {
@@ -79,6 +83,7 @@ const PROVIDER_TO_METHOD: Record<string, PaymentEntity["method"]> = {
   CARD: "card",
   DMONEY: "dmoney",
   CAC_BANK: "cac-bank",
+  CBE_BILL: "cbe-bill",
 };
 
 /**
@@ -214,8 +219,13 @@ export class PaymentService {
 
   async initiate(input: InitiateIntentInput): Promise<InitiateIntentResult> {
     try {
-
-       
+      const isCbeBill = input.method === ProviderMethod.CBE_BILL;
+      // CBE settles ETB only (docs/cbe/CBE_IMPLEMENTATION_PLAN.md D8).
+      if (isCbeBill && input.currency?.toUpperCase() !== "ETB") {
+        throw new BadRequestException(
+          "CBE bill payment is only available for ETB invoices",
+        );
+      }
 
       const snapshot = await this.paymentClient.initiate({
         service: PaymentServiceEnum.FREIGHT,
@@ -223,11 +233,15 @@ export class PaymentService {
         referenceId: input.referenceId,
         orderRef: input.orderRef,
         // amountMinor: input.amountMinor,
-        amountMinor:1,
+        // CBE_BILL must carry the REAL amount: /cbe/payment verifies what the customer was
+        // debited against the intent amount, so the 1-birr dev shortcut would break it.
+        amountMinor: isCbeBill ? input.amountMinor : 1,
         currency: input.currency,
         provider: input.method as ProviderMethod,
         platform: input.platform,
         payerAccount: input.payerAccount,
+        payerName: input.payerName,
+        expiresAt: input.expiresAt,
         returnUrl:
           input.returnUrl ?? "https://edrfreight.triaplc.com/payment/success",
         failureUrl:

apps/edr-freight-api/src/modules/payment/payments.dto.ts

@@ -60,8 +60,10 @@ export class RefundDto {
 }
 
 export class ClientActionDto {
-  @ApiProperty({ enum: ["REDIRECT", "LAUNCH_APP", "COLLECT_OTP"] })
-  type!: "REDIRECT" | "LAUNCH_APP" | "COLLECT_OTP";
+  @ApiProperty({
+    enum: ["REDIRECT", "LAUNCH_APP", "COLLECT_OTP", "SHOW_BILL_REFERENCE"],
+  })
+  type!: "REDIRECT" | "LAUNCH_APP" | "COLLECT_OTP" | "SHOW_BILL_REFERENCE";
 
   @ApiPropertyOptional({ description: "Set when type=REDIRECT (web flow)" })
   url?: string;
@@ -80,6 +82,17 @@ export class ClientActionDto {
 
   @ApiPropertyOptional({ description: "Set when type=COLLECT_OTP" })
   message?: string;
+
+  @ApiPropertyOptional({
+    description: "Set when type=SHOW_BILL_REFERENCE (CBE bill payment)",
+  })
+  billReference?: string;
+
+  @ApiPropertyOptional({ description: "Set when type=SHOW_BILL_REFERENCE" })
+  instructions?: string;
+
+  @ApiPropertyOptional({ description: "Set when type=SHOW_BILL_REFERENCE" })
+  expiresAt?: string;
 }
 
 export class InitiateResponseDto {