Zum Inhalt

Ride lifecycle (booking state management)

TxRide links passengers to driver offers through the Match entity. This document describes the booking lifecycle delivered in June 2026.

State machine

stateDiagram-v2
    [*] --> PROPOSED: passenger requests ride
    PROPOSED --> ACCEPTED: driver accepts
    PROPOSED --> DECLINED: driver declines
    ACCEPTED --> CANCELLED: passenger or driver cancels booking
    PROPOSED --> CANCELLED: passenger or driver cancels booking
  • Direct booking: passenger selects an offer on the map and calls rideOffer.request. This creates a RideRequest plus a PROPOSED Match.
  • Broadcast requests (rideRequest.create via /requests/new) remain unchanged and do not count against the open-request limit when already linked to an active match.
  • Seat accounting: booking.accept decrements RideOffer.seatsAvailable; booking.cancel on an accepted match returns seats.
  • Whole-ride cancel: rideOffer.cancel sets the offer to CANCELLED and cancels all active matches; matched passengers receive a best-effort email.

API endpoints

Procedure Auth Description
rideOffer.request passenger Request a specific offer (creates request + PROPOSED match)
booking.accept driver Accept a booking; decrements seats
booking.decline driver Decline a PROPOSED booking
booking.cancel passenger or driver Cancel a booking (per-match)
rideOffer.cancel driver Cancel the entire ride
appConfig.get authenticated Returns cancellationWindowHours
rideOffer.get driver Includes passengers[] with booking status
rideRequest.get/list passenger Includes booking summary when linked

Configuration

Set the cancellation window in .env:

CANCELLATION_WINDOW_HOURS=24

The API reads this value in packages/api/src/config.ts and exposes it to the web app via appConfig.get. Cancel actions are rejected with cancellation-window-passed when now >= departureAt - window.

Tests

  • Unit: packages/api/test/booking.test.ts, packages/api/test/ride-cancel.test.ts
  • E2E: e2e/booking.cy.ts (requires CYPRESS_INTEGRATION=1 and full dev stack)
  • Doc screenshots: e2e/doc-screenshots.cy.ts (booking section)

Run on NixOS:

nix develop -c bun test packages/api/test/booking.test.ts
nix develop -c bun run cypress:web:integration --spec e2e/booking.cy.ts