Skip to main content

​
Data Types

TypeScript definitions for API response objects.

​
Device

type Device = {
  _id: ObjectId;
  device_id: string;
  hardware_id: string;
  device_type: string;
  name?: string;
  attributes: Record<string, unknown>;
  config?: Record<string, unknown>;
  capabilities: string[];
  commands: string[];
  is_online?: boolean;
  created_at: Date;
  updated_at: Date;
};

​
Config & Capabilities

  • config — per-device key-value object defining the device’s active capabilities and operational parameters. Validated against the device type’s config schema (JSON Schema) on every write.
  • capabilities — derived from config at read time. Each device type defines which config keys map to which capability names. Not stored; computed on every API response.
  • commands — available commands for the device’s type.

​
Notable Capabilities

CapabilityMeaning
lockDevice has lock hardware and accepts lock/unlock commands (system/geofence and, when allowed, user)
key_keylessDevice supports key vs keyless mode switching. When present, config.key_keyless_state holds the current mode
When key_keyless is in capabilities, config.key_keyless_state is "key" (physical key only, no remote), "keyless" (remote only, no physical key), or "hybrid" (physical key works and remote also allowed). Show Lock/Unlock in UI when state is "keyless" or "hybrid". Devices with lock but without key_keyless have lock hardware for system/geofence use only.

​
Config Schema

Each device type defines a config schema (standard JSON Schema, additionalProperties: false) that describes all possible config keys, their types, constraints, and defaults. 
type ConfigSchema = {
  type: "object";
  properties: Record<string, {
    type: string | string[];
    description?: string;
    default?: unknown;
    enum?: unknown[];
    minimum?: number;
    maximum?: number;
  }>;
  additionalProperties: false;
};

​
GPS Telemetry

type GPSTelemetry = {
  _id: ObjectId;
  device_id: string;
  hardware_id: string;
  timestamp: Date;
  lat: number;
  long: number;
  speed?: number;
};

​
Battery Telemetry

type BatteryTelemetry = {
  _id: ObjectId;
  device_id: string;
  hardware_id: string;
  timestamp: Date;
  battery_voltage: number;
};

​
Command

type CommandStatus = 
  | "pending" 
  | "published" 
  | "failed" 
  | "acknowledged" 
  | "completed" 
  | "timeout";

type Command = {
  _id: ObjectId;
  command_id: string;
  device_id?: string;
  hardware_id?: string;
  device_type: string;
  broker_name: string;
  topic: string;
  command: string;
  params?: Record<string, unknown>;
  status: CommandStatus;
  error_message?: string;
  created_at: Date;
  published_at?: Date;
  acknowledged_at?: Date;
  completed_at?: Date;
};

​
Trip

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

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

​
Trip Configuration

type TripConfig = {
  speedThreshold: number;         // km/h
  minimalTripDuration: number;    // seconds
  minimalTripDistance: number;    // meters
  minimalParkingDuration: number; // seconds
  minimalNoDataDuration: number;  // seconds
  minimalAvgSpeed: number;        // km/h
  maxAcceleration: number;        // m/s²
};

​
API User

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 = {
  _id: ObjectId;
  user_id: string;
  name: string;
  email?: string;
  role: UserRole;
  is_active: boolean;
  created_at: Date;
  updated_at: Date;
  usage: ApiUserUsage;
};

​
WebSocket Messages

​
Client Messages

type SubscribeMessage = {
  type: "subscribe";
  hardwareIds: string[];
};

type UnsubscribeMessage = {
  type: "unsubscribe";
  hardwareIds: string[];
};

type CommandMessage = {
  type: "command";
  hardwareId: string;
  command: string;
  params?: Record<string, unknown>;
};

​
Server Messages

type ConnectedMessage = {
  type: "connected";
  connectionId: string;
};

type SubscribedMessage = {
  type: "subscribed";
  hardwareIds: string[];
};

type DeviceDataMessage = {
  type: "device_data";
  hardwareId: string;
  deviceId: string;
  payload: Record<string, unknown>;
  timestamp: string;
};

type DeviceStatusMessage = {
  type: "device_status";
  hardwareId: string;
  deviceId: string;
  payload: { is_online: boolean };
  timestamp: string;
};

type ErrorMessage = {
  type: "error";
  message: string;
};