@vulog/aima-booking

Booking management module for the AIMA platform. This module provides functionality to manage booking requests, stations, and subscription bookings.

Installation

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

Usage

Initialize Client

import { getClient } from '@vulog/aima-client';
import { 
    getBookingRequests, 
    getScheduleBookingRequests, 
    getSubscriptionBookingRequests,
    getSATBookingRequests,
    getBookingRequestById,
    getBookingRequestByTrip,
    getSubscriptionBookingRequestById,
    getStations,
    getStationById
} from '@vulog/aima-booking';

const client = getClient({
    apiKey: 'your-api-key',
    baseUrl: 'https://your-api-base-url',
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
    fleetId: 'your-fleet-id',
});

API Reference

Booking Requests

getBookingRequests

Retrieve booking requests with optional filtering.

const bookingRequests = await getBookingRequests(client, 'ONGOING', {
    limit: 50,
    offset: 0,
    userId: 'user-uuid-here'
});

Parameters:

• client: AIMA client instance
• status: Booking request status ('ONGOING', 'COMPLETED', 'CANCELLED', 'EXPIRED')
• filters: Optional filter object
  • limit: Maximum number of results
  • offset: Number of results to skip
  • userId: Filter by user ID
  • vehicleId: Filter by vehicle ID
  • stationId: Filter by station ID

getScheduleBookingRequests

Get scheduled booking requests.

const scheduledRequests = await getScheduleBookingRequests(client, {
    startDate: '2024-01-01T00:00:00Z',
    endDate: '2024-01-31T23:59:59Z'
});

getSubscriptionBookingRequests

Get subscription-based booking requests.

const subscriptionRequests = await getSubscriptionBookingRequests(client, {
    status: 'ACTIVE',
    userId: 'user-uuid-here'
});

getSATBookingRequests

Get SAT (Scheduled Access Time) booking requests.

const satRequests = await getSATBookingRequests(client, 'PENDING');

Individual Booking Requests

getBookingRequestById

Retrieve a specific booking request by ID.

const bookingRequest = await getBookingRequestById(client, 'bb493049-5b4f-43ea-8a65-964a13aec549');

getBookingRequestByTrip

Get booking request associated with a trip.

const bookingRequest = await getBookingRequestByTrip(client, '33E8E42710144E15A5CC447E4D3524F4');

getSubscriptionBookingRequestById

Get subscription booking request by ID.

const subscriptionRequest = await getSubscriptionBookingRequestById(client, 'b7faa2a2-e8fc-4a29-8de7-09ce783b9797');

Stations

getStations

Retrieve stations with optional includes.

const stations = await getStations(client, ['OPEN_HOUR', 'INFO']);

Parameters:

• client: AIMA client instance
• includes: Array of data to include ('OPEN_HOUR', 'INFO', 'VEHICLES', 'ZONES')

getStationById

Get a specific station by ID.

const station = await getStationById(client, 'station-id-here', ['OPEN_HOUR', 'INFO']);

Vehicle Allocation

allocateVehicle

Allocate a vehicle to a booking request.

import { allocateVehicle } from '@vulog/aima-booking';

const result = await allocateVehicle(client, 'booking-request-uuid', 'vehicle-uuid', 'service-uuid');

deallocateVehicle

Deallocate a vehicle from a booking request.

import { deallocateVehicle } from '@vulog/aima-booking';

await deallocateVehicle(client, 'booking-request-uuid');

Booking Actions

updateScheduleBooking

Update a scheduled booking.

import { updateScheduleBooking } from '@vulog/aima-booking';

await updateScheduleBooking(client, 'booking-request-uuid', { endDate: '2024-02-15T00:00:00Z' });

cancelBookingRequest

Cancel a booking request.

import { cancelBookingRequest } from '@vulog/aima-booking';

await cancelBookingRequest(client, 'booking-request-uuid');

triggerBRPayment / releaseBRPayment

Trigger or release payment for a booking request.

import { triggerBRPayment, releaseBRPayment } from '@vulog/aima-booking';

await triggerBRPayment(client, 'booking-request-uuid');
await releaseBRPayment(client, 'booking-request-uuid');

getBookingRequestsByUserId

Get booking requests for a specific user.

import { getBookingRequestsByUserId } from '@vulog/aima-booking';

const requests = await getBookingRequestsByUserId(client, 'user-uuid');

Subscriptions

createSubscription

Create a new subscription booking request.

import { createSubscription } from '@vulog/aima-booking';

const subscription = await createSubscription(client, {
    userId: 'user-uuid',
    profileId: 'profile-uuid',
    startDate: '2024-01-15T00:00:00Z',
    endDate: '2024-07-15T00:00:00Z',
    vehicleId: 'vehicle-uuid',
    modelId: 372,
    station: 'station-uuid',
    serviceId: 'service-uuid',
    // optional fields
    pricingId: 'pricing-uuid',
    notes: 'VIP client',
    isRollingContract: false,
    additionalDriverInvitations: ['[email protected]'],
});

Available Vehicles

getAvailableVehicles

Get available vehicles for booking.

import { getAvailableVehicles } from '@vulog/aima-booking';

const vehicles = await getAvailableVehicles(client);

Types

BookingRequest

interface BookingRequest {
    id: string;
    userId: string;
    vehicleId: string;
    stationId: string;
    status: 'PENDING' | 'ONGOING' | 'COMPLETED' | 'CANCELLED' | 'EXPIRED';
    startTime: string;
    endTime: string;
    createdAt: string;
    updatedAt: string;
}

Station

interface Station {
    id: string;
    name: string;
    address: string;
    coordinates: {
        latitude: number;
        longitude: number;
    };
    isActive: boolean;
    openHours: OpenHours[];
    info: StationInfo;
    vehicles: Vehicle[];
    zones: Zone[];
}

BookingRequestStatus

type BookingRequestStatus = 'PENDING' | 'ONGOING' | 'COMPLETED' | 'CANCELLED' | 'EXPIRED';

ServiceType

type ServiceType = 'CAR_SHARING' | 'BIKE_SHARING' | 'SCOOTER_SHARING' | 'MULTIMODAL';

Error Handling

All functions include validation and will throw appropriate errors if:

• Required parameters are missing
• Invalid booking request or station IDs are provided
• Invalid status values are used
• Network errors occur

Examples

Complete Booking Management Workflow

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

const client = getClient({
    apiKey: 'your-api-key',
    baseUrl: 'https://your-api-base-url',
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
    fleetId: 'your-fleet-id',
});

async function bookingWorkflow() {
    try {
        // Get all ongoing booking requests
        const ongoingRequests = await getBookingRequests(client, 'ONGOING');
        console.log(`Found ${ongoingRequests.length} ongoing booking requests`);
        
        // Get stations with full information
        const stations = await getStations(client, ['OPEN_HOUR', 'INFO', 'VEHICLES']);
        console.log(`Found ${stations.length} stations`);
        
        // Get specific booking request
        const bookingRequest = await getBookingRequestById(client, 'bb493049-5b4f-43ea-8a65-964a13aec549');
        console.log('Booking request details:', bookingRequest);
        
        return { ongoingRequests, stations, bookingRequest };
    } catch (error) {
        console.error('Booking workflow error:', error);
        throw error;
    }
}

Station Analysis

async function analyzeStations(client) {
    try {
        const stations = await getStations(client, ['OPEN_HOUR', 'INFO', 'VEHICLES']);
        
        const analysis = {
            totalStations: stations.length,
            activeStations: stations.filter(s => s.isActive).length,
            stationsWithVehicles: stations.filter(s => s.vehicles && s.vehicles.length > 0).length,
            averageVehiclesPerStation: stations.reduce((sum, s) => sum + (s.vehicles?.length || 0), 0) / stations.length,
            stationsByZone: stations.reduce((acc, station) => {
                station.zones?.forEach(zone => {
                    acc[zone.name] = (acc[zone.name] || 0) + 1;
                });
                return acc;
            }, {})
        };
        
        console.log('Station Analysis:');
        console.log(`Total Stations: ${analysis.totalStations}`);
        console.log(`Active Stations: ${analysis.activeStations}`);
        console.log(`Stations with Vehicles: ${analysis.stationsWithVehicles}`);
        console.log(`Average Vehicles per Station: ${analysis.averageVehiclesPerStation.toFixed(2)}`);
        console.log('Stations by Zone:', analysis.stationsByZone);
        
        return analysis;
    } catch (error) {
        console.error('Station analysis error:', error);
        throw error;
    }
}

Booking Request Monitoring

async function monitorBookingRequests(client) {
    try {
        const [ongoing, completed, cancelled] = await Promise.all([
            getBookingRequests(client, 'ONGOING'),
            getBookingRequests(client, 'COMPLETED'),
            getBookingRequests(client, 'CANCELLED')
        ]);
        
        const monitoring = {
            ongoing: ongoing.length,
            completed: completed.length,
            cancelled: cancelled.length,
            total: ongoing.length + completed.length + cancelled.length,
            completionRate: completed.length / (completed.length + cancelled.length) * 100
        };
        
        console.log('Booking Request Monitoring:');
        console.log(`Ongoing: ${monitoring.ongoing}`);
        console.log(`Completed: ${monitoring.completed}`);
        console.log(`Cancelled: ${monitoring.cancelled}`);
        console.log(`Total: ${monitoring.total}`);
        console.log(`Completion Rate: ${monitoring.completionRate.toFixed(2)}%`);
        
        return monitoring;
    } catch (error) {
        console.error('Booking monitoring error:', error);
        throw error;
    }
}