Merge pull request #1746 from Kwin-xeexee/cancellation-fee.service.ts

cancellation-fee.service.ts

Author: mftee

backend/docs/payments-custody-model.md

@@ -17,6 +17,16 @@ This creates a **hybrid custody model**: non-custodial deposit (the shipper cont
 
 We adopt a **hybrid (non-custodial deposit + admin-arbitrated release)** custody model.
 
+### Cancellation Fees
+
+Cancellation fees are based on shipment progress only when the shipper
+cancels, or an admin cancels on the shipper's behalf: cancellation is free
+while `PENDING`, retains 10% of the quoted price after `ACCEPTED`, and retains
+25% while `IN_TRANSIT`. A carrier-initiated cancellation is always fee-free,
+so the shipper receives the full escrow refund. An admin cancelling a
+`DISPUTED` shipment also refunds in full. The backend records the applied
+fee on the shipment and includes it in the escrow refund calculation.
+
 ### What the Admin Keypair Can Do
 
 | Action | Authorized By | Effect |

backend/src/shipments/cancellation-fee.service.spec.ts

@@ -5,6 +5,7 @@ import {
 } from './cancellation-fee.service';
 import { Shipment } from './entities/shipment.entity';
 import { ShipmentStatus } from '../common/enums/shipment-status.enum';
+import { UserRole } from '../common/enums/role.enum';
 
 function makeShipment(overrides: Partial<Shipment> = {}): Shipment {
   return {
@@ -116,7 +117,11 @@ describe('CancellationFeeService', () => {
     it('stamps the fee and an audit note onto the shipment', () => {
       const shipment = makeShipment({ status: ShipmentStatus.ACCEPTED });
 
-      const fee = service.applyTo(shipment, ShipmentStatus.ACCEPTED);
+      const fee = service.applyTo(
+        shipment,
+        UserRole.SHIPPER,
+        ShipmentStatus.ACCEPTED,
+      );
 
       expect(fee).toBe(20);
       expect(shipment.cancellationFee).toBe(20);
@@ -126,7 +131,7 @@ describe('CancellationFeeService', () => {
     it('defaults to the shipment’s current status', () => {
       const shipment = makeShipment({ status: ShipmentStatus.IN_TRANSIT });
 
-      expect(service.applyTo(shipment)).toBe(50);
+      expect(service.applyTo(shipment, UserRole.SHIPPER)).toBe(50);
       expect(shipment.cancellationFee).toBe(50);
     });
 
@@ -136,7 +141,7 @@ describe('CancellationFeeService', () => {
         notes: 'Handle with care — fragile electronics',
       });
 
-      service.applyTo(shipment);
+      service.applyTo(shipment, UserRole.SHIPPER);
 
       expect(shipment.notes).toBe(
         'Handle with care — fragile electronics\nCancellation fee: 50 USD',
@@ -146,22 +151,44 @@ describe('CancellationFeeService', () => {
     it('records a zero fee for a cancelled-before-accept shipment', () => {
       const shipment = makeShipment({ status: ShipmentStatus.PENDING });
 
-      expect(service.applyTo(shipment)).toBe(0);
+      expect(service.applyTo(shipment, UserRole.SHIPPER)).toBe(0);
       expect(shipment.cancellationFee).toBe(0);
       expect(shipment.notes).toBe('Cancellation fee: 0 USD');
     });
 
     it('refuses to apply a fee to a non-cancellable shipment', () => {
       const shipment = makeShipment({ status: ShipmentStatus.DELIVERED });
 
-      expect(() => service.applyTo(shipment)).toThrow(BadRequestException);
+      expect(() => service.applyTo(shipment, UserRole.SHIPPER)).toThrow(
+        BadRequestException,
+      );
       expect(shipment.cancellationFee).toBeNull();
     });
 
     it('coerces a stringified numeric price (Postgres numeric) safely', () => {
       const shipment = makeShipment({ price: '1000.00' as never });
 
-      expect(service.applyTo(shipment, ShipmentStatus.IN_TRANSIT)).toBe(250);
+      expect(
+        service.applyTo(
+          shipment,
+          UserRole.SHIPPER,
+          ShipmentStatus.IN_TRANSIT,
+        ),
+      ).toBe(250);
+    });
+
+    it('waives the fee when a carrier cancels', () => {
+      const shipment = makeShipment({ status: ShipmentStatus.IN_TRANSIT });
+
+      expect(service.applyTo(shipment, UserRole.CARRIER)).toBe(0);
+      expect(shipment.cancellationFee).toBe(0);
+      expect(shipment.notes).toBe('Cancellation fee: 0 USD');
+    });
+
+    it('uses the status tier when an admin cancels on the shipper side', () => {
+      const shipment = makeShipment({ status: ShipmentStatus.ACCEPTED });
+
+      expect(service.applyTo(shipment, UserRole.ADMIN)).toBe(20);
     });
   });
 

backend/src/shipments/cancellation-fee.service.ts

@@ -1,6 +1,7 @@
 import { Injectable, BadRequestException } from '@nestjs/common';
 import { Shipment } from './entities/shipment.entity';
 import { ShipmentStatus } from '../common/enums/shipment-status.enum';
+import { UserRole } from '../common/enums/role.enum';
 
 /**
  * Share of the quoted price retained by the platform when a shipment is
@@ -85,15 +86,24 @@ export class CancellationFeeService {
    * Stamps the calculated fee onto `shipment` (in memory — the caller
    * persists it) and appends an audit line to the existing notes rather
    * than overwriting them, so a shipper's own notes survive a
-   * cancellation.
+   * cancellation. Carrier-initiated cancellations are fee-free; shipper
+   * and admin cancellations use the status-based fee tier.
    *
+   * @param actorRole role of the user initiating the cancellation.
    * @param previousStatus the status the shipment is being cancelled
    *   *from*; defaults to the shipment's current status.
    * @returns the fee that was applied.
    */
-  applyTo(shipment: Shipment, previousStatus?: ShipmentStatus): number {
+  applyTo(
+    shipment: Shipment,
+    actorRole: UserRole,
+    previousStatus?: ShipmentStatus,
+  ): number {
     const from = previousStatus ?? shipment.status;
-    const fee = this.calculateFee(Number(shipment.price), from);
+    const fee =
+      actorRole === UserRole.CARRIER
+        ? 0
+        : this.calculateFee(Number(shipment.price), from);
     const note = this.describeFee(fee, shipment.currency);
 
     shipment.cancellationFee = fee;

backend/src/shipments/shipments.service.spec.ts

@@ -753,7 +753,7 @@ describe('ShipmentsService', () => {
       expect(shipmentRepo.save).not.toHaveBeenCalled();
     });
 
-    it('lets the assigned carrier cancel an in-transit shipment', async () => {
+    it('lets the assigned carrier cancel an in-transit shipment without a fee', async () => {
       const carrier = makeUser({
         id: 'carrier-uuid-1',
         role: UserRole.CARRIER,
@@ -768,7 +768,11 @@ describe('ShipmentsService', () => {
       await service.cancel('shipment-uuid-1', carrier);
 
       expect(shipmentRepo.save).toHaveBeenCalledWith(
-        expect.objectContaining({ cancellationFee: 200 }),
+        expect.objectContaining({ cancellationFee: 0 }),
+      );
+      expect(paymentsService.refundEscrowForShipment).toHaveBeenCalledWith(
+        'shipment-uuid-1',
+        0,
       );
     });
   });

backend/src/shipments/shipments.service.ts

@@ -678,11 +678,11 @@ export class ShipmentsService {
    * Cancels a shipment, refunding escrow and retaining a tiered
    * cancellation fee.
    *
-   * The fee rate is a function of the status being cancelled *from*
-   * (see `CancellationFeeService`): free while PENDING, 10% once a carrier
-   * has accepted, 25% while the cargo is IN_TRANSIT, and free for an
-   * admin cancelling a disputed shipment. The fee is stamped on the
-   * shipment and surfaced on every shipment read via
+   * Shipper and admin cancellations use the status-based fee tier (free
+   * while PENDING, 10% once a carrier has accepted, 25% while IN_TRANSIT,
+   * and free for an admin cancelling a disputed shipment). Carrier-
+   * initiated cancellations are always fee-free. The fee is stamped on
+   * the shipment and surfaced on every shipment read via
    * `shipment.cancellationFee`.
    *
    * Ordering matters: the fee is computed before the settlement so a failing
@@ -718,6 +718,7 @@ export class ShipmentsService {
     const previousStatus = shipment.status;
     const cancellationFee = this.cancellationFeeService.applyTo(
       shipment,
+      user.role,
       previousStatus,
     );