Booking a Ride

Phase 1 — rider booking flow. API-level today; the rider app UI wraps these endpoints.

1. Sign in

Riders authenticate with a phone OTP:

POST /api/auth/otp/request   { "phone": "+9198…" }     → sends code (dev: returns it)
POST /api/auth/otp/verify    { "phone": "+9198…", "code": "123456" }
                             → { accessToken, refreshToken }

The first OTP login auto-creates the rider account. Use the accessToken as Authorization: Bearer <token> on every call below.

2. Get a fare estimate

POST /api/pricing/estimate
{ "pickupLat": 12.9756, "pickupLng": 77.6068,
  "dropoffLat": 12.9352, "dropoffLng": 77.6245 }

Returns one estimate per active vehicle type (Economy / Sedan / SUV…), each with distance, time, and fare (in the installation's currency). The distance is computed with PostGIS, the same source the matching engine uses.

3. Book

POST /api/rides
{ "vehicleTypeId": "<id>",
  "pickupLat": 12.9756, "pickupLng": 77.6068,
  "dropoffLat": 12.9352, "dropoffLng": 77.6245 }

The ride is created in requested state with a fare snapshot (the price is locked at booking time). The matching engine then finds the nearest available driver.

Bidding mode (where enabled)

If the installation runs bidding (inDriver-style), pass:

{ …, "pricingMode": "bidding", "bidFareMinor": "10000" }

Drivers may accept your fare or counter; you accept a counter via POST /api/rides/:id/bids/rider-accept { "bidId": "<id>" }.

4. Track the ride (realtime)

Connect a Socket.IO client with your access token:

io('https://your-host', { auth: { token: accessToken } })
  .on('ride:status', e => /* requested → accepted → arrived → in_progress → completed */)
  .on('driver:location', e => /* live driver position */)

You only receive events for your own rides (server-side per-user rooms).

5. Other actions

Cancellation is allowed before the trip starts (requested / accepted / arrived); once in_progress the trip must complete.