@vulog/aima-event/README.md

Event tracking — query fleet events by type, trip, or time range.

# @vulog/aima-event

Event tracking — query fleet events by type, trip, or time range.

## Installation

```sh
npm install @vulog/aima-event @vulog/aima-client @vulog/aima-core
```

## Usage

```ts
import { getClient } from '@vulog/aima-client';
import { getEventsByType, getEvents, getEventsByTripId } from '@vulog/aima-event';

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

const events = await getEventsByType(client, 'TRIP_START');
const allEvents = await getEvents(client, { page: 0, size: 50 });
const tripEvents = await getEventsByTripId(client, 'trip-uuid');
```

## API Reference

### getEventsByType

```ts
getEventsByType(
    client: Client,
    type: EventType,
    options?: PaginableOptions<EventFilters, 'date'>
): Promise<PaginableResponse<Event>>
```

Returns events of the given type for the fleet. Default time window: last 2 months to now.

**Params:** `client` — Authenticated AIMA client; `type` — event type to filter on; `options` — optional pagination and date filters  
**Returns:** `Promise<PaginableResponse<Event>>`

---

### getEvents

```ts
getEvents(
    client: Client,
    options?: PaginableOptions<EventFilters, 'date'>
): Promise<PaginableResponse<Event>>
```

Returns events of all types for the fleet. Default time window: last 2 months to now.

**Params:** `client` — Authenticated AIMA client; `options` — optional pagination and date filters  
**Returns:** `Promise<PaginableResponse<Event>>`

---

### getEventsByTripId

```ts
getEventsByTripId(
    client: Client,
    tripId: string,
    options?: PaginableOptions<EventFilters & { type?: EventType[] }, 'date'>
): Promise<PaginableResponse<Event>>
```

Returns events for a specific trip, optionally filtered by event type.

**Params:** `client` — Authenticated AIMA client; `tripId` — trip identifier; `options` — optional pagination, date filters, and type filter  
**Returns:** `Promise<PaginableResponse<Event>>`

## Types

### EventFilters

```ts
interface EventFilters {
    startDate?: string; // format: yyyy-MM-dd'T'HH:mm:ssZ
    endDate?: string;   // format: yyyy-MM-dd'T'HH:mm:ssZ
}
```

### Event

```ts
interface Event {
    fleetId: string;
    userId: string;
    origin: string;
    type: EventType;
    date: string;
    failed: boolean;
    originId?: string;
    insertionDate?: string;
    deletionDate?: string;
    doNotTrack: boolean;
    extraInfo: ExtraInfo;
}
```

### ExtraInfo

An object with event-specific data; its shape depends on the event `type`.

### EventType

A string union of 160+ event types. Examples:

| Value | Description |
| ----- | ----------- |
| `BOOKING_CANCEL` | Booking canceled |
| `TRIP_START` | Trip started |
| `TRIP_END` | Trip ended |
| `VEHICLE_LOCK` | Vehicle locked |
| `VEHICLE_UNLOCK` | Vehicle unlocked |
| `PAYMENT_SUCCESS` | Payment succeeded |
| `USER_CREATED` | User account created |
| `USER_ARCHIVED` | User account archived |
| `USER_PLAN_SUBSCRIBED` | Mobility plan subscribed |
| `USER_PLAN_UNSUBSCRIBED` | Mobility plan unsubscribed |
| `VEHICLE_OUT_OF_SERVICE` | Vehicle marked out of service |
| `VEHICLE_ENABLE` | Vehicle back in service |

See the source for the full list of supported event types.