Overview The Trip models define the data structures for creating trips, estimating fares, managing trip lifecycle, and handling real-time trip events. These models are used throughout the passenger app for trip planning, booking, and tracking.
Core Trip Models CreateTripRequest Payload for creating a new trip request.
The ID of the passenger requesting the trip
Payment method for the trip. One of: 'cash', 'card', or 'wallet'
Geographic coordinates of the pickup location Human-readable address for the pickup location
Array of trip stops/destinations Geographic coordinates of the stop
Human-readable address for the stop
Place identifier from geocoding service
Additional notes or instructions for this stop
Sequence number for stop ordering
ISO 8601 timestamp for planned arrival
Selected vehicle category ID (e.g., sedan, SUV)
Selected service class ID (e.g., economy, premium)
Optional idempotency key to prevent duplicate trip creation
export type PaymentMode = 'cash' | 'card' | 'wallet' ; export interface GeoPointDto { lat : number ; lng : number ; } export interface TripStopCreateDto { point : GeoPointDto ; address ?: string ; placeId ?: string ; notes ?: string ; seq ?: number ; plannedArrivalAt ?: string ; } export interface CreateTripRequest { passengerId : string ; paymentMode : PaymentMode ; pickupPoint : GeoPointDto ; pickupAddress ?: string | null ; stops ?: TripStopCreateDto []; vehicleCategoryId : string ; serviceClassId : string ; idempotencyKey ?: string ; }
TripResponseDto Response returned after creating a trip.
ID of the passenger who requested the trip
paymentMode
PaymentMode | string
required
Payment method selected for this trip
requestedVehicleCategoryId
Vehicle category requested by passenger
Service class requested by passenger
Geographic coordinates of pickup location
Human-readable pickup address
export interface TripResponseDto { id : string ; passengerId : string ; paymentMode : PaymentMode | string ; requestedVehicleCategoryId : string ; requestedServiceClassId : string ; pickupPoint : GeoPointDto ; pickupAddress : string | null ; }
Trip Estimation Models EstimateTripRequest Payload for requesting a trip fare estimate.
Vehicle category to estimate for
Service class to estimate for
pickup
{ lat: number; lng: number }
required
Pickup location coordinates
stops
Array<{ lat: number; lng: number }>
required
Array of destination coordinates
Currency code for fare calculation (e.g., ‘CUP’, ‘USD’)
export type LatLngDto = { lat : number ; lng : number }; export interface EstimateTripRequest { vehicleCategoryId : string ; serviceClassId : string ; pickup : { lat : number ; lng : number }; stops : Array <{ lat : number ; lng : number }>; currency ?: string ; }
FareQuote Fare estimation response with pricing breakdown.
Currency code for all monetary values
Surge pricing multiplier (1.0 = no surge)
Detailed fare calculation breakdown Estimated distance in kilometers
Estimated duration in minutes
Subtotal before surge multiplier
Total fare including all charges
Surge pricing multiplier applied
export interface FareBreakdown { distance_km_est : number ; duration_min_est : number ; base_fare : number ; min_fare : number ; cost_per_km : number ; cost_per_minute : number ; subtotal : number ; total : number ; surge_multiplier : number ; } export interface FareQuote { currency : string ; surgeMultiplier : number ; totalEstimated : number ; breakdown : FareBreakdown ; }
Catalog Models VehicleCategoryDto Vehicle category information from the backend.
Unique category identifier
Category name (e.g., “Sedan”, “SUV”)
URL to category icon image
Whether this category is currently active
ServiceClassDto Service class configuration from the backend.
Unique service class identifier
Service class name (e.g., “Economy”, “Premium”)
Service class description
Multiplier for base fare pricing
Multiplier for per-kilometer pricing
Multiplier for per-minute pricing
Multiplier for minimum fare
Minimum passenger capacity
Maximum passenger capacity
URL to service class icon
Whether this service class is active
export interface VehicleCategoryDto { id : string ; name : string ; description ?: string ; iconUrl ?: string ; isActive ?: boolean ; } export interface ServiceClassDto { id : string ; name : string ; description ?: string ; baseFareMultiplier ?: string ; costPerKmMultiplier ?: string ; costPerMinuteMultiplier ?: string ; minFareMultiplier ?: string ; minCapacity ?: number ; maxCapacity ?: number ; iconUrl ?: string ; isActive ?: boolean ; }
Trip Lifecycle & Status ActivePhase Enum-like type representing the current trip phase.
export type ActivePhase = | 'idle' // No active trip | 'assigning' // Searching for driver | 'accepted' // Driver accepted trip | 'arriving' // Driver en route to pickup | 'in_progress' // Trip in progress | 'completed' // Trip completed | 'cancelled' ; // Trip cancelled
Real-time Trip Events These event payloads are received via WebSocket for real-time trip updates.
AssigningStartedPayload Emitted when the system starts searching for a driver.
ISO 8601 timestamp of the event
Status before this transition
Current status after this event
export type AssigningStartedPayload = { tripId : string ; at : string ; previousStatus : 'pending' ; currentStatus : 'assigning' ; };
NoDriversFoundPayload Emitted when no drivers are available to accept the trip.
ISO 8601 timestamp of the event
Reason why no drivers were found
export type NoDriversFoundPayload = { tripId : string ; at : string ; reason ?: string | null ; };
DriverAssignedPayloadForPassenger Minimal payload when a driver is assigned (IDs only).
ISO 8601 timestamp of assignment
export type DriverAssignedPayloadForPassenger = { tripId : string ; driverId : string ; vehicleId : string ; at : string ; currentStatus : 'accepted' ; };
DriverAcceptedEnrichedPayload Enriched payload with full driver and vehicle details.
driver
DriverSlimForPassenger
required
Driver details Show DriverSlimForPassenger
Driver’s profile picture URL
vehicle
VehicleSlimForPassenger
required
Vehicle details Show VehicleSlimForPassenger
Vehicle make/manufacturer
export type DriverSlimForPassenger = { id : string ; name : string ; profilePictureUrl ?: string | null ; ratingAvg ?: number | null ; ratingCount ?: number | null ; phone ?: string | null ; }; export type VehicleSlimForPassenger = { id : string ; plateNumber ?: string | null ; color ?: string | null ; make ?: string | null ; model ?: string | null ; year ?: number | null ; }; export type DriverAcceptedEnrichedPayload = { tripId : string ; at : string ; currentStatus : 'accepted' ; driver : DriverSlimForPassenger ; vehicle : VehicleSlimForPassenger ; };
DriverEnRoutePayload Emitted periodically as the driver travels to pickup location.
Estimated time of arrival in minutes
driverPosition
{ lat: number; lng: number } | null
Current driver location coordinates
export type DriverEnRoutePayload = { tripId : string ; driverId : string ; at : string ; etaMinutes ?: number | null ; driverPosition ?: { lat : number ; lng : number } | null ; };
DriverArrivedPickupPayload Emitted when the driver arrives at the pickup location.
ISO 8601 timestamp of arrival
export type DriverArrivedPickupPayload = { tripId : string ; driverId : string ; at : string ; currentStatus : 'arriving' ; };
TripStartedPayload Emitted when the trip begins (passenger picked up).
ISO 8601 timestamp when trip started
export type TripStartedPayload = { tripId : string ; driverId : string ; at : string ; currentStatus : 'in_progress' ; };
TripCompletedPayload Emitted when the trip is completed.
ISO 8601 timestamp of completion
export type TripCompletedPayload = { tripId : string ; driverId : string ; at : string ; currentStatus : 'completed' ; fareTotal : number ; currency : string ; };
TripCancelledPayload Emitted when a trip is cancelled.
ISO 8601 timestamp of cancellation
export type TripCancelledPayload = { tripId : string ; at : string ; reason ?: string | null ; currentStatus : 'cancelled' ; };
Supporting Models PlaceSuggestion Represents a place suggestion from the geocoding service.
Full place name (e.g., “street, city, country”)
export type LatLng = { lat : number ; lng : number }; export interface PlaceSuggestion { id : string ; text : string ; placeName : string ; coords : LatLng ; }
Usage Examples Creating a Trip import { CreateTripRequest , PaymentMode } from '@/app/core/models/trip/create-trip.models' ; import { TripsApiService } from '@/app/core/services/http/trips-api.service' ; const tripRequest : CreateTripRequest = { passengerId: 'user-123' , paymentMode: 'cash' as PaymentMode , pickupPoint: { lat: 23.1136 , lng: - 82.3666 }, pickupAddress: 'Calle 23, Vedado, La Habana' , stops: [ { point: { lat: 23.1330 , lng: - 82.3830 }, address: 'Plaza de la Revolución' , seq: 1 } ], vehicleCategoryId: 'sedan-standard' , serviceClassId: 'economy' , idempotencyKey: 'trip-request-uuid-123' }; this . tripsApi . createTrip ( tripRequest ). subscribe ( trip => { if ( trip ) { console . log ( 'Trip created:' , trip . id ); } });
Estimating Trip Fare import { EstimateTripRequest } from '@/app/core/models/trip/estimate-for-trip.models' ; const estimateRequest : EstimateTripRequest = { vehicleCategoryId: 'sedan-standard' , serviceClassId: 'economy' , pickup: { lat: 23.1136 , lng: - 82.3666 }, stops: [ { lat: 23.1330 , lng: - 82.3830 } ], currency: 'CUP' }; this . tripsApi . estimateTrip ( estimateRequest ). subscribe ( quote => { if ( quote ) { console . log ( 'Estimated fare:' , quote . totalEstimated , quote . currency ); console . log ( 'Distance:' , quote . breakdown . distance_km_est , 'km' ); console . log ( 'Duration:' , quote . breakdown . duration_min_est , 'min' ); } });
Handling Real-time Trip Events import { DriverAcceptedEnrichedPayload } from '@/app/core/realtime/trip-realtime' ; import { TripLifecycleStore } from '@/app/store/trips/trip-lifecycle.store' ; // When driver accepts trip const payload : DriverAcceptedEnrichedPayload = { tripId: 'trip-456' , at: new Date (). toISOString (), currentStatus: 'accepted' , driver: { id: 'driver-789' , name: 'Juan Pérez' , profilePictureUrl: 'https://example.com/photo.jpg' , ratingAvg: 4.8 , ratingCount: 245 , phone: '+53 5555 1234' }, vehicle: { id: 'vehicle-101' , plateNumber: 'ABC 1234' , color: 'Negro' , make: 'Toyota' , model: 'Corolla' , year: 2020 } }; this . tripLifecycle . setAcceptedEnriched ( payload );
