@vulog/aima-vehicle 1.2.44 → 1.2.46

package/README.md

@@ -1,246 +1,355 @@
 # @vulog/aima-vehicle
 
-Vehicle management module for AIMA platform.
+Vehicle and model management — CRUD operations, real-time data, services, and options.
 
 ## Installation
 
-```bash
-npm i @vulog/aima-client @vulog/aima-core @vulog/aima-vehicle
+```sh
+npm install @vulog/aima-vehicle @vulog/aima-client @vulog/aima-core
 ```
 
 ## Usage
 
-### Initialize Client
-
-```javascript
+```ts
+import { getVehicles, getVehicleById, getVehiclesRealTime } from '@vulog/aima-vehicle';
 import { getClient } from '@vulog/aima-client';
-import { getVehicles, getModelById, getModels, getVehicleById, getVehiclesRealTime } from '@vulog/aima-vehicle';
-
-const client = getClient({
-    apiKey: '...',
-    baseUrl: '...',
-    clientId: '...',
-    clientSecret: '...',
-    fleetId: '...',
-});
+
+const client = getClient({ ... });
+
+const vehicles = await getVehicles(client);
+const vehicle = await getVehicleById(client, 'vehicle-uuid');
+const realTime = await getVehiclesRealTime(client, 500, Date.now() - 3600_000);
 ```
 
-### Get All Vehicles
+## API Reference
 
-Fetches all vehicles with pagination (default page size: 500). The implementation uses an internal `getVehiclesPage` function to fetch individual pages of vehicles.
+### getModelsById
 
-```javascript
-// Get all vehicles
-const vehicles = await getVehicles(client);
+```ts
+getModelsById(client: Client, id: number): Promise<Model>
+```
+
+Fetches a single vehicle model by ID.
+
+| Param    | Type     | Description               |
+| -------- | -------- | ------------------------- |
+| `client` | `Client` | Authenticated AIMA client |
+| `id`     | `number` | Model identifier          |
+
+---
+
+### getModelByIdAssets
+
+```ts
+getModelByIdAssets(client: Client, id: number): Promise<Assets>
+```
+
+Returns EDS assets for a model.
+
+| Param    | Type     | Description               |
+| -------- | -------- | ------------------------- |
+| `client` | `Client` | Authenticated AIMA client |
+| `id`     | `number` | Model identifier          |
+
+---
+
+### getModels
+
+```ts
+getModels(client: Client): Promise<Model[]>
+```
 
-// Get all vehicles with custom page size
-const vehicles = await getVehicles(client, 1000);
+Returns all vehicle models for the fleet.
+
+| Param    | Type     | Description               |
+| -------- | -------- | ------------------------- |
+| `client` | `Client` | Authenticated AIMA client |
+
+---
+
+### getVehicleById
+
+```ts
+getVehicleById(client: Client, id: string): Promise<Vehicle | null>
 ```
 
-The `getVehicles` function automatically handles pagination and will fetch all available vehicles up to a maximum of 50 pages. If you need to fetch a specific page of vehicles, you can use the internal `getVehiclesPage` function:
+Fetches a vehicle by ID. Returns `null` on 404.
+
+| Param    | Type     | Description               |
+| -------- | -------- | ------------------------- |
+| `client` | `Client` | Authenticated AIMA client |
+| `id`     | `string` | Vehicle identifier        |
 
-```javascript
-// Get a specific page of vehicles
-const vehiclesPage = await getVehiclesPage(client, 0, 100); // First page, 100 vehicles per page
+---
+
+### getVehicleRealTimeById
+
+```ts
+getVehicleRealTimeById(client: Client, id: string): Promise<VehicleRealTime | null>
 ```
 
-Note: `getVehiclesPage` is an internal function and is not exported from the package. It's used internally by `getVehicles` to handle the pagination logic.
+Returns real-time telemetry for a vehicle. Returns `null` on 404.
 
-### Get Vehicle by ID
+| Param    | Type     | Description               |
+| -------- | -------- | ------------------------- |
+| `client` | `Client` | Authenticated AIMA client |
+| `id`     | `string` | Vehicle identifier        |
 
-Fetches a specific vehicle by its ID.
+---
 
-```javascript
-const vehicle = await getVehicleById(client, 'dcb0c41e-4be3-11ea-83a5-024d0cba6da4');
+### getVehicleByIdAssets
+
+```ts
+getVehicleByIdAssets(client: Client, id: string): Promise<Assets>
 ```
 
-### Get All Models
+Returns EDS assets for a vehicle.
+
+| Param    | Type     | Description               |
+| -------- | -------- | ------------------------- |
+| `client` | `Client` | Authenticated AIMA client |
+| `id`     | `string` | Vehicle identifier        |
 
-Fetches all vehicle models.
+---
 
-```javascript
-const models = await getModels(client);
+### getVehicles
+
+```ts
+getVehicles(client: Client, pageSize?: number): Promise<Vehicle[]>
 ```
 
-### Get Model by ID
+Returns all vehicles in the fleet. Auto-paginates up to 50 pages using the given page size (default 500).
+
+| Param      | Type     | Description                        |
+| ---------- | -------- | ---------------------------------- |
+| `client`   | `Client` | Authenticated AIMA client          |
+| `pageSize` | `number` | Results per page (default 500)     |
+
+---
 
-Fetches a specific model by its ID.
+### getVehiclesRealTime
 
-```javascript
-const model = await getModelById(client, 372);
+```ts
+getVehiclesRealTime(client: Client, pageSize?: number, lastUpdatedMillis?: number): Promise<VehicleRealTime[]>
 ```
 
-### Get Real-Time Vehicle Data
+Returns real-time data for all vehicles. Auto-paginates up to 50 pages. `lastUpdatedMillis` must be a past UTC timestamp in milliseconds.
 
-Fetches real-time data for all vehicles with pagination (default page size: 500). The implementation uses an internal `getVehiclesRealTimePage` function to fetch individual pages of real-time vehicle data.
+| Param               | Type     | Description                             |
+| ------------------- | -------- | --------------------------------------- |
+| `client`            | `Client` | Authenticated AIMA client               |
+| `pageSize`          | `number` | Results per page (default 500)          |
+| `lastUpdatedMillis` | `number` | Only return vehicles updated after this |
 
-```javascript
-// Get real-time data for all vehicles
-const realTimeVehicles = await getVehiclesRealTime(client);
+---
 
-// Get real-time data with custom page size
-const realTimeVehicles = await getVehiclesRealTime(client, 1000);
+### pingVehicleById
 
-// Get only vehicles updated after a specific timestamp (in UTC milliseconds)
-const lastSyncTime = Date.now() - 24 * 60 * 60 * 1000; // 24 hours ago
-const updatedVehicles = await getVehiclesRealTime(client, 500, lastSyncTime);
+```ts
+pingVehicleById(client: Client, id: string): Promise<boolean>
 ```
 
-The `getVehiclesRealTime` function automatically handles pagination and will fetch all available vehicles up to a maximum of 50 pages. If you need to fetch a specific page of real-time vehicle data, you can use the internal `getVehiclesRealTimePage` function:
+Checks whether a vehicle's box is connected. Returns `true` if connected.
+
+| Param    | Type     | Description               |
+| -------- | -------- | ------------------------- |
+| `client` | `Client` | Authenticated AIMA client |
+| `id`     | `string` | Vehicle identifier        |
+
+---
 
-```javascript
-// Get a specific page of real-time vehicle data
-const realTimeVehiclesPage = await getVehiclesRealTimePage(client, 0, 100); // First page, 100 vehicles per page
+### enableVehicle
 
-// Get a specific page with lastUpdatedMillis filter
-const updatedVehiclesPage = await getVehiclesRealTimePage(client, 0, 100, lastSyncTime);
+```ts
+enableVehicle(client: Client, vehicleId: string, payload: EnableVehicleBody): Promise<void>
 ```
 
-Note: `getVehiclesRealTimePage` is an internal function and is not exported from the package. It's used internally by `getVehiclesRealTime` to handle the pagination logic.
+Enables a vehicle.
 
-### Create a Vehicle
+| Param       | Type                | Description               |
+| ----------- | ------------------- | ------------------------- |
+| `client`    | `Client`            | Authenticated AIMA client |
+| `vehicleId` | `string`            | Vehicle identifier        |
+| `payload`   | `EnableVehicleBody` | Enable payload            |
 
-Creates a new vehicle in the fleet.
+---
+
+### disableVehicle
+
+```ts
+disableVehicle(client: Client, vehicleId: string, payload: DisableVehicleBody): Promise<void>
+```
 
-```javascript
-import { createVehicle } from '@vulog/aima-vehicle';
-
-const vehicle = await createVehicle(client, {
-    vin: '1HGBH41JXMN109186',
-    plate: 'AB-123-CD',
-    name: 'My Vehicle',
-    model: { id: 372 },
-    // optional fields
-    vuboxId: 'vubox-123',
-    externalId: 'ext-123',
-    noBox: false,
-    published: true,
-});
+Disables a vehicle.
+
+| Param       | Type                 | Description               |
+| ----------- | -------------------- | ------------------------- |
+| `client`    | `Client`             | Authenticated AIMA client |
+| `vehicleId` | `string`             | Vehicle identifier        |
+| `payload`   | `DisableVehicleBody` | Disable payload           |
+
+---
+
+### getModelVehicles
+
+```ts
+getModelVehicles(client: Client, options?: PaginableOptions): Promise<PaginableResponse<ModelVehicle>>
 ```
 
-### Get Options
+Returns a paginated list of model-to-vehicle mappings.
+
+| Param     | Type               | Description               |
+| --------- | ------------------ | ------------------------- |
+| `client`  | `Client`           | Authenticated AIMA client |
+| `options` | `PaginableOptions` | Pagination options        |
 
-Fetches all vehicle options available in the fleet.
+---
 
-```javascript
-import { getOptions } from '@vulog/aima-vehicle';
+### createVehicle
 
-const options = await getOptions(client);
+```ts
+createVehicle(client: Client, body: CreateVehicleBody): Promise<Vehicle>
 ```
 
-### Add / Remove Option for Vehicle
+Creates a new vehicle in the fleet.
+
+| Param    | Type                | Description               |
+| -------- | ------------------- | ------------------------- |
+| `client` | `Client`            | Authenticated AIMA client |
+| `body`   | `CreateVehicleBody` | Vehicle creation data     |
 
-Add or remove an option to/from a vehicle.
+---
 
-```javascript
-import { addOptionForVehicle, removeOptionForVehicle } from '@vulog/aima-vehicle';
+### addServiceForVehicle
 
-const vehicle = await addOptionForVehicle(client, 'vehicle-uuid', 25);
-const vehicle = await removeOptionForVehicle(client, 'vehicle-uuid', 25);
+```ts
+addServiceForVehicle(client: Client, serviceId: string, vehicleId: string): Promise<void>
 ```
 
-### Add / Remove Service for Vehicle
+Assigns a service to a vehicle.
 
-Add or remove a service to/from a vehicle.
+| Param       | Type     | Description               |
+| ----------- | -------- | ------------------------- |
+| `client`    | `Client` | Authenticated AIMA client |
+| `serviceId` | `string` | Service identifier        |
+| `vehicleId` | `string` | Vehicle identifier        |
 
-```javascript
-import { addServiceForVehicle, removeServiceForVehicle } from '@vulog/aima-vehicle';
+---
 
-await addServiceForVehicle(client, 'service-uuid', 'vehicle-uuid');
-await removeServiceForVehicle(client, 'service-uuid', 'vehicle-uuid');
+### removeServiceForVehicle
+
+```ts
+removeServiceForVehicle(client: Client, serviceId: string, vehicleId: string): Promise<void>
 ```
 
-### Enable / Disable Vehicle
+Removes a service from a vehicle.
+
+| Param       | Type     | Description               |
+| ----------- | -------- | ------------------------- |
+| `client`    | `Client` | Authenticated AIMA client |
+| `serviceId` | `string` | Service identifier        |
+| `vehicleId` | `string` | Vehicle identifier        |
 
-Enable or disable a vehicle with a sub-status.
+---
 
-```javascript
-import { enableVehicle, disableVehicle } from '@vulog/aima-vehicle';
+### getOptions
 
-await enableVehicle(client, 'vehicle-uuid', { subStatus: 'AVAILABLE' });
-await disableVehicle(client, 'vehicle-uuid', { subStatus: 'MAINTENANCE' });
+```ts
+getOptions(client: Client): Promise<Options[]>
 ```
 
-### Ping Vehicle
+Returns all vehicle options available in the fleet.
 
-Check if a vehicle box is connected.
+| Param    | Type     | Description               |
+| -------- | -------- | ------------------------- |
+| `client` | `Client` | Authenticated AIMA client |
 
-```javascript
-import { pingVehicleById } from '@vulog/aima-vehicle';
+---
 
-const isConnected = await pingVehicleById(client, 'vehicle-uuid');
-// true = connected, false = connection problem
+### addOptionForVehicle
+
+```ts
+addOptionForVehicle(client: Client, vehicleId: string, optionId: number): Promise<Vehicle>
 ```
 
-### Get Model Vehicles
+Adds an option to a vehicle. Returns the updated vehicle.
+
+| Param       | Type     | Description               |
+| ----------- | -------- | ------------------------- |
+| `client`    | `Client` | Authenticated AIMA client |
+| `vehicleId` | `string` | Vehicle identifier        |
+| `optionId`  | `number` | Option identifier         |
 
-Fetches paginated model vehicle listings.
+---
 
-```javascript
-import { getModelVehicles } from '@vulog/aima-vehicle';
+### removeOptionForVehicle
 
-const result = await getModelVehicles(client, {
-    page: 0,
-    pageSize: 50,
-    sort: 'modelId',
-    sortDirection: 'DESC',
-});
+```ts
+removeOptionForVehicle(client: Client, vehicleId: string, optionId: number): Promise<Vehicle>
 ```
 
+Removes an option from a vehicle. Returns the updated vehicle.
+
+| Param       | Type     | Description               |
+| ----------- | -------- | ------------------------- |
+| `client`    | `Client` | Authenticated AIMA client |
+| `vehicleId` | `string` | Vehicle identifier        |
+| `optionId`  | `number` | Option identifier         |
+
 ## Types
 
 ### Vehicle
 
-```typescript
-interface Vehicle {
-    id: string;
-    name: string;
-    plate: string;
-    vin: string;
-    model: Model;
-    options: Options[];
-    createDate: string;
-    updateDate: string;
-    fleetId: string;
-    externalId: string;
-    wakeupProvider?: string;
-    msisdn: string;
-    iccid: string;
-    imsi?: string;
-    published: boolean;
-    noBox: boolean;
-    archived: boolean;
+Fleet vehicle data including `id`, `name`, `plate`, `vin`, `model`, `options`, `fleetId`, `published`, `archived`, `noBox`, `msisdn`, `iccid`, and optional `wakeupProvider`, `imsi`, `residualValue`.
+
+### VehicleRealTime
+
+Real-time vehicle telemetry including location, battery, booking state, door/window status, zone membership, and box connectivity.
+
+### Model
+
+Vehicle model definition including `id`, `name`, `energyType`, `vehicleType`, `transmission`, `nbOfSeats`, `autonomy`, `fleetId`.
+
+### Assets
+
+```ts
+{
+    fleet_id: string;
+    model_id: number;
+    assets: {
+        aid: string;
+        type: string;
+        url: string;
+        value: string;
+        b_value: string;
+        text: string;
+    }[];
 }
 ```
 
-### Model
+### ModelVehicle
 
-```typescript
-interface Model {
-    id: number;
-    name: string;
-    energyType: string;
-    status: string;
-    nbOfSeats: number;
-    autonomy: number;
-    creationDate: string;
-    updateDate: string;
-    description: string;
-    fleetId: string;
-    vehicleType: string;
-    transmission: string;
-    outOfServiceRange: string;
-    recoveryRange: string;
-    incentiveThresholds: any[];
-    redistributeVehicleChargedEnoughRange: string;
-    odometerReliable?: boolean;
+```ts
+{
+    serviceId: string;
+    serviceVisibility: 'PUBLIC' | 'PRIVATE';
+    modelId: number;
+    vehicles: string[];
 }
 ```
 
+### CreateVehicleBody
+
+Vehicle creation data. Optional fields include `wakeupProvider`, `archived`, `msisdn`, `iccid`, `imsi`, `residualValue`.
+
+### EnableVehicleBody / DisableVehicleBody
+
+Payloads for enabling and disabling a vehicle.
+
 ### Options
 
-```typescript
-interface Options {
+```ts
+{
     id: number;
     fleetId: string;
     name: string;
@@ -248,106 +357,3 @@ interface Options {
     description: string;
 }
 ```
-
-### VehicleRealTime
-
-```typescript
-interface VehicleRealTime {
-    id: string;
-    name: string;
-    plate: string;
-    vin: string;
-    fleetid: string;
-    currentFleetId: string;
-    ownerFleetId: string;
-    boxid: string;
-    vehicle_status: number;
-    zones: Zone[];
-    releasable: boolean;
-    box_status: number;
-    autonomy: number;
-    autonomy2: number;
-    isCharging: boolean;
-    battery: number;
-    km: number;
-    speed: number;
-    location: {
-        geohash: string;
-        cap: number;
-        latitude: number;
-        longitude: number;
-        gpsDate: string;
-        lastMovingDate: string;
-    };
-    endTripLocation: {
-        latitude: number;
-        longitude: number;
-    };
-    endZoneIds: [];
-    productIds: [];
-    isDoorClosed: boolean;
-    isDoorLocked: boolean;
-    engineOn: boolean;
-    immobilizerOn: boolean;
-    secureOn: boolean;
-    spareLockOn: boolean | null;
-    pileLockOn: boolean | null;
-    helmetPresent: boolean | null;
-    helmet2Present: boolean | null;
-    helmetBoxLockOn: boolean | null;
-    helmet2LockOn: boolean | null;
-    userId: string | null;
-    user_locale: string | null;
-    rfid: string | null;
-    orderId: string | null;
-    gatewayUrl: string | null;
-    booking_status: number;
-    booking_date: string | null;
-    expiresOn: boolean | null;
-    last_active_date: string;
-    last_wakeUp_date: string;
-    version: string;
-    pricingId: string | null;
-    start_date: string | null;
-    theorStartDate: string | null;
-    theorEndDate: string | null;
-    startZones: Zone[];
-    endZones: Zone[];
-    disabled: boolean;
-    outOfServiceReason: string;
-    ignitionOffGeohash: string | null;
-    geohashNeighbours: string[];
-    cleanlinessStatus: boolean;
-    needsRedistribution: boolean;
-    batteryUnderThreshold: boolean;
-    isBeingTowed: boolean;
-    automaticallyEnableVehicleAfterRangeRecovery: boolean;
-    key: {
-        deviceName: string;
-    };
-    doNotTrack: boolean;
-    energyLevel: number;
-    lastOosDate: string;
-    hasAlerts: boolean;
-    firmwareModel: string;
-    comeFromApp: string;
-    doors: {
-        frontLeftClosed: boolean;
-        frontRightClosed: boolean;
-        rearLeftClosed: boolean;
-        rearRightClosed: boolean;
-        trunkClosed: boolean;
-        hoodClosed: boolean;
-    };
-    windows: {
-        frontLeftClosed: boolean;
-        frontRightClosed: boolean;
-        rearLeftClosed: boolean;
-        rearRightClosed: boolean;
-        trunkClosed: boolean;
-    };
-    doorsAndWindowsClosed: boolean;
-    vpChecksum: string;
-    firmwareBuildDate: string;
-}
-```

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@vulog/aima-vehicle",
     "type": "module",
-    "version": "1.2.44",
+    "version": "1.2.46",
     "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.44",
-        "@vulog/aima-core": "1.2.44"
+        "@vulog/aima-client": "1.2.46",
+        "@vulog/aima-core": "1.2.46"
     },
     "peerDependencies": {
         "zod": "^4.3.6"