npm - @vulog/aima-booking - Versions diffs - 1.2.45 → 1.2.47 - Mend

@vulog/aima-booking 1.2.45 → 1.2.47

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2) hide show

package/README.md +103 -386
package/package.json +3 -3

package/README.md CHANGED Viewed

@@ -1,411 +1,128 @@
 # @vulog/aima-booking
-Booking management module for the AIMA platform. This module provides functionality to manage booking requests, stations, and subscription bookings.
+Booking requests, stations, subscriptions, and vehicle allocation for the AIMA platform.
 ## Installation
-```bash
-npm install @vulog/aima-client @vulog/aima-core @vulog/aima-booking
+```sh
+npm install @vulog/aima-booking @vulog/aima-client @vulog/aima-core
 ```
 ## Usage
-### Initialize Client
-```javascript
+```ts
 import { getClient } from '@vulog/aima-client';
-import {
-    getBookingRequests,
-    getScheduleBookingRequests,
-    getSubscriptionBookingRequests,
-    getSATBookingRequests,
-    getBookingRequestById,
-    getBookingRequestByTrip,
-    getSubscriptionBookingRequestById,
-    getStations,
-    getStationById
-} from '@vulog/aima-booking';
+import { getBookingRequestById, getStations } from '@vulog/aima-booking';
+const client = getClient({ /* ClientOptions */ });
-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',
-});
+const booking = await getBookingRequestById(client, 'booking-uuid');
+const stations = await getStations(client, ['INFO', 'SERVICES']);
 ```
 ## API Reference
 ### Booking Requests
-#### getBookingRequests
-Retrieve booking requests with optional filtering.
-```javascript
-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.
-```javascript
-const scheduledRequests = await getScheduleBookingRequests(client, {
-    startDate: '2024-01-01T00:00:00Z',
-    endDate: '2024-01-31T23:59:59Z'
-});
-```
-#### getSubscriptionBookingRequests
-Get subscription-based booking requests.
-```javascript
-const subscriptionRequests = await getSubscriptionBookingRequests(client, {
-    status: 'ACTIVE',
-    userId: 'user-uuid-here'
-});
-```
-#### getSATBookingRequests
-Get SAT (Scheduled Access Time) booking requests.
-```javascript
-const satRequests = await getSATBookingRequests(client, 'PENDING');
-```
-### Individual Booking Requests
-#### getBookingRequestById
-Retrieve a specific booking request by ID.
-```javascript
-const bookingRequest = await getBookingRequestById(client, 'bb493049-5b4f-43ea-8a65-964a13aec549');
-```
-#### getBookingRequestByTrip
-Get booking request associated with a trip.
-```javascript
-const bookingRequest = await getBookingRequestByTrip(client, '33E8E42710144E15A5CC447E4D3524F4');
-```
-#### getSubscriptionBookingRequestById
-Get subscription booking request by ID.
-```javascript
-const subscriptionRequest = await getSubscriptionBookingRequestById(client, 'b7faa2a2-e8fc-4a29-8de7-09ce783b9797');
-```
-### Stations
-#### getStations
-Retrieve stations with optional includes.
-```javascript
-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.
-```javascript
-const station = await getStationById(client, 'station-id-here', ['OPEN_HOUR', 'INFO']);
-```
-### Vehicle Allocation
-#### allocateVehicle
-Allocate a vehicle to a booking request.
-```javascript
-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.
-```javascript
-import { deallocateVehicle } from '@vulog/aima-booking';
-await deallocateVehicle(client, 'booking-request-uuid');
-```
-### Booking Actions
-#### updateScheduleBooking
-Update a scheduled booking.
-```javascript
-import { updateScheduleBooking } from '@vulog/aima-booking';
-await updateScheduleBooking(client, 'booking-request-uuid', { endDate: '2024-02-15T00:00:00Z' });
-```
-#### cancelBookingRequest
-Cancel a booking request.
-```javascript
-import { cancelBookingRequest } from '@vulog/aima-booking';
-await cancelBookingRequest(client, 'booking-request-uuid');
-```
-#### triggerBRPayment / releaseBRPayment
-Trigger or release payment for a booking request.
-```javascript
-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.
-```javascript
-import { getBookingRequestsByUserId } from '@vulog/aima-booking';
-const requests = await getBookingRequestsByUserId(client, 'user-uuid');
-```
+| 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
-#### createSubscription
-Create a new subscription booking request.
-```javascript
-import { createSubscription } from '@vulog/aima-booking';
+| 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` |
-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: ['driver@example.com'],
-});
-```
-### Available Vehicles
-#### getAvailableVehicles
-Get available vehicles for booking.
-```javascript
-import { getAvailableVehicles } from '@vulog/aima-booking';
+### Stations
-const vehicles = await getAvailableVehicles(client);
-```
+| 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
-### BookingRequest
-```typescript
-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
-```typescript
-interface Station {
-    id: string;
-    name: string;
-    address: string;
-    coordinates: {
-        latitude: number;
-        longitude: number;
-    };
-    isActive: boolean;
-    openHours: OpenHours[];
-    info: StationInfo;
-    vehicles: Vehicle[];
-    zones: Zone[];
-}
-```
-### BookingRequestStatus
-```typescript
-type BookingRequestStatus = 'PENDING' | 'ONGOING' | 'COMPLETED' | 'CANCELLED' | 'EXPIRED';
-```
-### ServiceType
-```typescript
-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
-```javascript
-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
-```javascript
-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
-```javascript
-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;
-    }
-}
-```
+| 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'` |

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
     "name": "@vulog/aima-booking",
     "type": "module",
-    "version": "1.2.45",
+    "version": "1.2.47",
     "main": "dist/index.cjs",
     "module": "dist/index.mjs",
     "types": "dist/index.d.cts",
@@ -32,8 +32,8 @@
     "author": "Vulog",
     "license": "MIT",
     "dependencies": {
-        "@vulog/aima-client": "1.2.45",
-        "@vulog/aima-core": "1.2.45"
+        "@vulog/aima-client": "1.2.47",
+        "@vulog/aima-core": "1.2.47"
     },
     "peerDependencies": {
         "es-toolkit": "^1.45.1",