> ## Documentation Index
> Fetch the complete documentation index at: https://docs.iotee.eu/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Types

> TypeScript type definitions for all API resources: devices, telemetry, trips, lock events, users.

## Device

```typescript theme={null}
type Device = {
  short_id: string;
  hardware_id: string;
  device_type: string;
  name?: string;
  attributes: Record<string, unknown>;
  is_online?: boolean;
  created_at: Date;
  updated_at: Date;
  last_responded_at?: Date;
};
```

## GPS Telemetry

```typescript theme={null}
type GPSTelemetry = {
  hardware_id: string;
  timestamp: Date;
  lat: number;
  long: number;
  speed?: number;
};
```

## Battery Telemetry

```typescript theme={null}
type BatteryTelemetry = {
  hardware_id: string;
  timestamp: Date;
  battery_voltage: number;
};
```

## Trip

```typescript theme={null}
type Trip = {
  hardware_id: string;
  startTime: Date;
  endTime: Date;
  startLocation: { lat: number; long: number };
  endLocation: { lat: number; long: number };
  distance: number;   // meters
  duration: number;    // seconds
  maxSpeed: number;    // km/h
  avgSpeed: number;    // km/h
  pointCount: number;
};
```

## Stop

```typescript theme={null}
type Stop = {
  startTime: Date;
  endTime: Date;
  location: { lat: number; long: number };
  duration: number;  // seconds
};
```

## Lock Event

```typescript theme={null}
type UnlockSource = "rfid" | "keypad" | "key" | "remote";

type LockEvent = {
  event_id: string;
  hardware_id: string;
  event: "unlock" | "lock";
  timestamp: Date;
  source: UnlockSource;
  code?: string;
  metadata?: Record<string, unknown>;
};
```

| Source   | `code`         | `metadata` | Triggered by    |
| -------- | -------------- | ---------- | --------------- |
| `rfid`   | RFID tag value | -          | Device hardware |
| `keypad` | Code entered   | -          | Device hardware |
| `key`    | -              | -          | Physical key    |
| `remote` | -              | Optional   | API call        |

## Trip Configuration

```typescript theme={null}
type TripConfig = {
  speedThreshold: number;         // km/h — below this speed is stopped
  minimalTripDuration: number;    // seconds
  minimalTripDistance: number;     // meters
  minimalParkingDuration: number; // seconds
  minimalNoDataDuration: number;  // seconds
  minimalAvgSpeed: number;        // km/h — filters GPS drift
  maxAcceleration: number;        // m/s² — filters GPS spikes
};
```

A trip is only recorded if it meets **all** of these criteria:

* Duration >= `minimalTripDuration`
* Distance >= `minimalTripDistance`
* Average speed >= `minimalAvgSpeed`

## API User

```typescript theme={null}
type UserRole = "user" | "admin";

type ApiUserUsage = {
  total_requests: number;
  last_used_at?: Date;
  first_used_at?: Date;
  requests_today: number;
  last_reset: Date;
};

type ApiUser = {
  user_id: string;
  name: string;
  email?: string;
  role: UserRole;
  is_active: boolean;
  allowed_hardware_ids?: string[] | null;
  created_at: Date;
  updated_at: Date;
  usage: ApiUserUsage;
};
```

**Usage tracking fields:**

| Field            | Description                                        |
| ---------------- | -------------------------------------------------- |
| `total_requests` | Total number of API requests made with this key    |
| `last_used_at`   | Timestamp of the most recent request               |
| `first_used_at`  | Timestamp of the first request (set on first use)  |
| `requests_today` | Number of requests made today (resets at midnight) |
| `last_reset`     | Timestamp when the daily counter was last reset    |