flightbyte 1.0.0

data/lib/flightbyte/transport.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "timeout"
+require "uri"
+require "zlib"
+
+module FlightByte
+  # Sends authenticated requests and turns error statuses into errors.
+  #
+  # @api private Reach the API through {Client}.
+  class Transport
+    # How many same-origin redirects a GET or HEAD follows.
+    MAX_REDIRECTS = 5
+
+    # Every way a request can fail without an HTTP response.
+    TRANSPORT_ERRORS = [
+      SocketError,
+      SystemCallError,
+      IOError,
+      Timeout::Error,
+      OpenSSL::OpenSSLError,
+      Net::ProtocolError,
+      Net::HTTPBadResponse,
+      Net::HTTPHeaderSyntaxError,
+      Zlib::Error
+    ].freeze
+
+    # A response, as the transport hands it back.
+    Response = Struct.new(:status, :reason, :headers, :body, keyword_init: true)
+    private_constant :Response
+
+    attr_reader :base_url, :timeout
+
+    def initialize(api_key:, base_url:, timeout:, user_agent:)
+      @api_key = api_key
+      @base_url = base_url
+      @timeout = timeout
+      @user_agent = user_agent
+      @mutex = Mutex.new
+      @last_rate_limit = nil
+    end
+
+    # The quota state from the latest response that carried one.
+    def last_rate_limit
+      @mutex.synchronize { @last_rate_limit }
+    end
+
+    # Builds the URL for `path` under the base URL, each segment escaped.
+    # `nil` and empty query values are left out.
+    def url(path, query = nil)
+      url = "#{@base_url}/#{path.map { |segment| Transport.escape(segment) }.join("/")}"
+      pairs = (query || {}).filter_map do |key, value|
+        [key.to_s, value.to_s] unless value.nil? || value == ""
+      end
+      pairs.empty? ? url : "#{url}?#{URI.encode_www_form(pairs)}"
+    end
+
+    # Sends a request and returns the decoded JSON, or `nil` for an empty body.
+    def request(method, path, query: nil, body: nil, headers: nil, timeout: nil)
+      timeout = timeout.nil? ? @timeout : Transport.check_timeout(timeout)
+      target = url(path, query)
+      request_headers = { "x-api-key" => @api_key, "accept" => "application/json", "user-agent" => @user_agent }
+      request_headers.merge!(headers) if headers
+      payload = nil
+      if body.nil?
+        request_headers["content-length"] = "0" if %w[POST PUT PATCH].include?(method)
+      else
+        request_headers["content-type"] = "application/json"
+        payload = JSON.generate(body)
+      end
+
+      response = perform(method, target, request_headers, payload, timeout)
+      handle(method, target, response)
+    end
+
+    # Never shows the API key.
+    def inspect
+      "#<#{self.class.name} base_url=#{@base_url.inspect}>"
+    end
+
+    class << self
+      # Escapes one path segment, so an id like `../admin?x=1` stays one segment.
+      def escape(segment)
+        segment = segment.to_s
+        # `.` and `..` would be read as a step up or across the path.
+        return segment.gsub(".", "%2E") if segment.match?(/\A\.{1,2}\z/)
+
+        segment.b.gsub(/[^A-Za-z0-9\-._~]/n) { |byte| format("%%%02X", byte.ord) }
+      end
+
+      # Rejects an empty path parameter before it turns into a request for the wrong URL.
+      def required(name, value)
+        value = value.to_s if value.is_a?(Integer) || value.is_a?(Symbol)
+        raise ArgumentError, "flightbyte: #{name} is required." unless value.is_a?(String) && !value.strip.empty?
+
+        value
+      end
+
+      # A flight date: a `YYYY-MM-DD` string, or a Date or Time to format.
+      def date(name, value)
+        value.respond_to?(:strftime) ? FlightByte.format_date(value) : required(name, value)
+      end
+
+      def check_timeout(value)
+        unless value.is_a?(Numeric) && value.real? && value.finite? && value >= 0
+          raise ArgumentError, "flightbyte: timeout must be a number of seconds, 0 or more; got #{value.inspect}."
+        end
+
+        value
+      end
+    end
+
+    private
+
+    def perform(method, target, headers, payload, timeout)
+      with_deadline(timeout) do
+        deadline = timeout.positive? ? clock + timeout : nil
+        current = target
+        hops = 0
+        loop do
+          response = exchange(method, URI(current), headers, payload, deadline)
+          following = followable_redirect(response, current, method)
+          return response if following.nil? || hops >= MAX_REDIRECTS
+
+          hops += 1
+          current = following
+        end
+      end
+    rescue Timeout::Error
+      raise ConnectionError.new("#{method} #{target} timed out after #{seconds(timeout)}.", timed_out: true)
+    rescue *TRANSPORT_ERRORS => e
+      raise ConnectionError, "#{method} #{target} failed: #{e.message} (#{e.class})"
+    end
+
+    # The overall deadline: it bounds the whole exchange, redirects and the
+    # response body included, which the per-read timeouts alone cannot.
+    def with_deadline(timeout, &)
+      timeout.positive? ? Timeout.timeout(timeout, &) : yield
+    end
+
+    def exchange(method, uri, headers, payload, deadline)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      # Net::HTTP retries an idempotent request once on its own; a retry is
+      # the caller's call, and it would stretch the timeout.
+      http.max_retries = 0
+      remaining = deadline && [deadline - clock, 0.001].max
+      http.open_timeout = remaining
+      http.read_timeout = remaining
+      http.write_timeout = remaining
+
+      # Built as a generic request so that one without a payload has no body
+      # at all. Before Ruby 4.0, Net::HTTP::Post and friends give a body-less
+      # request an empty body and then a form content type, with a warning.
+      request = Net::HTTPGenericRequest.new(method, !payload.nil?, method != "HEAD", uri.request_uri, headers)
+      http.start do |connection|
+        response = connection.request(request, payload)
+        Response.new(
+          status: response.code.to_i,
+          reason: response.message.to_s,
+          headers: response.each_header.to_h.freeze,
+          # Invalid bytes become U+FFFD, as a browser or Node would decode them.
+          body: response.body.to_s.dup.force_encoding(Encoding::UTF_8).scrub
+        )
+      end
+    end
+
+    # Where to go next when `response` is a redirect this client may follow: a
+    # GET or HEAD, to the same origin (scheme, host and port). Anything else
+    # reaches the caller as an error, so the API key, sent with every request,
+    # never reaches another server or travels in the clear, and a write is
+    # never replayed.
+    def followable_redirect(response, from, method)
+      return nil unless (300..399).cover?(response.status) && %w[GET HEAD].include?(method)
+
+      location = response.headers["location"].to_s
+      return nil if location.empty?
+
+      target = URI.join(from, location)
+      same_origin?(URI(from), target) ? target.to_s : nil
+    rescue URI::Error
+      nil
+    end
+
+    def same_origin?(from, target)
+      target.is_a?(URI::HTTP) && !target.host.to_s.empty? &&
+        from.scheme.downcase == target.scheme.to_s.downcase &&
+        from.host.downcase == target.host.downcase &&
+        from.port == target.port
+    end
+
+    def handle(method, target, response)
+      rate_limit = RateLimit.parse(response.headers)
+      @mutex.synchronize { @last_rate_limit = rate_limit } if rate_limit
+
+      unless (200..299).cover?(response.status)
+        raise APIError.from(response.status, response.reason, response.body, response.headers)
+      end
+      return nil if response.status == 204 || response.body.strip.empty?
+
+      begin
+        JSON.parse(response.body)
+      rescue JSON::ParserError, EncodingError
+        text = response.body
+        preview = text.length > 200 ? "#{text[0, 200]}..." : text
+        raise Error, "Expected JSON from #{method} #{target}, got: #{preview}"
+      end
+    end
+
+    def clock
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def seconds(value)
+      value = value.to_i if value.is_a?(Float) && value == value.to_i
+      "#{value} #{value == 1 ? "second" : "seconds"}"
+    end
+  end
+  private_constant :Transport
+end

data/lib/flightbyte/values.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module FlightByte
+  # The values the API's string enums take, as this version knows them. The
+  # API may add more: a value added after this release still arrives as a
+  # plain `String`, so nothing breaks. Compare with strings, or check
+  # `FLIGHT_PHASES.include?(phase)` to see whether this version knows a value.
+
+  # Every flight phase this version knows, in the API's order.
+  FLIGHT_PHASES = %w[
+    scheduled boarding departed en_route landed arrived cancelled diverted redirected unknown
+  ].freeze
+
+  # The phases after which nothing about the flight changes any more.
+  TERMINAL_PHASES = %w[arrived cancelled diverted redirected].freeze
+
+  # Every subscription status this version knows.
+  #
+  # `active` polls and delivers, `pending` waits for the flight to be
+  # published upstream, `paused` was paused by you, `completed` finished after
+  # the flight did, `suspended` was disabled by the API, for example after
+  # repeated delivery failures.
+  SUBSCRIPTION_STATUSES = %w[active pending paused completed suspended].freeze
+
+  # Every flight change type this version knows, in the API's order: the kind
+  # of change a `flight.updated` webhook reports, and what a subscription's
+  # `events` filter is made of.
+  FLIGHT_CHANGE_TYPES = %w[
+    status.changed
+    flight.departed
+    flight.arrived
+    flight.cancelled
+    flight.diverted
+    flight.reinstated
+    departure.gate.changed
+    departure.terminal.changed
+    arrival.gate.changed
+    arrival.terminal.changed
+    arrival.baggage.changed
+    departure.scheduled.changed
+    departure.estimated.changed
+    departure.actual.changed
+    arrival.scheduled.changed
+    arrival.estimated.changed
+    arrival.actual.changed
+    delay.increased
+    delay.decreased
+    aircraft.changed
+    aircraft.tail.changed
+    route.changed
+    codeshares.changed
+  ].freeze
+
+  # Every webhook event type this version knows.
+  WEBHOOK_EVENT_TYPES = %w[
+    subscription.created
+    subscription.activated
+    subscription.test
+    subscription.completed
+    subscription.suspended
+    flight.updated
+  ].freeze
+
+  # Every delivery status this version knows: the outcome of one webhook
+  # delivery attempt.
+  DELIVERY_STATUSES = %w[delivered failed].freeze
+end

data/lib/flightbyte/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module FlightByte
+  # This gem's version. It is sent in the `User-Agent` header of every request.
+  VERSION = "1.0.0"
+end

data/lib/flightbyte/webhook/rack_app.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module FlightByte
+  module Webhook
+    # A Rack app that receives FlightByte webhooks. It needs no Rack gem, so
+    # it runs under anything that speaks Rack: Rails, Sinatra, Hanami, Roda,
+    # or a bare `config.ru` on Puma.
+    #
+    #   # config/routes.rb
+    #   mount FlightByte::Webhook::RackApp.new(ENV.fetch("FLIGHTBYTE_WEBHOOK_SECRET")) { |event|
+    #     FlightEventJob.perform_later(event.to_h)
+    #   }, at: "/hooks/flightbyte"
+    #
+    # It reads up to {MAX_BODY_BYTES}, verifies the signature, decodes the
+    # event and calls the block with it and the Rack env. It answers 405 to
+    # anything but POST, 413 to a larger body, 401 when the signature does not
+    # verify, 400 when the body is not an event, 500 when the block raises (so
+    # FlightByte retries) and 200 otherwise. Retries carry the same event id:
+    # deduplicate on `event.id`.
+    class RackApp
+      # @param secret [String] the subscription's signing secret
+      # @param tolerance [Numeric] how far the signing time may be from now, in seconds; `0` skips the check
+      # @param now [Time, Numeric, nil] the time to check against instead of now; useful in tests
+      # @param on_error [#call, nil] called with the error, the event and the
+      #   Rack env when the block raises, after the 500 is decided. Defaults to
+      #   `warn`. Whatever it raises is ignored, so the answer stays 500.
+      # @yieldparam event [WebhookEvent]
+      # @yieldparam env [Hash] the Rack env
+      # @raise [ArgumentError] right away when `secret` is empty, so an unset
+      #   environment variable fails at boot instead of accepting forged events,
+      #   or when no block is given
+      def initialize(secret, tolerance: DEFAULT_TOLERANCE, now: nil, on_error: nil, &handler)
+        Webhook.check_secret(secret)
+        raise ArgumentError, "flightbyte: RackApp needs a block to handle each event." unless handler
+        unless on_error.nil? || on_error.respond_to?(:call)
+          raise ArgumentError, "flightbyte: on_error must respond to call."
+        end
+
+        @secret = secret.dup.freeze
+        @tolerance = tolerance
+        @now = now
+        @on_error = on_error || method(:report)
+        @handler = handler
+        freeze
+      end
+
+      # Handles one Rack request.
+      #
+      # @param env [Hash] the Rack env
+      # @return [Array(Integer, Hash, Array<String>)]
+      def call(env)
+        return reply(405, "method not allowed", "allow" => "POST") unless env["REQUEST_METHOD"] == "POST"
+
+        payload = read_body(env)
+        return reply(413, "body too large") if payload.nil?
+
+        begin
+          event = Webhook.construct_event(payload, env[SIGNATURE_ENV_KEY], @secret, tolerance: @tolerance, now: @now)
+        rescue WebhookSignatureError
+          return reply(401, "invalid signature")
+        rescue Error
+          return reply(400, "invalid event")
+        end
+
+        begin
+          @handler.call(event, env)
+        rescue StandardError => e
+          notify(e, event, env)
+          return reply(500, "handler failed")
+        end
+        reply(200, "ok")
+      end
+
+      # Never shows the signing secret.
+      def inspect
+        "#<#{self.class.name}>"
+      end
+
+      private
+
+      # The body, or nil when it is larger than MAX_BODY_BYTES.
+      def read_body(env)
+        declared = env["CONTENT_LENGTH"].to_s
+        return nil if declared.match?(/\A\d+\z/) && declared.to_i > MAX_BODY_BYTES
+
+        input = env["rack.input"]
+        return +"" if input.nil?
+
+        body = +"".b
+        while (chunk = input.read(16 * 1024))
+          body << chunk
+          return nil if body.bytesize > MAX_BODY_BYTES
+        end
+        body
+      end
+
+      def notify(error, event, env)
+        @on_error.call(error, event, env)
+      rescue StandardError
+        # A failing reporter must not change the answer.
+        nil
+      end
+
+      def report(error, event, _env)
+        warn "flightbyte: the webhook handler failed for event #{event.id} (#{event.type}): " \
+             "#{error.full_message(highlight: false)}"
+      end
+
+      def reply(status, text, headers = {})
+        [status, { "content-type" => "text/plain; charset=utf-8" }.merge(headers), [text]]
+      end
+    end
+  end
+end

data/lib/flightbyte/webhook.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+module FlightByte
+  # Verifies and decodes the webhooks FlightByte posts to your receiver.
+  #
+  # Each delivery carries an `x-flightbyte-signature` header of the form
+  # `t=<unix seconds>,v1=<hex>`, where the hex is HMAC-SHA256 of
+  # `"<t>.<raw body>"` keyed with the subscription's signing secret.
+  #
+  #   event = FlightByte::Webhook.construct_event(
+  #     request.raw_post,
+  #     request.headers["X-FlightByte-Signature"],
+  #     ENV.fetch("FLIGHTBYTE_WEBHOOK_SECRET")
+  #   )
+  #
+  # Pass the body exactly as received: JSON parsed and serialized again no
+  # longer matches the signature. Keep the signing secret on your server.
+  module Webhook
+    # Header carrying the signature.
+    SIGNATURE_HEADER = "x-flightbyte-signature"
+    # Header carrying the signing time, in unix seconds.
+    TIMESTAMP_HEADER = "x-flightbyte-timestamp"
+    # Header carrying the event id.
+    EVENT_ID_HEADER = "x-flightbyte-event-id"
+    # Header carrying the event type.
+    EVENT_TYPE_HEADER = "x-flightbyte-event-type"
+    # Header carrying the subscription id.
+    SUBSCRIPTION_ID_HEADER = "x-flightbyte-subscription-id"
+    # Header carrying the delivery attempt number, starting at 1.
+    DELIVERY_ATTEMPT_HEADER = "x-flightbyte-delivery-attempt"
+    # The Rack env key of {SIGNATURE_HEADER}, for `request.env[...]`.
+    SIGNATURE_ENV_KEY = "HTTP_X_FLIGHTBYTE_SIGNATURE"
+    # How far the signing time may be from now by default, in seconds: 5 minutes.
+    DEFAULT_TOLERANCE = 300
+    # The largest body {RackApp} reads: 1 MiB.
+    MAX_BODY_BYTES = 1024 * 1024
+
+    class << self
+      # Checks `signature` (the `x-flightbyte-signature` header) against the
+      # raw body `payload` and the subscription's `secret`.
+      #
+      # @param payload [String] the body exactly as received, for example Rails'
+      #   `request.raw_post` or Rack's `env["rack.input"].read`
+      # @param signature [String, nil] the `x-flightbyte-signature` header
+      # @param secret [String] the subscription's signing secret
+      # @param tolerance [Numeric] how far the signing time may be from now, in
+      #   seconds; `0` skips the check
+      # @param now [Time, Numeric, nil] the time to check against instead of
+      #   now, as a Time or unix seconds; useful in tests
+      # @return [true]
+      # @raise [WebhookSignatureError] when the signature does not verify
+      # @raise [ArgumentError] when `secret` is empty: anyone can sign with an
+      #   empty key, so it usually means the secret was not configured
+      def verify(payload, signature, secret, tolerance: DEFAULT_TOLERANCE, now: nil)
+        check_secret(secret)
+        unless tolerance.is_a?(Numeric) && tolerance.real?
+          raise ArgumentError, "flightbyte: tolerance must be a number of seconds; got #{tolerance.inspect}."
+        end
+
+        body = bytes(payload)
+        timestamp, signatures = parse_signature(signature)
+        if tolerance.positive?
+          current = unix(now || Time.now)
+          # Compared against both edges, so an extreme timestamp cannot slip through.
+          if timestamp.to_i < current - tolerance || timestamp.to_i > current + tolerance
+            raise WebhookSignatureError, "The signature timestamp is outside the tolerance window."
+          end
+        end
+
+        expected = hmac(secret, timestamp, body)
+        matched = signatures.any? do |candidate|
+          candidate.bytesize == expected.bytesize && OpenSSL.fixed_length_secure_compare(candidate, expected)
+        end
+        raise WebhookSignatureError, "The signature does not match the payload." unless matched
+
+        true
+      end
+
+      # Whether `signature` verifies; see {.verify}.
+      #
+      # @return [Boolean]
+      # @raise [ArgumentError] when `secret` is empty
+      def valid?(payload, signature, secret, tolerance: DEFAULT_TOLERANCE, now: nil)
+        verify(payload, signature, secret, tolerance: tolerance, now: now)
+      rescue WebhookSignatureError
+        false
+      end
+
+      # Verifies the signature, then decodes the event.
+      #
+      # @param (see .verify)
+      # @return [WebhookEvent]
+      # @raise [WebhookSignatureError] when the signature does not verify
+      # @raise [Error] when the verified body is not a webhook event
+      # @raise [ArgumentError] when `secret` is empty
+      def construct_event(payload, signature, secret, tolerance: DEFAULT_TOLERANCE, now: nil)
+        verify(payload, signature, secret, tolerance: tolerance, now: now)
+        begin
+          # As text, invalid bytes replaced, the way the API's other clients decode it.
+          event = JSON.parse(bytes(payload).force_encoding(Encoding::UTF_8).scrub)
+        rescue JSON::ParserError, EncodingError
+          raise Error, "The webhook body is not JSON."
+        end
+        unless event.is_a?(Hash) && event["id"].is_a?(String) && event["type"].is_a?(String)
+          raise Error, "The webhook body is not a FlightByte event."
+        end
+
+        WebhookEvent.from_response(event)
+      end
+
+      # Signs `payload` the way the API does and returns the
+      # `x-flightbyte-signature` header value. Useful for testing your receiver.
+      #
+      # @param payload [String]
+      # @param secret [String]
+      # @param timestamp [Time, Numeric, nil] the signing time, as a Time or unix seconds; now by default
+      # @return [String]
+      # @raise [ArgumentError] when `secret` is empty
+      def sign(payload, secret, timestamp: nil)
+        check_secret(secret)
+        seconds = unix(timestamp || Time.now).to_s
+        "t=#{seconds},v1=#{hmac(secret, seconds, bytes(payload))}"
+      end
+
+      # @api private
+      # Raises ArgumentError for an empty or blank secret.
+      def check_secret(secret)
+        return if secret.is_a?(String) && !secret.strip.empty?
+
+        raise ArgumentError,
+              "flightbyte: the webhook signing secret is empty. Anyone can sign with an empty key; " \
+              "set the subscription's secret."
+      end
+
+      private
+
+      # Splits `t=<seconds>,v1=<hex>[,v1=<hex>...]`.
+      def parse_signature(header)
+        # As bytes, so a header that is not valid text cannot raise anything else.
+        header = header.to_s.b
+        raise WebhookSignatureError, "The signature header is missing." if header.strip.empty?
+
+        timestamp = nil
+        signatures = []
+        header.split(",").each do |part|
+          key, separator, value = part.partition("=")
+          next if separator.empty? || key.strip.empty?
+
+          case key.strip
+          when "t" then timestamp = value.strip
+          when "v1" then signatures << value.strip.downcase
+          end
+        end
+        unless timestamp&.match?(/\A\d{1,15}\z/)
+          raise WebhookSignatureError, "The signature header has no valid timestamp."
+        end
+        raise WebhookSignatureError, "The signature header has no v1 signature." if signatures.empty?
+
+        [timestamp, signatures]
+      end
+
+      def hmac(secret, timestamp, body)
+        OpenSSL::HMAC.hexdigest("SHA256", secret.b, "#{timestamp}.".b + body)
+      end
+
+      def bytes(payload)
+        unless payload.respond_to?(:to_str)
+          raise TypeError, "flightbyte: the webhook payload must be the raw body as a String, got #{payload.class}."
+        end
+
+        payload.to_str.b
+      end
+
+      def unix(time)
+        case time
+        when Time then time.to_i
+        when Numeric then time.floor
+        else raise ArgumentError, "flightbyte: expected a Time or unix seconds, got #{time.inspect}."
+        end
+      end
+    end
+  end
+end

data/lib/flightbyte.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "date"
+require "json"
+
+require_relative "flightbyte/version"
+require_relative "flightbyte/values"
+require_relative "flightbyte/errors"
+require_relative "flightbyte/object"
+require_relative "flightbyte/models"
+require_relative "flightbyte/rate_limit"
+require_relative "flightbyte/transport"
+require_relative "flightbyte/resources/flights"
+require_relative "flightbyte/resources/subscriptions"
+require_relative "flightbyte/resources/countries"
+require_relative "flightbyte/client"
+require_relative "flightbyte/webhook"
+require_relative "flightbyte/webhook/rack_app"
+
+# The official client for the FlightByte flight status API: look flights up,
+# watch them with signed webhooks and verify every delivery.
+#
+#   require "flightbyte"
+#
+#   client = FlightByte::Client.new(api_key: ENV.fetch("FLIGHTBYTE_API_KEY"))
+#   flight = client.flights.get(carrier: "TK", flight_number: "1848", date: "2026-09-08")
+#   flight.status.label # => "Scheduled"
+#
+# Keep API keys on a server you control. A key shipped inside a browser or
+# mobile app can be extracted by anyone who has the app.
+module FlightByte
+  class << self
+    # Formats a date as the `YYYY-MM-DD` the API expects for flight dates.
+    #
+    # Only the calendar fields are used, in the value's own time zone, so pass
+    # the local departure date at the origin airport: a `Date`, or a `Time`
+    # already in the airport's offset (`time.getlocal("+03:00")`, or
+    # `time.in_time_zone("Europe/Istanbul")` with Active Support).
+    #
+    # @param value [Date, Time, DateTime, #strftime]
+    # @return [String]
+    # @raise [ArgumentError] when `value` is not a date or a time
+    def format_date(value)
+      unless value.respond_to?(:strftime)
+        raise ArgumentError, "flightbyte: format_date needs a Date or a Time, got #{value.inspect}."
+      end
+
+      value.strftime("%Y-%m-%d")
+    end
+
+    # Whether the flight is finished: arrived, cancelled, diverted or redirected.
+    #
+    # @param phase [String, nil] a {FlightStatusInfo#phase}
+    # @return [Boolean]
+    def terminal_phase?(phase)
+      TERMINAL_PHASES.include?(phase.to_s)
+    end
+
+    # The best known gate time: actual, else estimated, else scheduled.
+    #
+    # @param times [EndpointTimes, Hash, nil] a {FlightEndpoint#times}
+    # @return [FlightTime, Hash, nil]
+    def best_gate_time(times)
+      return nil if times.nil?
+
+      times["actualGate"] || times["estimatedGate"] || times["scheduledGate"]
+    end
+
+    # Masks a signing secret the way the API does: the first 11 characters,
+    # `...`, and the last 4. Short secrets are returned as they are.
+    #
+    # @param secret [String]
+    # @return [String]
+    def mask_secret(secret)
+      secret = secret.to_s
+      secret.length <= 15 ? secret : "#{secret[0, 11]}...#{secret[-4..]}"
+    end
+  end
+end