flightbyte 1.0.0

data/lib/flightbyte/object.rb

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+
+module FlightByte
+  # A read-only view of a JSON object the API sent.
+  #
+  # Fields read as methods with snake_case names (`flight.departure.delay_minutes`),
+  # or with `[]` and the API's own camelCase key (`flight["departure"]["delayMinutes"]`).
+  # {#to_h} returns the JSON exactly as it was received.
+  #
+  # Each response has its own subclass, such as {FlightSnapshot} or
+  # {Subscription}, that declares the fields this version knows. A known field
+  # the API left out reads as `nil`, so a delay of `0` and no delay reading stay
+  # apart. A field the API added after this release still reads as a method
+  # and with `[]`; a name that is neither raises `NoMethodError`, so a typo does
+  # not pass for a missing value.
+  #
+  # Objects are frozen and safe to share between threads. Timestamps stay ISO
+  # 8601 strings and enums stay strings, exactly as the API sent them.
+  class Object
+    @fields = {}.freeze
+
+    class << self
+      # The fields this class declares: the API's key to the type its value is
+      # wrapped in (`nil` for a plain JSON value).
+      #
+      # @return [Hash{String => Object}]
+      attr_reader :fields
+
+      # The snake_case method name for an API key: `delayMinutes` reads as
+      # `delay_minutes`.
+      #
+      # @param key [String]
+      # @return [String]
+      def method_name(key)
+        key.to_s
+           .gsub(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2')
+           .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+           .tr("-", "_")
+           .downcase
+      end
+
+      # @api private
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@fields, fields)
+      end
+
+      # @api private
+      # Wraps already frozen JSON without copying it again.
+      def build(frozen)
+        allocate.tap { |object| object.send(:setup, frozen) }
+      end
+
+      # @api private
+      # Wraps a decoded response body, which must be a JSON object.
+      def from_response(data)
+        unless data.is_a?(Hash)
+          raise Error, "flightbyte: expected a JSON object from the API for #{name}, got #{data.inspect[0, 100]}"
+        end
+
+        build(deep_freeze_copy(data))
+      end
+
+      # @api private
+      # Wraps the `data` list of a decoded `{ count, data }` response.
+      def list_from_response(data)
+        list = data.is_a?(Hash) ? data["data"] : nil
+        unless list.is_a?(Array)
+          raise Error, "flightbyte: expected a JSON object with a data list from the API for #{name}"
+        end
+
+        list.map { |item| from_response(item) }.freeze
+      end
+
+      private
+
+      # Declares a field: a reader named after `key` in snake_case, and with
+      # `predicate: true` a `?` reader that is true only when the API sent `true`.
+      #
+      # `type` is a subclass to wrap an object in, `[Subclass]` for a list of
+      # them, or `:map` for a map of your own strings such as `metadata`, which
+      # reads as a frozen `Hash`.
+      def field(key, type = nil, predicate: false)
+        @fields = fields.merge(key => type).freeze
+        name = Object.method_name(key)
+        define_method(name) { @values[key] }
+        define_method("#{name}?") { @values[key] == true } if predicate
+        name.to_sym
+      end
+    end
+
+    # Wraps `data`, a Hash shaped like the API's JSON. Keys may be strings or
+    # symbols; the data is copied, so changing `data` later changes nothing here.
+    #
+    # @param data [Hash]
+    def initialize(data = {})
+      raise TypeError, "flightbyte: #{self.class} needs a Hash, got #{data.class}." unless data.is_a?(Hash)
+
+      setup(Object.deep_freeze_copy(data))
+    end
+
+    # The value under the API's own key, wrapped as the method would return it.
+    #
+    # @param key [String, Symbol] the camelCase key, for example `"delayMinutes"`
+    # @return [Object, nil]
+    def [](key)
+      @values[key.to_s]
+    end
+
+    # Reads a nested value, as `Hash#dig` does: `flight.dig("departure", "gate")`.
+    #
+    # @return [Object, nil]
+    def dig(key, *rest)
+      value = self[key]
+      return value if rest.empty? || value.nil?
+
+      value.dig(*rest)
+    end
+
+    # Whether the API sent `key`, even as `null`.
+    #
+    # @param key [String, Symbol]
+    def key?(key)
+      @raw.key?(key.to_s)
+    end
+
+    # The keys the API sent, in its order.
+    #
+    # @return [Array<String>]
+    def keys
+      @raw.keys
+    end
+
+    # The JSON exactly as the API sent it, with string keys. A fresh copy each
+    # time, so changing it changes nothing here.
+    #
+    # @return [Hash{String => Object}]
+    def to_h
+      Object.deep_copy(@raw)
+    end
+
+    # The JSON as received; used by Rails' `render json:`.
+    #
+    # @return [Hash{String => Object}]
+    def as_json(*)
+      to_h
+    end
+
+    # The JSON as received, serialized.
+    #
+    # @return [String]
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+
+    # Pattern matching with snake_case keys:
+    #
+    #   case flight
+    #   in { status: { phase: "landed" | "arrived" }, arrival: { gate: String => gate } }
+    #     puts "Landed at gate #{gate}"
+    #   end
+    #
+    # @return [Hash{Symbol => Object}]
+    def deconstruct_keys(keys)
+      names = self.class.fields.keys.to_h { |key| [Object.method_name(key).to_sym, key] }.merge(@extra)
+      names = names.slice(*keys) if keys
+      names.transform_values { |key| @values[key] }
+    end
+
+    # Equal when the class and the JSON are the same.
+    def ==(other)
+      other.instance_of?(self.class) && other.raw == @raw
+    end
+    alias eql? ==
+
+    # @return [Integer]
+    def hash
+      [self.class, @raw].hash
+    end
+
+    # Shows the JSON, with any signing secret masked so it stays out of logs.
+    #
+    # @return [String]
+    def inspect
+      "#<#{self.class.name} #{Object.mask_secrets(@raw).inspect}>"
+    end
+    alias to_s inspect
+
+    # @api private
+    def pretty_print(printer)
+      printer.text(inspect)
+    end
+
+    # @api private
+    def respond_to_missing?(name, include_private = false)
+      @extra.key?(name) || super
+    end
+
+    # @api private
+    def method_missing(name, *args, &block)
+      key = @extra[name]
+      return super if key.nil? || !args.empty? || block
+
+      @values[key]
+    end
+
+    protected
+
+    # @api private
+    attr_reader :raw
+
+    private
+
+    def setup(frozen)
+      fields = self.class.fields
+      @raw = frozen
+      @values = {}
+      @extra = {}
+      frozen.each do |key, value|
+        @extra[Object.method_name(key).to_sym] = key unless fields.key?(key)
+        @values[key] = Object.wrap(value, fields[key])
+      end
+      @values.freeze
+      @extra.freeze
+      freeze
+    end
+
+    class << self
+      # @api private
+      def wrap(value, type)
+        case value
+        when Hash
+          return value if type == :map
+
+          (type.is_a?(Class) && type <= Object ? type : Object).build(value)
+        when Array
+          element = type.is_a?(Array) ? type.first : nil
+          value.map { |item| wrap(item, element) }.freeze
+        else
+          value
+        end
+      end
+
+      # @api private
+      def deep_freeze_copy(value)
+        case value
+        when Hash then value.to_h { |key, item| [key.to_s.dup.freeze, deep_freeze_copy(item)] }.freeze
+        when Array then value.map { |item| deep_freeze_copy(item) }.freeze
+        when String then value.frozen? ? value : value.dup.freeze
+        when Object then deep_freeze_copy(value.to_h)
+        else value
+        end
+      end
+
+      # @api private
+      def deep_copy(value)
+        case value
+        when Hash then value.to_h { |key, item| [key, deep_copy(item)] }
+        when Array then value.map { |item| deep_copy(item) }
+        when String then value.dup
+        else value
+        end
+      end
+
+      # @api private
+      def mask_secrets(value)
+        case value
+        when Hash
+          value.to_h do |key, item|
+            [key, key == "secret" && item.is_a?(String) ? FlightByte.mask_secret(item) : mask_secrets(item)]
+          end
+        when Array then value.map { |item| mask_secrets(item) }
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/flightbyte/rate_limit.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module FlightByte
+  # One quota window, from the `X-RateLimit-*` response headers.
+  #
+  # @!attribute [r] limit
+  #   @return [Integer] Requests the window allows.
+  # @!attribute [r] remaining
+  #   @return [Integer] Requests left in the window.
+  # @!attribute [r] reset_at
+  #   @return [Time, nil] When the window resets, in UTC, or `nil` when not reported.
+  RateLimitWindow = Struct.new(:limit, :remaining, :reset_at, keyword_init: true)
+
+  # The quota state sent with a response, from {Client#last_rate_limit}. A
+  # window the key has no limit on is `nil`; keys without limits get no
+  # headers at all. Frozen, so it can be shared and never changes the client.
+  #
+  # @!attribute [r] minute
+  #   @return [RateLimitWindow, nil] The per-minute window.
+  # @!attribute [r] day
+  #   @return [RateLimitWindow, nil] The per-day window.
+  # @!attribute [r] month
+  #   @return [RateLimitWindow, nil] The per-month window.
+  RateLimit = Struct.new(:minute, :day, :month, keyword_init: true) do
+    # @api private
+    # Reads the quota headers (lower-case names), or returns `nil` when there are none.
+    def self.parse(headers)
+      windows = %w[minute day month].to_h { |name| [name.to_sym, parse_window(headers, name)] }
+      return nil if windows.values.none?
+
+      new(**windows).freeze
+    end
+
+    # @api private
+    def self.parse_window(headers, name)
+      limit = parse_integer(headers["x-ratelimit-limit-#{name}"])
+      remaining = parse_integer(headers["x-ratelimit-remaining-#{name}"])
+      return nil if limit.nil? || remaining.nil?
+
+      reset = parse_integer(headers["x-ratelimit-reset-#{name}"])
+      reset_at = reset && Time.at(reset).utc.freeze
+      RateLimitWindow.new(limit: limit, remaining: remaining, reset_at: reset_at).freeze
+    end
+
+    # @api private
+    def self.parse_integer(value)
+      value = value.to_s.strip
+      value.match?(/\A\d+\z/) ? Integer(value, 10) : nil
+    end
+
+    private_class_method :parse_window, :parse_integer
+  end
+end

data/lib/flightbyte/resources/countries.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module FlightByte
+  # Country names, emoji and flags. Reach it as `client.countries`.
+  class Countries
+    # @api private
+    def initialize(transport)
+      @transport = transport
+    end
+
+    # Every country, sorted by name.
+    #
+    # @param lang [String, nil] the language of the names, for example `tr`; the API's default is `en`
+    # @param timeout [Numeric, nil] seconds for this request instead of the client's
+    # @return [Array<Country>]
+    def list(lang: nil, timeout: nil)
+      Country.list_from_response(@transport.request("GET", ["countries"], query: { lang: lang }, timeout: timeout))
+    end
+
+    # One country by its ISO 3166-1 alpha-2 code.
+    #
+    # @param code [String] for example `TR`
+    # @param (see #list)
+    # @return [Country]
+    # @raise [NotFoundError] when there is no such country
+    def get(code, lang: nil, timeout: nil)
+      path = ["countries", Transport.required("code", code)]
+      Country.from_response(@transport.request("GET", path, query: { lang: lang }, timeout: timeout))
+    end
+
+    # The URL of a country's SVG flag: 4:3, or 1:1 with `square: true`. Flags
+    # need no API key, so the URL can go straight into an `<img>`. Nothing is
+    # sent.
+    #
+    # @param code [String] for example `TR`
+    # @param square [Boolean]
+    # @return [String]
+    def flag_url(code, square: false)
+      @transport.url(["flags", "#{Transport.required("code", code).downcase}.svg"], { shape: square ? "1x1" : nil })
+    end
+
+    # Never shows the API key.
+    def inspect
+      "#<#{self.class.name}>"
+    end
+  end
+end

data/lib/flightbyte/resources/flights.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module FlightByte
+  # Flight lookups. Reach it as `client.flights`.
+  class Flights
+    # @api private
+    def initialize(transport)
+      @transport = transport
+    end
+
+    # Looks a flight up. The API upper-cases the carrier and strips leading
+    # zeros from the flight number.
+    #
+    # A flight number can fly several legs on one date. The snapshot lists them
+    # all in `alternates`; pass `origin:` (and optionally `destination:`) or a
+    # leg's `flight_id:` to choose one.
+    #
+    # @param carrier [String] IATA or ICAO carrier code, for example `TK`
+    # @param flight_number [String, Integer] flight number, for example `1848`
+    # @param date [String, Date, Time] local departure date at the origin, `YYYY-MM-DD`
+    # @param origin [String, nil] selects a leg by its origin IATA code
+    # @param destination [String, nil] narrows the leg further by its destination IATA code
+    # @param flight_id [String, nil] selects a leg by its upstream id, from `alternates`
+    # @param refresh [Boolean] skips the API's cache and asks upstream
+    # @param timeout [Numeric, nil] seconds for this request instead of the client's
+    # @return [FlightSnapshot]
+    # @raise [NotFoundError] when the flight did not operate that day
+    def get(carrier:, flight_number:, date:, origin: nil, destination: nil, flight_id: nil, refresh: false,
+            timeout: nil)
+      path = flight_path(carrier, flight_number, date)
+      query = { origin: origin, destination: destination, flightId: flight_id, refresh: refresh ? "true" : nil }
+      FlightSnapshot.from_response(@transport.request("GET", path, query: query, timeout: timeout))
+    end
+
+    # The flight's change history as recorded by the airline, newest first.
+    #
+    # @param (see #get)
+    # @return [FlightTimeline]
+    def timeline(carrier:, flight_number:, date:, origin: nil, destination: nil, timeout: nil)
+      path = [*flight_path(carrier, flight_number, date), "timeline"]
+      query = { origin: origin, destination: destination }
+      FlightTimeline.from_response(@transport.request("GET", path, query: query, timeout: timeout))
+    end
+
+    # Never shows the API key.
+    def inspect
+      "#<#{self.class.name}>"
+    end
+
+    private
+
+    def flight_path(carrier, flight_number, date)
+      [
+        "flights",
+        Transport.required("carrier", carrier),
+        Transport.required("flight_number", flight_number),
+        Transport.date("date", date)
+      ]
+    end
+  end
+end

data/lib/flightbyte/resources/subscriptions.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+module FlightByte
+  # Watched flights and their webhooks. Reach it as `client.subscriptions`.
+  # Every subscription is a billable watched flight.
+  class Subscriptions
+    # The page size {#list_all} asks for unless told otherwise: the API's largest.
+    DEFAULT_PAGE_SIZE = 200
+
+    # @api private
+    def initialize(transport)
+      @transport = transport
+    end
+
+    # Starts watching a flight. The API posts a signed webhook to
+    # `webhook_url` each time something about it changes.
+    #
+    # @param carrier [String] carrier code, for example `TK`
+    # @param flight_number [String, Integer] flight number, for example `1848`
+    # @param date [String, Date, Time] local departure date at the origin, `YYYY-MM-DD`
+    # @param webhook_url [String] where webhooks are posted; a public HTTPS URL
+    # @param origin [String, nil] selects a leg, when the flight number flies several that day
+    # @param destination [String, nil] narrows the leg further
+    # @param flight_id [String, nil] selects a leg by its upstream id
+    # @param secret [String, nil] the webhook signing secret. By default the API
+    #   generates one, returned once as `secret`. Setting the same secret on
+    #   every subscription lets one receiver verify them all.
+    # @param events [Array<String>, nil] change types that trigger a webhook; by default every type does
+    # @param delay_threshold_minutes [Integer, nil] ignore delay swings smaller than this, 1 to 240
+    # @param headers [Hash{String => String}, nil] extra headers sent with every delivery
+    # @param metadata [Hash{String => String}, nil] your own data, echoed back in every webhook
+    # @param idempotency_key [String, nil] makes retries safe: repeating the
+    #   request with the same key within 24 hours returns the original
+    #   subscription with `reused` true, instead of creating and billing a
+    #   second one. Sent as `Idempotency-Key`.
+    # @param timeout [Numeric, nil] seconds for this request instead of the client's
+    # @return [CreatedSubscription]
+    # @raise [PaymentRequiredError] when no watched flights are left
+    # @raise [BadRequestError] with `legs` set, when the flight number flies
+    #   several legs that day and neither `origin:` nor `flight_id:` chose one
+    def create(carrier:, flight_number:, date:, webhook_url:, origin: nil, destination: nil, flight_id: nil,
+               secret: nil, events: nil, delay_threshold_minutes: nil, headers: nil, metadata: nil,
+               idempotency_key: nil, timeout: nil)
+      body = {
+        "carrier" => Transport.required("carrier", carrier),
+        "flightNumber" => Transport.required("flight_number", flight_number),
+        "date" => Transport.date("date", date),
+        "webhookUrl" => Transport.required("webhook_url", webhook_url),
+        "origin" => origin,
+        "destination" => destination,
+        "flightId" => flight_id,
+        "secret" => secret,
+        "events" => events&.map(&:to_s),
+        "delayThresholdMinutes" => delay_threshold_minutes,
+        "headers" => headers,
+        "metadata" => metadata
+      }.compact
+      key = idempotency_key.to_s.strip
+      request_headers = key.empty? ? nil : { "idempotency-key" => key }
+      created = @transport.request("POST", ["subscriptions"], body: body, headers: request_headers, timeout: timeout)
+      if created.is_a?(Hash) && created["secret"].is_a?(String) && !created["secretHint"]
+        created = created.merge("secretHint" => FlightByte.mask_secret(created["secret"]))
+      end
+      CreatedSubscription.from_response(created)
+    end
+
+    # One page of your subscriptions, newest first.
+    #
+    # @param status [String, nil] keeps subscriptions in this status; see {SUBSCRIPTION_STATUSES}
+    # @param carrier [String, nil] keeps subscriptions for this carrier
+    # @param flight_number [String, Integer, nil] keeps subscriptions for this flight number
+    # @param date [String, Date, Time, nil] keeps subscriptions for this date
+    # @param limit [Integer, nil] page size; the API clamps it to 1 to 200 and defaults to 25
+    # @param offset [Integer, nil] the number of subscriptions to skip
+    # @param timeout [Numeric, nil] seconds for this request instead of the client's
+    # @return [SubscriptionPage]
+    def list(status: nil, carrier: nil, flight_number: nil, date: nil, limit: nil, offset: nil, timeout: nil)
+      date = FlightByte.format_date(date) if date.respond_to?(:strftime)
+      query = { status: status, carrier: carrier, flightNumber: flight_number, date: date, limit: limit,
+                offset: offset }
+      SubscriptionPage.from_response(@transport.request("GET", ["subscriptions"], query: query, timeout: timeout))
+    end
+
+    # Every subscription matching the filters, fetched page by page as you
+    # iterate. With a block it yields each one; without, it returns an
+    # Enumerator, so `first(10)`, `lazy` and `each_slice` fetch only the pages
+    # they need. Stop early with `break`; nothing more is fetched.
+    #
+    #   client.subscriptions.list_all(status: "active") do |subscription|
+    #     puts subscription.flight_key
+    #   end
+    #
+    # @param page_size [Integer] page size, 1 to 200
+    # @param (see #list)
+    # @yieldparam subscription [Subscription]
+    # @return [Enumerator<Subscription>, nil]
+    def list_all(status: nil, carrier: nil, flight_number: nil, date: nil, offset: nil,
+                 page_size: DEFAULT_PAGE_SIZE, timeout: nil, &block)
+      filters = { status: status, carrier: carrier, flight_number: flight_number, date: date, timeout: timeout }
+      pages = Enumerator.new { |yielder| paginate(filters, offset || 0, page_size) { |item| yielder << item } }
+      return pages unless block
+
+      pages.each(&block)
+      nil
+    end
+    alias each list_all
+
+    # One subscription.
+    #
+    # @param id [String]
+    # @param timeout [Numeric, nil] seconds for this request instead of the client's
+    # @return [Subscription]
+    # @raise [NotFoundError] when it does not exist or belongs to another key
+    def get(id, timeout: nil)
+      Subscription.from_response(@transport.request("GET", path(id), timeout: timeout))
+    end
+
+    # Changes a subscription. Only the fields you pass change. `headers` and
+    # `metadata` replace the existing maps; the API cannot clear them, so an
+    # empty map leaves them as they are.
+    #
+    # @param id [String]
+    # @param webhook_url [String, nil] moves deliveries to another URL
+    # @param events [Array<String>, nil] replaces the change type filter
+    # @param delay_threshold_minutes [Integer, nil] replaces the delay threshold
+    # @param headers [Hash{String => String}, nil] replaces the delivery headers
+    # @param metadata [Hash{String => String}, nil] replaces the metadata
+    # @param timeout [Numeric, nil] seconds for this request instead of the client's
+    # @return [Subscription]
+    def update(id, webhook_url: nil, events: nil, delay_threshold_minutes: nil, headers: nil, metadata: nil,
+               timeout: nil)
+      body = {
+        "webhookUrl" => webhook_url,
+        "events" => events&.map(&:to_s),
+        "delayThresholdMinutes" => delay_threshold_minutes,
+        "headers" => headers,
+        "metadata" => metadata
+      }.compact
+      Subscription.from_response(@transport.request("PATCH", path(id), body: body, timeout: timeout))
+    end
+
+    # Stops watching the flight and deletes the subscription for good.
+    #
+    # @param id [String]
+    # @param timeout [Numeric, nil] seconds for this request instead of the client's
+    # @return [nil]
+    def delete(id, timeout: nil)
+      @transport.request("DELETE", path(id), timeout: timeout)
+      nil
+    end
+
+    # Pauses polling and deliveries; {#resume} picks up where it left off.
+    #
+    # @param (see #get)
+    # @return [Subscription]
+    def pause(id, timeout: nil)
+      Subscription.from_response(@transport.request("POST", path(id, "pause"), timeout: timeout))
+    end
+
+    # Resumes a paused or suspended subscription. A completed one cannot be
+    # resumed and gives a {BadRequestError}.
+    #
+    # @param (see #get)
+    # @return [Subscription]
+    def resume(id, timeout: nil)
+      Subscription.from_response(@transport.request("POST", path(id, "resume"), timeout: timeout))
+    end
+
+    # Sends a signed `subscription.test` webhook to the subscription's URL.
+    #
+    # @param (see #get)
+    # @return [String] the event id
+    def send_test(id, timeout: nil)
+      field(@transport.request("POST", path(id, "test"), timeout: timeout), "eventId")
+    end
+
+    # The latest delivery attempts, newest first.
+    #
+    # @param id [String]
+    # @param limit [Integer, nil] how many to return, 1 to 100; the API's default is 25
+    # @param timeout [Numeric, nil] seconds for this request instead of the client's
+    # @return [Array<DeliveryRecord>]
+    def deliveries(id, limit: nil, timeout: nil)
+      response = @transport.request("GET", path(id, "deliveries"), query: { limit: limit }, timeout: timeout)
+      DeliveryRecord.list_from_response(response)
+    end
+
+    # The latest events, exactly as they were posted, newest first.
+    #
+    # @param (see #deliveries)
+    # @return [Array<WebhookEvent>]
+    def events(id, limit: nil, timeout: nil)
+      response = @transport.request("GET", path(id, "events"), query: { limit: limit }, timeout: timeout)
+      WebhookEvent.list_from_response(response)
+    end
+
+    # The full webhook signing secret.
+    #
+    # @param (see #get)
+    # @return [String]
+    def secret(id, timeout: nil)
+      field(@transport.request("GET", path(id, "secret"), timeout: timeout), "secret")
+    end
+
+    # Replaces the webhook signing secret and returns the new one. Deliveries
+    # are signed with it from now on, so update your receiver right away.
+    #
+    # @param (see #get)
+    # @return [String]
+    def rotate_secret(id, timeout: nil)
+      field(@transport.request("POST", path(id, "secret", "rotate"), timeout: timeout), "secret")
+    end
+
+    # Never shows the API key.
+    def inspect
+      "#<#{self.class.name}>"
+    end
+
+    private
+
+    def path(id, *rest)
+      ["subscriptions", Transport.required("id", id), *rest]
+    end
+
+    def paginate(filters, offset, page_size, &block)
+      loop do
+        page = list(**filters, limit: page_size, offset: offset)
+        items = page.data || []
+        items.each(&block)
+        following = (page.offset || offset) + items.length
+        break if items.empty? || !page.total.is_a?(Integer) || following >= page.total
+
+        offset = following
+      end
+    end
+
+    def field(response, key)
+      raise Error, "flightbyte: expected a JSON object with #{key} from the API" unless response.is_a?(Hash)
+
+      response[key]
+    end
+  end
+end