### Health
GET http://localhost:4000/api/health

### List rides
GET http://localhost:4000/api/rides

### Filter rides
GET http://localhost:4000/api/rides?from=accra&minSeats=2&status=active

### Create ride
POST http://localhost:4000/api/rides
Content-Type: application/json

{
  "from": "Tema",
  "to": "Osu",
  "date": "2026-03-19",
  "time": "08:15",
  "availableSeats": 3,
  "price": 22,
  "estimatedDuration": 55,
  "driverId": "user-3",
  "hotspots": [
    { "id": "hs-a", "name": "18 Junction", "type": "pickup" },
    { "id": "hs-b", "name": "Nungua", "type": "dropoff" }
  ]
}

### List bookings
GET http://localhost:4000/api/bookings

### Create booking
POST http://localhost:4000/api/bookings
Content-Type: application/json

{
  "rideId": "ride-1",
  "riderId": "user-1",
  "seats": 1,
  "pickupHotspot": "37 Station",
  "dropoffHotspot": "Nkrumah Circle"
}

### Update booking status
PATCH http://localhost:4000/api/bookings/booking-1/status
Content-Type: application/json

{
  "status": "completed"
}

### Refresh access token
POST http://localhost:4000/api/auth/refresh
Content-Type: application/json

{
  "refreshToken": "{{refreshToken}}"
}

### Mobile app me (single app for rider + driver)
GET http://localhost:4000/api/app/me
Authorization: Bearer {{token}}

### Mobile app profile update
PATCH http://localhost:4000/api/app/me
Content-Type: application/json
Authorization: Bearer {{token}}

{
  "profile": {
    "fullName": "Alex Boateng",
    "phone": "+233200000123",
    "profileVisibility": "drivers",
    "shareLocation": true
  },
  "rider": {
    "location": {
      "city": "Accra",
      "town": "Labone"
    }
  }
}

### Enable driver mode (sets canDrive and links/creates driver profile)
POST http://localhost:4000/api/app/mode/driver/enable
Content-Type: application/json
Authorization: Bearer {{token}}

{
  "name": "Alex Boateng",
  "phone": "+233200000123"
}

### Mobile app summary for current mode
GET http://localhost:4000/api/app/summary?mode=driver
Authorization: Bearer {{token}}

### Inbound mail webhook (generic)
POST http://localhost:4000/api/mail/inbound
Content-Type: application/json
x-mail-inbound-secret: {{mailInboundSecret}}
x-mail-provider: generic
x-mail-event-id: evt_generic_001
x-roamit-signature: sha256={{genericInboundHmac}}

{
  "from": "Alice Example <alice@example.com>",
  "subject": "Need help with my account",
  "text": "Hello team, I need support with my account settings.",
  "accountType": "account",
  "accountId": "acct_123",
  "accountName": "Alice Example"
}

### Inbound mail webhook (mailgun style)
POST http://localhost:4000/api/mail/inbound
Content-Type: application/json
x-mail-inbound-secret: {{mailInboundSecret}}
x-mail-provider: mailgun
x-mail-event-id: evt_mailgun_001

{
  "sender": "Bob Rider <bob@example.com>",
  "subject": "Re: Booking issue [tmail_demo123]",
  "timestamp": "1731532800",
  "token": "mailgun-token-example",
  "signature": "mailgun-hmac-signature",
  "body-plain": "Following up on my booking issue.",
  "stripped-text": "Following up on my booking issue.",
  "accountType": "rider",
  "accountId": "rdr_demo123"
}

### Inbound mail webhook (postmark style)
POST http://localhost:4000/api/mail/inbound
Content-Type: application/json
x-mail-inbound-secret: {{mailInboundSecret}}
x-mail-provider: postmark
x-mail-event-id: evt_postmark_001
x-postmark-inbound-secret: {{postmarkInboundSecret}}
x-postmark-signature: {{postmarkSignature}}

{
  "From": "Carla Driver <carla@example.com>",
  "FromName": "Carla Driver",
  "Subject": "Payout clarification",
  "TextBody": "Can you explain the latest payout hold?",
  "accountType": "driver",
  "accountId": "drv_demo567"
}

### Inbound mail webhook (sendgrid style)
POST http://localhost:4000/api/mail/inbound
Content-Type: application/json
x-mail-inbound-secret: {{mailInboundSecret}}
x-mail-provider: sendgrid
x-mail-event-id: evt_sendgrid_001
x-twilio-email-event-webhook-timestamp: {{sendgridTimestamp}}
x-twilio-email-event-webhook-signature: {{sendgridSignatureBase64}}

{
  "from": "Zee Ops <zee@example.com>",
  "subject": "Re: Dispatch issue [tmail_demo890]",
  "text": "Checking in on dispatch assignment updates.",
  "accountType": "support",
  "accountId": "sup_demo890"
}

### Tracking: publish driver location (trip-scoped)
POST http://localhost:4000/api/tracking/driver/location
Content-Type: application/json
Authorization: Bearer {{driverToken}}

{
  "tripId": "{{tripRef}}",
  "latitude": 5.6037,
  "longitude": -0.1870,
  "heading": 78,
  "speedKph": 34,
  "accuracyMeters": 9,
  "city": "Accra",
  "region": "Greater Accra"
}

### Tracking: publish driver location (booking-scoped)
POST http://localhost:4000/api/tracking/driver/location
Content-Type: application/json
Authorization: Bearer {{driverToken}}

{
  "bookingId": "{{bookingRef}}",
  "latitude": 5.6071,
  "longitude": -0.2014,
  "heading": 102,
  "speedKph": 26,
  "accuracyMeters": 12
}

### Tracking: get live booking tracking (rider participant)
GET http://localhost:4000/api/tracking/bookings/{{bookingRef}}/live
Authorization: Bearer {{riderToken}}

### Tracking: get live booking tracking (driver participant)
GET http://localhost:4000/api/tracking/bookings/{{bookingRef}}/live
Authorization: Bearer {{driverToken}}

### Tracking placeholders
# @driverToken: JWT for driver-linked app account
# @riderToken: JWT for rider-linked app account on same booking
# @bookingRef: booking _id or bookingId (for example BK-AB12C)
# @tripRef: trip _id or tripId (for example TP-Z9Y8X)

### Verification docs: list rider documents
GET http://localhost:4000/api/app/documents?mode=rider
Authorization: Bearer {{riderToken}}

### Verification docs: list driver documents
GET http://localhost:4000/api/app/documents?mode=driver
Authorization: Bearer {{driverToken}}

### Verification docs: upload rider ID card
POST http://localhost:4000/api/app/documents/upload
Content-Type: application/json
Authorization: Bearer {{riderToken}}

{
  "mode": "rider",
  "documentType": "id-card",
  "documentName": "National ID Card Front",
  "fileName": "ghana-card-front.jpg",
  "mimeType": "image/jpeg",
  "contentBase64": "data:image/jpeg;base64,{{base64Image}}",
  "clientGeneratedMeta": {
    "sizeBytes": 123456,
    "lastModified": 1763539200000,
    "sha256Client": "{{sha256Hex}}",
    "navigatorUserAgent": "Mozilla/5.0"
  }
}

### Verification docs: upload driver licence
POST http://localhost:4000/api/app/documents/upload
Content-Type: application/json
Authorization: Bearer {{driverToken}}

{
  "mode": "driver",
  "documentType": "driver-license",
  "documentName": "Driver Licence",
  "fileName": "driver-licence.pdf",
  "mimeType": "application/pdf",
  "contentBase64": "data:application/pdf;base64,{{base64Pdf}}",
  "clientGeneratedMeta": {
    "sizeBytes": 223456,
    "lastModified": 1763539200000,
    "sha256Client": "{{sha256Hex}}",
    "navigatorUserAgent": "Mozilla/5.0"
  }
}

### Admin review: approve rider document (by documentId or index)
PATCH http://localhost:4000/api/admin/riders/{{riderId}}/documents/{{documentRef}}/review
Content-Type: application/json
Authorization: Bearer {{adminToken}}

{
  "status": "approved",
  "reason": "Valid ID and metadata checks passed"
}

### Admin review: reject driver document
PATCH http://localhost:4000/api/admin/drivers/{{driverId}}/documents/{{documentRef}}/review
Content-Type: application/json
Authorization: Bearer {{adminToken}}

{
  "status": "rejected",
  "reason": "Document image appears altered"
}