phoebe 0.1.0.pre.alpha.1

data/lib/phoebe/models/ref/taxonomy/species_group_list_params.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Phoebe
+  module Models
+    module Ref
+      module Taxonomy
+        # @see Phoebe::Resources::Ref::Taxonomy::SpeciesGroups#list
+        class SpeciesGroupListParams < Phoebe::Internal::Type::BaseModel
+          extend Phoebe::Internal::Type::RequestParameters::Converter
+          include Phoebe::Internal::Type::RequestParameters
+
+          # @!attribute group_name_locale
+          #   Locale for species group names. English names are returned for any non-listed
+          #   locale or any non-translated group name.
+          #
+          #   @return [String, nil]
+          optional :group_name_locale, String
+
+          # @!method initialize(group_name_locale: nil, request_options: {})
+          #   Some parameter documentations has been truncated, see
+          #   {Phoebe::Models::Ref::Taxonomy::SpeciesGroupListParams} for more details.
+          #
+          #   @param group_name_locale [String] Locale for species group names. English names are returned for any non-listed lo
+          #
+          #   @param request_options [Phoebe::RequestOptions, Hash{Symbol=>Object}]
+
+          # The order in which groups are returned.
+          module SpeciesGrouping
+            extend Phoebe::Internal::Type::Enum
+
+            MERLIN = :merlin
+            EBIRD = :ebird
+
+            # @!method self.values
+            #   @return [Array<Symbol>]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phoebe/models/ref/taxonomy/species_group_list_response.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Phoebe
+  module Models
+    module Ref
+      module Taxonomy
+        class SpeciesGroupListResponseItem < Phoebe::Internal::Type::BaseModel
+          # @!attribute group_name
+          #
+          #   @return [String, nil]
+          optional :group_name, String, api_name: :groupName
+
+          # @!attribute group_order
+          #
+          #   @return [Integer, nil]
+          optional :group_order, Integer, api_name: :groupOrder
+
+          # @!attribute taxon_order_bounds
+          #
+          #   @return [Array<Array<Float>>, nil]
+          optional :taxon_order_bounds,
+                   Phoebe::Internal::Type::ArrayOf[Phoebe::Internal::Type::ArrayOf[Float]],
+                   api_name: :taxonOrderBounds
+
+          # @!method initialize(group_name: nil, group_order: nil, taxon_order_bounds: nil)
+          #   @param group_name [String]
+          #   @param group_order [Integer]
+          #   @param taxon_order_bounds [Array<Array<Float>>]
+        end
+
+        # @type [Phoebe::Internal::Type::Converter]
+        SpeciesGroupListResponse =
+          Phoebe::Internal::Type::ArrayOf[-> { Phoebe::Models::Ref::Taxonomy::SpeciesGroupListResponseItem }]
+      end
+    end
+  end
+end

data/lib/phoebe/models/ref/taxonomy/version_list_params.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Phoebe
+  module Models
+    module Ref
+      module Taxonomy
+        # @see Phoebe::Resources::Ref::Taxonomy::Versions#list
+        class VersionListParams < Phoebe::Internal::Type::BaseModel
+          extend Phoebe::Internal::Type::RequestParameters::Converter
+          include Phoebe::Internal::Type::RequestParameters
+
+          # @!method initialize(request_options: {})
+          #   @param request_options [Phoebe::RequestOptions, Hash{Symbol=>Object}]
+        end
+      end
+    end
+  end
+end

data/lib/phoebe/models/ref/taxonomy/version_list_response.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Phoebe
+  module Models
+    module Ref
+      module Taxonomy
+        class VersionListResponseItem < Phoebe::Internal::Type::BaseModel
+          # @!attribute authority_ver
+          #
+          #   @return [Float, nil]
+          optional :authority_ver, Float, api_name: :authorityVer
+
+          # @!attribute latest
+          #
+          #   @return [Boolean, nil]
+          optional :latest, Phoebe::Internal::Type::Boolean
+
+          # @!method initialize(authority_ver: nil, latest: nil)
+          #   @param authority_ver [Float]
+          #   @param latest [Boolean]
+        end
+
+        # @type [Phoebe::Internal::Type::Converter]
+        VersionListResponse =
+          Phoebe::Internal::Type::ArrayOf[-> { Phoebe::Models::Ref::Taxonomy::VersionListResponseItem }]
+      end
+    end
+  end
+end

data/lib/phoebe/models.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Phoebe
+  [Phoebe::Internal::Type::BaseModel, *Phoebe::Internal::Type::BaseModel.subclasses].each do |cls|
+    cls.define_sorbet_constant!(:OrHash) { T.type_alias { T.any(cls, Phoebe::Internal::AnyHash) } }
+  end
+
+  Phoebe::Internal::Util.walk_namespaces(Phoebe::Models).each do |mod|
+    case mod
+    in Phoebe::Internal::Type::Enum | Phoebe::Internal::Type::Union
+      mod.constants.each do |name|
+        case mod.const_get(name)
+        in true | false
+          mod.define_sorbet_constant!(:TaggedBoolean) { T.type_alias { T::Boolean } }
+          mod.define_sorbet_constant!(:OrBoolean) { T.type_alias { T::Boolean } }
+        in Integer
+          mod.define_sorbet_constant!(:TaggedInteger) { T.type_alias { Integer } }
+          mod.define_sorbet_constant!(:OrInteger) { T.type_alias { Integer } }
+        in Float
+          mod.define_sorbet_constant!(:TaggedFloat) { T.type_alias { Float } }
+          mod.define_sorbet_constant!(:OrFloat) { T.type_alias { Float } }
+        in Symbol
+          mod.define_sorbet_constant!(:TaggedSymbol) { T.type_alias { Symbol } }
+          mod.define_sorbet_constant!(:OrSymbol) { T.type_alias { T.any(Symbol, String) } }
+        else
+        end
+      end
+    else
+    end
+  end
+
+  Phoebe::Internal::Util.walk_namespaces(Phoebe::Models)
+                        .lazy
+                        .grep(Phoebe::Internal::Type::Union)
+                        .each do |mod|
+    const = :Variants
+    next if mod.sorbet_constant_defined?(const)
+
+    mod.define_sorbet_constant!(const) { T.type_alias { mod.to_sorbet_type } }
+  end
+
+  Data = Phoebe::Models::Data
+
+  Product = Phoebe::Models::Product
+
+  Ref = Phoebe::Models::Ref
+end

data/lib/phoebe/request_options.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Phoebe
+  # Specify HTTP behaviour to use for a specific request. These options supplement
+  # or override those provided at the client level.
+  #
+  # When making a request, you can pass an actual {RequestOptions} instance, or
+  # simply pass a Hash with symbol keys matching the attributes on this class.
+  class RequestOptions < Phoebe::Internal::Type::BaseModel
+    # @api private
+    #
+    # @param opts [Phoebe::RequestOptions, Hash{Symbol=>Object}]
+    #
+    # @raise [ArgumentError]
+    def self.validate!(opts)
+      case opts
+      in Phoebe::RequestOptions | Hash
+        opts.to_h.each_key do |k|
+          unless fields.include?(k)
+            raise ArgumentError.new("Request `opts` keys must be one of #{fields.keys}, got #{k.inspect}")
+          end
+        end
+      else
+        raise ArgumentError.new("Request `opts` must be a Hash or RequestOptions, got #{opts.inspect}")
+      end
+    end
+
+    # @!attribute idempotency_key
+    #   Idempotency key to send with request and all associated retries. Will only be
+    #   sent for write requests.
+    #
+    #   @return [String, nil]
+    optional :idempotency_key, String
+
+    # @!attribute extra_query
+    #   Extra query params to send with the request. These are `.merge`’d into any
+    #   `query` given at the client level.
+    #
+    #   @return [Hash{String=>Array<String>, String, nil}, nil]
+    optional :extra_query, Phoebe::Internal::Type::HashOf[Phoebe::Internal::Type::ArrayOf[String]]
+
+    # @!attribute extra_headers
+    #   Extra headers to send with the request. These are `.merged`’d into any
+    #   `extra_headers` given at the client level.
+    #
+    #   @return [Hash{String=>String, nil}, nil]
+    optional :extra_headers, Phoebe::Internal::Type::HashOf[String, nil?: true]
+
+    # @!attribute extra_body
+    #   Extra data to send with the request. These are deep merged into any data
+    #   generated as part of the normal request.
+    #
+    #   @return [Object, nil]
+    optional :extra_body, Phoebe::Internal::Type::HashOf[Phoebe::Internal::Type::Unknown]
+
+    # @!attribute max_retries
+    #   Maximum number of retries to attempt after a failed initial request.
+    #
+    #   @return [Integer, nil]
+    optional :max_retries, Integer
+
+    # @!attribute timeout
+    #   Request timeout in seconds.
+    #
+    #   @return [Float, nil]
+    optional :timeout, Float
+
+    # @!method initialize(values = {})
+    #   Returns a new instance of RequestOptions.
+    #
+    #   @param values [Hash{Symbol=>Object}]
+
+    define_sorbet_constant!(:OrHash) do
+      T.type_alias { T.any(Phoebe::RequestOptions, Phoebe::Internal::AnyHash) }
+    end
+  end
+end

data/lib/phoebe/resources/data/observations/geo/recent/notable.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Phoebe
+  module Resources
+    class Data
+      class Observations
+        class Geo
+          class Recent
+            class Notable
+              # Get the list of notable observations (up to 30 days ago) of birds seen at
+              # locations within a radius of up to 50 kilometers, from a given set of
+              # coordinates. Notable observations can be for locally or nationally rare species
+              # or are otherwise unusual, for example over-wintering birds in a species which is
+              # normally only a summer visitor.
+              #
+              # @overload list(lat:, lng:, back: nil, detail: nil, dist: nil, hotspot: nil, max_results: nil, spp_locale: nil, request_options: {})
+              #
+              # @param lat [Float]
+              #
+              # @param lng [Float]
+              #
+              # @param back [Integer] The number of days back to fetch observations.
+              #
+              # @param detail [Symbol, Phoebe::Models::Data::Observations::Geo::Recent::NotableListParams::Detail] Include a subset (simple), or all (full), of the fields available.
+              #
+              # @param dist [Integer] The search radius from the given position, in kilometers.
+              #
+              # @param hotspot [Boolean] Only fetch observations from hotspots
+              #
+              # @param max_results [Integer] Only fetch this number of observations
+              #
+              # @param spp_locale [String] Use this language for species common names
+              #
+              # @param request_options [Phoebe::RequestOptions, Hash{Symbol=>Object}, nil]
+              #
+              # @return [Array<Phoebe::Models::Data::Observation>]
+              #
+              # @see Phoebe::Models::Data::Observations::Geo::Recent::NotableListParams
+              def list(params)
+                parsed, options = Phoebe::Data::Observations::Geo::Recent::NotableListParams.dump_request(params)
+                @client.request(
+                  method: :get,
+                  path: "data/obs/geo/recent/notable",
+                  query: parsed.transform_keys(max_results: "maxResults", spp_locale: "sppLocale"),
+                  model: Phoebe::Internal::Type::ArrayOf[Phoebe::Data::Observation],
+                  options: options
+                )
+              end
+
+              # @api private
+              #
+              # @param client [Phoebe::Client]
+              def initialize(client:)
+                @client = client
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phoebe/resources/data/observations/geo/recent/species.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Phoebe
+  module Resources
+    class Data
+      class Observations
+        class Geo
+          class Recent
+            class Species
+              # Get all observations of a species, seen up to 30 days ago, at any location
+              # within a radius of up to 50 kilometers, from a given set of coordinates. Results
+              # include only the most recent observation from each location in the region
+              # specified.
+              #
+              # #### URL parameters
+              #
+              # | Name        | Description             |
+              # | ----------- | ----------------------- |
+              # | speciesCode | The eBird species code. |
+              #
+              # #### Notes
+              #
+              # The species code is typically a 6-letter code, e.g. horlar for Horned Lark. You
+              # can get complete set of species code from the GET eBird Taxonomy end-point.
+              #
+              # @overload list(species_code, lat:, lng:, back: nil, dist: nil, hotspot: nil, include_provisional: nil, max_results: nil, spp_locale: nil, request_options: {})
+              #
+              # @param species_code [String] The eBird species code.
+              #
+              # @param lat [Float]
+              #
+              # @param lng [Float]
+              #
+              # @param back [Integer] The number of days back to fetch observations.
+              #
+              # @param dist [Integer] The search radius from the given position, in kilometers.
+              #
+              # @param hotspot [Boolean] Only fetch observations from hotspots
+              #
+              # @param include_provisional [Boolean] Include observations which have not yet been reviewed.
+              #
+              # @param max_results [Integer] Only fetch this number of observations
+              #
+              # @param spp_locale [String] Use this language for species common names
+              #
+              # @param request_options [Phoebe::RequestOptions, Hash{Symbol=>Object}, nil]
+              #
+              # @return [Array<Phoebe::Models::Data::Observation>]
+              #
+              # @see Phoebe::Models::Data::Observations::Geo::Recent::SpecieListParams
+              def list(species_code, params)
+                parsed, options = Phoebe::Data::Observations::Geo::Recent::SpecieListParams.dump_request(params)
+                @client.request(
+                  method: :get,
+                  path: ["data/obs/geo/recent/%1$s", species_code],
+                  query: parsed.transform_keys(
+                    include_provisional: "includeProvisional",
+                    max_results: "maxResults",
+                    spp_locale: "sppLocale"
+                  ),
+                  model: Phoebe::Internal::Type::ArrayOf[Phoebe::Data::Observation],
+                  options: options
+                )
+              end
+
+              # @api private
+              #
+              # @param client [Phoebe::Client]
+              def initialize(client:)
+                @client = client
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phoebe/resources/data/observations/geo/recent.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Phoebe
+  module Resources
+    class Data
+      class Observations
+        class Geo
+          class Recent
+            # @return [Phoebe::Resources::Data::Observations::Geo::Recent::Species]
+            attr_reader :species
+
+            # @return [Phoebe::Resources::Data::Observations::Geo::Recent::Notable]
+            attr_reader :notable
+
+            # Get the list of recent observations (up to 30 days ago) of birds seen at
+            # locations within a radius of up to 50 kilometers, from a given set of
+            # coordinates. Results include only the most recent observation for each species
+            # in the region specified.
+            #
+            # @overload list(lat:, lng:, back: nil, cat: nil, dist: nil, hotspot: nil, include_provisional: nil, max_results: nil, sort: nil, spp_locale: nil, request_options: {})
+            #
+            # @param lat [Float]
+            #
+            # @param lng [Float]
+            #
+            # @param back [Integer] The number of days back to fetch observations.
+            #
+            # @param cat [Symbol, Phoebe::Models::Data::Observations::Geo::RecentListParams::Cat] Only fetch observations from these taxonomic categories
+            #
+            # @param dist [Integer] The search radius from the given position, in kilometers.
+            #
+            # @param hotspot [Boolean] Only fetch observations from hotspots
+            #
+            # @param include_provisional [Boolean] Include observations which have not yet been reviewed.
+            #
+            # @param max_results [Integer] Only fetch this number of observations
+            #
+            # @param sort [Symbol, Phoebe::Models::Data::Observations::Geo::RecentListParams::Sort] Sort observations by taxonomy or by date, most recent first.
+            #
+            # @param spp_locale [String] Use this language for species common names
+            #
+            # @param request_options [Phoebe::RequestOptions, Hash{Symbol=>Object}, nil]
+            #
+            # @return [Array<Phoebe::Models::Data::Observation>]
+            #
+            # @see Phoebe::Models::Data::Observations::Geo::RecentListParams
+            def list(params)
+              parsed, options = Phoebe::Data::Observations::Geo::RecentListParams.dump_request(params)
+              @client.request(
+                method: :get,
+                path: "data/obs/geo/recent",
+                query: parsed.transform_keys(
+                  include_provisional: "includeProvisional",
+                  max_results: "maxResults",
+                  spp_locale: "sppLocale"
+                ),
+                model: Phoebe::Internal::Type::ArrayOf[Phoebe::Data::Observation],
+                options: options
+              )
+            end
+
+            # @api private
+            #
+            # @param client [Phoebe::Client]
+            def initialize(client:)
+              @client = client
+              @species = Phoebe::Resources::Data::Observations::Geo::Recent::Species.new(client: client)
+              @notable = Phoebe::Resources::Data::Observations::Geo::Recent::Notable.new(client: client)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phoebe/resources/data/observations/geo.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Phoebe
+  module Resources
+    class Data
+      class Observations
+        class Geo
+          # @return [Phoebe::Resources::Data::Observations::Geo::Recent]
+          attr_reader :recent
+
+          # @api private
+          #
+          # @param client [Phoebe::Client]
+          def initialize(client:)
+            @client = client
+            @recent = Phoebe::Resources::Data::Observations::Geo::Recent.new(client: client)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phoebe/resources/data/observations/nearest/geo_species.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Phoebe
+  module Resources
+    class Data
+      class Observations
+        class Nearest
+          class GeoSpecies
+            # Find the nearest locations where a species has been seen recently. #### Notes
+            # The species code is typically a 6-letter code, e.g. barswa for Barn Swallow. You
+            # can get complete set of species code from the GET eBird Taxonomy end-point.
+            #
+            # @overload list(species_code, lat:, lng:, back: nil, dist: nil, hotspot: nil, include_provisional: nil, max_results: nil, spp_locale: nil, request_options: {})
+            #
+            # @param species_code [String] The eBird species code.
+            #
+            # @param lat [Float]
+            #
+            # @param lng [Float]
+            #
+            # @param back [Integer] The number of days back to fetch observations.
+            #
+            # @param dist [Integer] Only fetch observations within this distance of the provided lat/lng
+            #
+            # @param hotspot [Boolean] Only fetch observations from hotspots
+            #
+            # @param include_provisional [Boolean] Include observations which have not yet been reviewed.
+            #
+            # @param max_results [Integer] Only fetch up to this number of observations
+            #
+            # @param spp_locale [String] Use this language for species common names
+            #
+            # @param request_options [Phoebe::RequestOptions, Hash{Symbol=>Object}, nil]
+            #
+            # @return [Array<Phoebe::Models::Data::Observation>]
+            #
+            # @see Phoebe::Models::Data::Observations::Nearest::GeoSpecieListParams
+            def list(species_code, params)
+              parsed, options = Phoebe::Data::Observations::Nearest::GeoSpecieListParams.dump_request(params)
+              @client.request(
+                method: :get,
+                path: ["data/nearest/geo/recent/%1$s", species_code],
+                query: parsed.transform_keys(
+                  include_provisional: "includeProvisional",
+                  max_results: "maxResults",
+                  spp_locale: "sppLocale"
+                ),
+                model: Phoebe::Internal::Type::ArrayOf[Phoebe::Data::Observation],
+                options: options
+              )
+            end
+
+            # @api private
+            #
+            # @param client [Phoebe::Client]
+            def initialize(client:)
+              @client = client
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phoebe/resources/data/observations/nearest.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Phoebe
+  module Resources
+    class Data
+      class Observations
+        class Nearest
+          # @return [Phoebe::Resources::Data::Observations::Nearest::GeoSpecies]
+          attr_reader :geo_species
+
+          # @api private
+          #
+          # @param client [Phoebe::Client]
+          def initialize(client:)
+            @client = client
+            @geo_species = Phoebe::Resources::Data::Observations::Nearest::GeoSpecies.new(client: client)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phoebe/resources/data/observations/recent/historic.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Phoebe
+  module Resources
+    class Data
+      class Observations
+        class Recent
+          class Historic
+            # Get a list of all taxa seen in a country, region or location on a specific date,
+            # with the specific observations determined by the "rank" parameter (defaults to
+            # latest observation on the date).
+            #
+            # #### Notes Responses may be cached for 30 minutes
+            #
+            # @overload list(d, region_code:, y_:, m:, cat: nil, detail: nil, hotspot: nil, include_provisional: nil, max_results: nil, r: nil, rank: nil, spp_locale: nil, request_options: {})
+            #
+            # @param d [Integer] Path param:
+            #
+            # @param region_code [String] Path param: The country, subnational1, subnational2 or location code.
+            #
+            # @param y_ [Integer] Path param:
+            #
+            # @param m [Integer] Path param:
+            #
+            # @param cat [Symbol, Phoebe::Models::Data::Observations::Recent::HistoricListParams::Cat] Query param: Only fetch observations from these taxonomic categories
+            #
+            # @param detail [Symbol, Phoebe::Models::Data::Observations::Recent::HistoricListParams::Detail] Query param: Include a subset (simple), or all (full), of the fields available.
+            #
+            # @param hotspot [Boolean] Query param: Only fetch observations from hotspots
+            #
+            # @param include_provisional [Boolean] Query param: Include observations which have not yet been reviewed.
+            #
+            # @param max_results [Integer] Query param: Only fetch this number of observations
+            #
+            # @param r [Array<String>] Query param: Fetch observations from up to 50 locations
+            #
+            # @param rank [Symbol, Phoebe::Models::Data::Observations::Recent::HistoricListParams::Rank] Query param: Include latest observation of the day, or the first added
+            #
+            # @param spp_locale [String] Query param: Use this language for species common names
+            #
+            # @param request_options [Phoebe::RequestOptions, Hash{Symbol=>Object}, nil]
+            #
+            # @return [Array<Phoebe::Models::Data::Observation>]
+            #
+            # @see Phoebe::Models::Data::Observations::Recent::HistoricListParams
+            def list(d, params)
+              parsed, options = Phoebe::Data::Observations::Recent::HistoricListParams.dump_request(params)
+              region_code =
+                parsed.delete(:region_code) do
+                  raise ArgumentError.new("missing required path argument #{_1}")
+                end
+              y_ =
+                parsed.delete(:y_) do
+                  raise ArgumentError.new("missing required path argument #{_1}")
+                end
+              m =
+                parsed.delete(:m) do
+                  raise ArgumentError.new("missing required path argument #{_1}")
+                end
+              @client.request(
+                method: :get,
+                path: ["data/obs/%1$s/historic/%2$s/%3$s/%4$s", region_code, y_, m, d],
+                query: parsed.transform_keys(
+                  include_provisional: "includeProvisional",
+                  max_results: "maxResults",
+                  spp_locale: "sppLocale"
+                ),
+                model: Phoebe::Internal::Type::ArrayOf[Phoebe::Data::Observation],
+                options: options
+              )
+            end
+
+            # @api private
+            #
+            # @param client [Phoebe::Client]
+            def initialize(client:)
+              @client = client
+            end
+          end
+        end
+      end
+    end
+  end
+end