syntax = "proto3";

package worldmonitor.aviation.v1;

import "sebuf/http/annotations.proto";
import "worldmonitor/aviation/v1/carrier.proto";

// FlightInstanceStatus represents the operational status of a flight occurrence.
enum FlightInstanceStatus {
  // Unspecified status.
  FLIGHT_INSTANCE_STATUS_UNSPECIFIED = 0;
  // Flight is scheduled but has not departed.
  FLIGHT_INSTANCE_STATUS_SCHEDULED = 1;
  // Boarding is in progress.
  FLIGHT_INSTANCE_STATUS_BOARDING = 2;
  // Flight has departed the gate.
  FLIGHT_INSTANCE_STATUS_DEPARTED = 3;
  // Flight is airborne.
  FLIGHT_INSTANCE_STATUS_AIRBORNE = 4;
  // Flight has landed at destination.
  FLIGHT_INSTANCE_STATUS_LANDED = 5;
  // Flight has arrived at the gate.
  FLIGHT_INSTANCE_STATUS_ARRIVED = 6;
  // Flight has been cancelled.
  FLIGHT_INSTANCE_STATUS_CANCELLED = 7;
  // Flight has been diverted to an alternate airport.
  FLIGHT_INSTANCE_STATUS_DIVERTED = 8;
  // Flight status is unknown.
  FLIGHT_INSTANCE_STATUS_UNKNOWN = 9;
}

// AirportRef is a lightweight reference to an airport.
message AirportRef {
  // IATA airport code (e.g., "IST").
  string iata = 1;
  // ICAO airport code (e.g., "LTFM").
  string icao = 2;
  // Airport name (e.g., "Istanbul Airport").
  string name = 3;
  // IANA timezone (e.g., "Europe/Istanbul").
  string timezone = 4;
}

// FlightInstance represents a specific occurrence of a flight on a given date.
message FlightInstance {
  // IATA flight number (e.g., "TK1952").
  string flight_number = 1;
  // Departure date in ISO 8601 format (e.g., "2026-03-05").
  string date = 2;
  // Operating carrier for this flight.
  Carrier operating_carrier = 3;
  // Origin airport.
  AirportRef origin = 4;
  // Destination airport.
  AirportRef destination = 5;
  // Scheduled departure time as Unix epoch milliseconds (UTC).
  int64 scheduled_departure = 6 [(sebuf.http.int64_encoding) = INT64_ENCODING_NUMBER];
  // Estimated departure time as Unix epoch milliseconds (UTC).
  int64 estimated_departure = 7 [(sebuf.http.int64_encoding) = INT64_ENCODING_NUMBER];
  // Actual departure time as Unix epoch milliseconds (UTC).
  int64 actual_departure = 8 [(sebuf.http.int64_encoding) = INT64_ENCODING_NUMBER];
  // Scheduled arrival time as Unix epoch milliseconds (UTC).
  int64 scheduled_arrival = 9 [(sebuf.http.int64_encoding) = INT64_ENCODING_NUMBER];
  // Estimated arrival time as Unix epoch milliseconds (UTC).
  int64 estimated_arrival = 10 [(sebuf.http.int64_encoding) = INT64_ENCODING_NUMBER];
  // Actual arrival time as Unix epoch milliseconds (UTC).
  int64 actual_arrival = 11 [(sebuf.http.int64_encoding) = INT64_ENCODING_NUMBER];
  // Current operational status.
  FlightInstanceStatus status = 12;
  // Delay in minutes (0 if on time, negative if early).
  int32 delay_minutes = 13;
  // Whether the flight is cancelled.
  bool cancelled = 14;
  // Whether the flight has been diverted.
  bool diverted = 15;
  // Departure gate (if available).
  string gate = 16;
  // Departure terminal (if available).
  string terminal = 17;
  // ICAO 24-bit transponder address of the aircraft (hex, e.g., "4b1805").
  string aircraft_icao24 = 18;
  // Aircraft type designator (e.g., "B738").
  string aircraft_type = 19;
  // Codeshare flight numbers marketed under this operating flight.
  repeated string codeshare_flight_numbers = 20;
  // Data source provider name.
  string source = 21;
  // Last update time as Unix epoch milliseconds.
  int64 updated_at = 22 [(sebuf.http.int64_encoding) = INT64_ENCODING_NUMBER];
}
