fix: prevent driver assignment when Soroban escrow contract is not initialised (#143)

[mmotunrayo]

Closes #143

Problem

Drivers could be assigned to deliveries whose Soroban escrow contract had never been funded or was in a non-ready state (pending, released, refunded, disputed), creating a mismatch between on-chain escrow state and off-chain delivery state.

Solution

Added a dedicated assignDriver flow in the service layer that queries the Escrow collection for the delivery and rejects the assignment with a clear, actionable error message unless the escrow lockStatus is LOCKED.

Changes

src/services/delivery.service.ts (implementation directory per issue)

• Imported Escrow model and EscrowLockStatus enum.

• Added AssignDriverInput interface { deliveryId, driverId }.

• Added assignDriver(input) method with six ordered guard checks:

  #	Check	HTTP
  1	Invalid delivery ObjectId format	400
  2	Delivery not found	404
  3	Terminal status (completed / cancelled)	409
  4	Already assigned	409
  5	No escrow record (contract never initialised)	422
  6	Escrow exists but lockStatus is not LOCKED (pending / released / refunded / disputed)	409 with status-specific message

  On success: sets delivery.driverId and advances status to ASSIGNED in a single document save (no partial-update window).

src/controllers/delivery.controller.ts

• Imported AssignDriverInput.
• Added assignDriver() handler that delegates to deliveryService.assignDriver() and returns 200 { status: 'success', message, data: delivery }.

src/routes/delivery.routes.ts

• Imported assignDriverSchema, authenticate, requireRole, UserRole.

• Added PATCH /api/v1/deliveries/:id/assign-driver route:

  authenticate -> requireRole(ADMIN) -> validateRequest(assignDriverSchema) -> deliveryController.assignDriver
  

• Full OpenAPI doc comment documents all response codes (200 / 400 / 401 / 403 / 404 / 409 / 422).

[drips-wave]

@mmotunrayo Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits