@vulog/aima-booking

Booking requests, stations, subscriptions, and vehicle allocation for the AIMA platform.

Installation

npm install @vulog/aima-booking @vulog/aima-client @vulog/aima-core

Usage

import { getClient } from '@vulog/aima-client';
import { getBookingRequestById, getStations } from '@vulog/aima-booking';

const client = getClient({ /* ClientOptions */ });

const booking = await getBookingRequestById(client, 'booking-uuid');
const stations = await getStations(client, ['INFO', 'SERVICES']);

API Reference

Booking Requests

| Function | Signature | Description | |----------|-----------|-------------| | getBookingRequests | (client, status: BookingRequestStatus, options?: PaginableOptions<BookingRequestFilters>) => Promise<PaginableResponse<BookingRequest>> | Retrieve a paginated list of booking requests by status | | getScheduleBookingRequests | (client, status: BookingRequestStatus, options?: PaginableOptions<SpecificBookingRequestFilters>) => Promise<PaginableResponse<BookingRequest>> | Booking requests filtered to service types ROUND_TRIP_BOOKING and SCHEDULED_BOOKING_STATION (auto-added) | | getSubscriptionBookingRequests | (client, status: BookingRequestStatus, options?: PaginableOptions<SpecificBookingRequestFilters>) => Promise<PaginableResponse<BookingRequest>> | Booking requests filtered to service type SUBSCRIPTION (auto-added) | | getSATBookingRequests | (client, status: SATBookingRequestStatus, options?: PaginableOptions<void, keyof SATBookingRequest>) => Promise<PaginableResponse<SATBookingRequest>> | Retrieve SAT booking requests by status | | getBookingRequestById | (client, id: string) => Promise<BookingRequest> | Retrieve a single booking request by UUID | | getBookingRequestByTrip | (client, tripId: string) => Promise<BookingRequest> | Retrieve a booking request by associated trip ID | | getSubscriptionBookingRequestById | (client, id: string) => Promise<BookingRequest> | Retrieve a subscription booking request by ID — normalises stationId to station | | getScheduledBookingById | (client, bookingId: string) => Promise<SATBookingRequest> | Retrieve a scheduled booking by UUID | | getBookingRequestsByUserId | (client, userId: string) => Promise<BookingRequest[]> | Retrieve all booking requests for a user — returns [] on 404 |

Actions

| Function | Signature | Description | |----------|-----------|-------------| | cancelBookingRequest | (client, id: string) => Promise<SATBookingRequest> | Cancel a booking request | | triggerBRPayment | (client, bookingRequestId: string, body: TriggerBRPaymentBody) => Promise<TriggerBRPaymentResponse> | Trigger a payment on a booking request | | releaseBRPayment | (client, bookingRequestId: string, pspReference: string) => Promise<SATBookingRequest> | Release a held payment on a booking request | | updateScheduleBooking | (client, bookingRequestId: string, updateData: Record<string, unknown>) => Promise<SATBookingRequest> | Update fields on a scheduled booking | | submitCancellationRequest | (client, bookingRequestId: string, userId: string) => Promise<SATBookingRequest> | Submit a cancellation request for a booking | | createBookingRequest | (client, body: CreateBookingRequestBody, options?: CreateBookingRequestOptions) => Promise<BookingRequest> | Create a new booking request |

triggerBRPayment — body fields

| Field | Type | Required | |-------|------|----------| | scope | 'RENTAL' \| 'DEPOSIT' | Yes | | online | boolean | Yes | | amountType | 'FIXED' \| 'PERCENTAGE' | Yes | | amountValue | number | Yes | | profileId | string | Yes | | requiresActionReturnURL | string | No | | preferredPaymentMethods | { pspReference: string; amount: number }[] | No |

createBookingRequest — required body fields

| Field | Type | |-------|------| | startDate | string | | endDate | string | | modelId | number (int) | | profileId | string (UUID) | | serviceId | string (UUID) |

updateScheduleBooking — available fields

startDate, latitude, longitude, radius, userId, status, cityId, profileId, serviceId, warning, modelId, notes, bookingReferenceId, plannedReturnDate

Subscriptions

| Function | Signature | Description | |----------|-----------|-------------| | createSubscription | (client, body: CreateSubscriptionBody) => Promise<BookingRequest> | Create a new subscription booking | | getSubscriptionsByUserId | (client, userId: string, active?: boolean) => Promise<Master[]> | Retrieve subscriptions for a user — active defaults to true | | getSlaves | (client, parentId: string, status: 'ONGOING' \| 'COMPLETED' \| 'UPCOMING') => Promise<BookingRequestSlave[]> | Retrieve slave bookings for a parent subscription | | getAdditionalDrivers | (client, parentId: string) => Promise<AdditionalDriver[]> | Retrieve additional drivers for a subscription | | getDigitalContracts | (client, bookingId: string, status?: string) => Promise<Contract[]> | Retrieve digital contracts for a booking — status defaults to 'SIGNED' |

createSubscription — required body fields

| Field | Type | |-------|------| | userId | string | | profileId | string | | startDate | string | | endDate | string | | vehicleId | string | | modelId | number (int) | | station | string | | serviceId | string |

Stations

| Function | Signature | Description | |----------|-----------|-------------| | getStations | (client, includes?: Include[]) => Promise<Station[]> | Retrieve all stations, optionally including extra data | | getStationById | (client, id: string, includes?: IncludeStation[]) => Promise<Station \| null> | Retrieve a station by ID — returns null on 400 | | getAvailableVehicles | (client, stationId: string, startDate: string) => Promise<AvailableVehiclesResponse> | Retrieve available vehicles at a station — startDate must be ISO without milliseconds | | getAvailableModels | (client, params: GetAvailableModelsParams) => Promise<StationWithAvailableModels[]> | Retrieve available models across stations | | getStationUnavailability | (client, params: { stationId: string; from: string; to: string; serviceId: string }) => Promise<StationVehicleCalendar> | Retrieve vehicle unavailability calendar for a station |

getAvailableModels — params

| Field | Type | Required | |-------|------|----------| | startDate | string | Yes | | endDate | string | Yes | | cityId | string | No | | userId | string | No | | profileId | string | No | | oneWayTrip | boolean | No | | showUnavailableModels | boolean | No |

Types

| Type | Values / Shape | |------|---------------| | BookingRequestStatus | 'ALERT' \| 'UPCOMING' \| 'ONGOING' \| 'COMPLETED' \| 'CANCELLED' \| 'PENDING_APPROVAL' \| 'CONFIRMED' \| 'PENDING' \| 'LATE' | | SATBookingRequestStatus | 'ALERT' \| 'CANCELLED' \| 'COMPLETED' \| 'CONFIRMED' \| 'LATE_RETURN' \| 'ONGOING' \| 'PENDING_PAYMENT' \| 'PENDING' \| 'UPCOMING_ALLOCATED' \| 'UPCOMING_NOT_ALLOCATED' | | Include | 'INFO' \| 'OPEN_HOUR' \| 'SERVICES' | | IncludeStation | 'INFO' \| 'SERVICES' |