powo_ruby 0.1.0

data/lib/powo_ruby/request_support/retry_policy.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+
+module PowoRuby
+  module RequestSupport
+    # Encapsulates retry behavior for HTTP calls.
+    #
+    # This is used by {PowoRuby::Request} to retry on:
+    # - {PowoRuby::RateLimitedError} (HTTP 429)
+    # - {PowoRuby::ServerError} (HTTP 5xx)
+    #
+    # Retries use exponential backoff with a small jitter and respect `Retry-After` when present.
+    class RetryPolicy
+      # @param enabled [Boolean] enable retry behavior
+      # @param max_retries [Integer] number of retries (not counting the first attempt)
+      # @param backoff_base [Numeric] base seconds for backoff
+      # @param backoff_max [Numeric] max seconds for backoff
+      # @param logger [#warn, nil] optional logger
+      def initialize(enabled:, max_retries:, backoff_base:, backoff_max:, logger: nil)
+        @enabled = enabled ? true : false
+        @max_retries = Integer(max_retries)
+        @backoff_base = Float(backoff_base)
+        @backoff_max = Float(backoff_max)
+        @logger = logger
+      end
+
+      # Execute a block with retry logic.
+      #
+      # @param method [Symbol, String]
+      # @param url [String]
+      # @yieldreturn [Object]
+      # @return [Object]
+      def with_retry(method:, url:)
+        attempt = 0
+        max_attempts = @max_retries + 1
+
+        begin
+          attempt += 1
+          yield
+        rescue RateLimitedError, ServerError => e
+          raise e unless @enabled
+          raise e if attempt >= max_attempts
+
+          sleep_seconds = retry_sleep_seconds(e, attempt: attempt)
+          warn_log(
+            "Retrying #{method.to_s.upcase} #{url} in #{format("%.2f", sleep_seconds)}s " \
+            "(attempt #{attempt}/#{max_attempts})"
+          )
+          sleep(sleep_seconds)
+          retry
+        end
+      end
+
+      private
+
+      def warn_log(message)
+        return unless @logger
+        return unless @logger.respond_to?(:warn)
+
+        @logger.warn(message)
+      end
+
+      def retry_sleep_seconds(error, attempt:)
+        header_seconds = retry_after_seconds(error)
+        return header_seconds if header_seconds
+
+        # Exponential backoff with small jitter.
+        exp = @backoff_base * (2**(attempt - 1))
+        jitter = rand * 0.25
+        [exp + jitter, @backoff_max].min
+      end
+
+      def retry_after_seconds(error)
+        return nil unless error.is_a?(RateLimitedError)
+
+        raw = error.headers && (error.headers["retry-after"] || error.headers["Retry-After"])
+        return nil if raw.to_s.strip.empty?
+
+        Float(raw)
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/powo_ruby/resources/search.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require_relative "../response"
+require_relative "../validation"
+
+module PowoRuby
+  module Resources
+    # Endpoint wrapper around POWO's `/search` resource.
+    #
+    # Responsibilities:
+    # - validate user input
+    # - shape/normalize params for the API
+    # - provide cursor-based enumerators
+    #
+    # This class is typically accessed via {PowoRuby::Client#search}.
+    class Search
+      DEFAULT_CURSOR = "*"
+      DEFAULT_PER_PAGE = 24
+
+      # @param request [PowoRuby::Request,#get] HTTP adapter used to call the API
+      # @param allowed_params [Set<Symbol>] allow-list of supported params for this mode
+      # @param group_keys [Array<Symbol>] keys that should be flattened when passed as grouped hashes
+      def initialize(request:, allowed_params:, group_keys:)
+        @request = request
+        @allowed_params = allowed_params
+        @group_keys = group_keys
+      end
+
+      # Perform a simple text search.
+      #
+      # @param query [String] the search query (mapped to `q`)
+      # @param filters [Hash] optional filter hash (validated against the allow-list)
+      # @param cursor [String] POWO cursor for pagination (default `*`)
+      # @param per_page [Integer] page size (mapped to `perPage`)
+      # @return [PowoRuby::Response]
+      #
+      # @example
+      #   response = client.search.query(query: "Acacia", filters: { accepted: true })
+      #   response.total_count
+      #   response.results
+      def query(query:, filters: {}, cursor: DEFAULT_CURSOR, per_page: DEFAULT_PER_PAGE)
+        Validation.presence!(query, name: "query")
+        reject_page!(filters)
+
+        params = normalize_filters(filters, name: "filters")
+        params["q"] = query.to_s
+        params["cursor"] = normalize_cursor(cursor)
+        params["perPage"] = Integer(per_page)
+
+        Response.new(request.get("search", params: params))
+      end
+
+      # Perform an "advanced" search using a structured hash of terms.
+      #
+      # Supports both flat and grouped forms; grouped keys are flattened based on `group_keys`.
+      #
+      # @param params_hash [Hash] query terms / filters
+      # @return [PowoRuby::Response]
+      #
+      # @example (flat)
+      #   client.search.advanced(family: "Fabaceae", accepted: true, limit: 24)
+      #
+      # @example (grouped)
+      #   client.search.advanced(
+      #     name: { genus: "Acacia", family: "Fabaceae" },
+      #     accepted: true
+      #   )
+      def advanced(params_hash)
+        Validation.hash!(params_hash, name: "params_hash")
+
+        flat = flatten_groups(params_hash)
+        reject_page!(flat)
+        params = normalize_filters(flat, name: "params_hash")
+
+        Response.new(request.get("search", params: params))
+      end
+
+      # Enumerate rows across cursor pages for a simple text search.
+      #
+      # @param query [String]
+      # @param filters [Hash]
+      # @param cursor [String]
+      # @param per_page [Integer]
+      # @return [Enumerator<Hash>]
+      #
+      # @example
+      #   client.search.each(query: "Acacia", filters: { accepted: true }).take(50)
+      def each(query:, filters: {}, cursor: DEFAULT_CURSOR, per_page: DEFAULT_PER_PAGE)
+        Enumerator.new do |y|
+          current_cursor = normalize_cursor(cursor)
+
+          loop do
+            response = self.query(query: query, filters: filters, cursor: current_cursor, per_page: per_page)
+            response.each { |row| y << row }
+
+            break unless response.next_page?
+
+            raw_cursor = response.raw.is_a?(Hash) ? (response.raw["cursor"] || response.raw[:cursor]) : nil
+            break if raw_cursor.to_s.strip.empty? || raw_cursor.to_s == DEFAULT_CURSOR
+
+            current_cursor = raw_cursor.to_s
+          end
+        end
+      end
+
+      # Enumerate rows across cursor pages for an advanced search.
+      #
+      # `limit` is treated as a page-size hint (mapped to `perPage`).
+      #
+      # @param params_hash [Hash]
+      # @return [Enumerator<Hash>]
+      def advanced_each(params_hash)
+        flat = flatten_groups(params_hash)
+        reject_page!(flat)
+
+        initial_cursor = flat.key?(:cursor) ? flat[:cursor].to_s : DEFAULT_CURSOR
+        per_page =
+          if flat.key?(:perPage)
+            Integer(flat[:perPage])
+          elsif flat.key?(:limit)
+            Integer(flat[:limit])
+          else
+            DEFAULT_PER_PAGE
+          end
+
+        Enumerator.new do |y|
+          current_cursor = initial_cursor.to_s.strip.empty? ? DEFAULT_CURSOR : initial_cursor.to_s
+          params_for_call = flat.dup
+          params_for_call.delete(:cursor)
+          params_for_call.delete(:perPage)
+
+          loop do
+            response = advanced(params_for_call.merge(cursor: current_cursor, limit: per_page))
+            response.each { |row| y << row }
+
+            break unless response.next_page?
+
+            raw_cursor = response.raw.is_a?(Hash) ? (response.raw["cursor"] || response.raw[:cursor]) : nil
+            break if raw_cursor.to_s.strip.empty? || raw_cursor.to_s == DEFAULT_CURSOR
+
+            current_cursor = raw_cursor.to_s
+          end
+        end
+      end
+
+      private
+
+      attr_reader :request, :allowed_params, :group_keys
+
+      def reject_page!(hashish)
+        return unless hashish.is_a?(Hash)
+        return unless hashish.key?(:page) || hashish.key?("page")
+
+        raise ArgumentError,
+              "POWO search no longer supports page-based pagination. Remove :page and use :cursor instead."
+      end
+
+      def normalize_cursor(cursor)
+        cursor.to_s.strip.empty? ? DEFAULT_CURSOR : cursor.to_s
+      end
+
+      def flatten_groups(hash)
+        Validation.hash!(hash, name: "params_hash")
+
+        flat = {}
+        hash.each do |key, value|
+          sym_key = key.is_a?(Symbol) ? key : key.to_s.to_sym
+          if group_keys.include?(sym_key)
+            Validation.hash!(value, name: sym_key.to_s)
+            value.each { |k, v| flat[k.to_sym] = v }
+          else
+            flat[sym_key] = value
+          end
+        end
+        flat
+      end
+
+      def normalize_filters(input_hash, name:)
+        Validation.hash!(input_hash, name: name)
+
+        unknown =
+          input_hash.keys
+                    .map { |k| k.is_a?(Symbol) ? k : k.to_s.to_sym }
+                    .reject { |k| allowed_params.include?(k) }
+        unless unknown.empty?
+          supported = allowed_params.to_a.sort.map(&:inspect).join(", ")
+          message =
+            "Unsupported parameter(s): #{unknown.map(&:inspect).join(", ")}. Supported: [#{supported}]"
+          raise ValidationError, message
+        end
+
+        normalized = {}
+        input_hash.each do |key, value|
+          sym_key = key.is_a?(Symbol) ? key : key.to_s.to_sym
+          next if value.nil?
+
+          case sym_key
+          when :limit
+            normalized["perPage"] = Integer(value)
+          when :images
+            Validation.boolean!(value, name: "images")
+            normalized["f"] = "has_images" if value
+          when :accepted
+            Validation.boolean!(value, name: "accepted")
+            normalized["accepted"] = value
+          when :page
+            normalized["page"] = Integer(value)
+          else
+            normalized[sym_key.to_s] = value
+          end
+        end
+
+        normalized
+      end
+    end
+  end
+end

data/lib/powo_ruby/resources/taxa.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "../response"
+require_relative "../uri_utils"
+require_relative "../validation"
+
+module PowoRuby
+  module Resources
+    # Endpoint wrapper around POWO's `/taxon/<id>` resource.
+    #
+    # This class is typically accessed via {PowoRuby::Client#taxa}.
+    class Taxa
+      # @param request [PowoRuby::Request,#get] HTTP adapter used to call the API
+      def initialize(request:)
+        @request = request
+      end
+
+      # Lookup a taxon (or IPNI record) by its identifier.
+      #
+      # The id is URL-escaped before being inserted into the path.
+      #
+      # @param id [String] POWO/IPNI identifier (often a URN/LSID)
+      # @return [PowoRuby::Response]
+      #
+      # @example
+      #   response = client.taxa.lookup("urn:lsid:ipni.org:names:30000618-2")
+      #   response.raw #=> Hash
+      def lookup(id)
+        Validation.presence!(id, name: "id")
+        taxon_id = URIUtils.escape_path_segment(id.to_s)
+
+        Response.new(@request.get("taxon/#{taxon_id}", params: {}))
+      end
+    end
+  end
+end

data/lib/powo_ruby/response.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module PowoRuby
+  # Schema-flexible wrapper for POWO JSON responses.
+  #
+  # For search-like responses this exposes `results`, `total_count`, and pagination helpers.
+  #
+  # Note: POWO's API schema is not formally documented; this class keeps parsing conservative.
+  class Response
+    include Enumerable
+
+    # @param raw [Hash, Array, Object] parsed JSON (or already-decoded object) from the API
+    def initialize(raw)
+      @raw = raw
+    end
+
+    attr_reader :raw
+
+    # Array of result rows for search-like responses.
+    #
+    # @return [Array<Hash>]
+    def results
+      if raw.is_a?(Hash)
+        value =
+          raw["results"] || raw[:results]
+      end
+
+      value.is_a?(Array) ? value : []
+    end
+
+    # Total result count when present.
+    #
+    # POWO sometimes returns different keys depending on the endpoint / mode.
+    #
+    # @return [Integer, nil]
+    def total_count
+      return nil unless raw.is_a?(Hash)
+
+      raw["totalResults"] || raw[:totalResults] || raw["total"] || raw[:total]
+    end
+
+    # Whether another page is available.
+    #
+    # Supports both styles:
+    # - page/totalPages (legacy/page-based)
+    # - cursor-based paging (POWO search)
+    #
+    # @return [Boolean]
+    def next_page?
+      return false unless raw.is_a?(Hash)
+
+      page = raw["page"] || raw[:page]
+      total_pages = raw["totalPages"] || raw[:totalPages] || raw["pages"] || raw[:pages]
+      cursor = raw["cursor"] || raw[:cursor]
+
+      if page && total_pages
+        page.to_i < total_pages.to_i
+      elsif cursor
+        cursor.to_s != "*" && !cursor.to_s.empty?
+      else
+        false
+      end
+    end
+
+    def each(&block)
+      return enum_for(:each) unless block
+
+      results.each(&block)
+    end
+  end
+end

data/lib/powo_ruby/terms.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "set"
+
+module PowoRuby
+  # Loads and exposes allow-lists of supported query parameters for POWO and IPNI.
+  #
+  # The allow-lists can be sourced from `docs/POWO_SEARCH_TERMS.md` (parsed at runtime) or,
+  # if that file can't be read, from built-in fallback lists.
+  class Terms
+    # Internal helper for allowed POWO/IPNI parameters.
+    POWO_NAME = %i[
+      full_name scientific_name genus species infraspecific family common_name author rank status
+    ].freeze
+    POWO_CHARACTERISTIC = %i[
+      summary appearance flower fruit leaf habit habitat use conservation
+    ].freeze
+    POWO_GEOGRAPHY = %i[
+      distribution native_distribution introduced_distribution region continent country
+    ].freeze
+    POWO_ADDITIONAL = %i[
+      accepted images page limit sort
+    ].freeze
+
+    IPNI_NAME = %i[
+      genus species infraspecific_rank infraspecific_name family publication_year full_name
+    ].freeze
+    IPNI_AUTHOR = %i[
+      author standard_form collaboration
+    ].freeze
+    IPNI_PUBLICATION = %i[
+      publication_title publication_year publication_place publisher
+    ].freeze
+
+    POWO_GROUP_HEADERS = {
+      "name terms" => :name,
+      "characteristic terms" => :characteristic,
+      "geography terms" => :geography,
+      "additional filters" => :additional
+    }.freeze
+
+    IPNI_GROUP_HEADERS = {
+      "name terms" => :name,
+      "author terms" => :author,
+      "publication terms" => :publication
+    }.freeze
+
+    # Load terms from a markdown file when possible, otherwise fall back to defaults.
+    #
+    # @param path [String] path to `POWO_SEARCH_TERMS.md`
+    # @return [PowoRuby::Terms]
+    def self.load(path)
+      parsed = parse_markdown(path)
+      parsed || new(source_path: path)
+    end
+
+    # Parse a terms markdown file.
+    #
+    # @param path [String]
+    # @return [PowoRuby::Terms, nil] nil if unreadable/empty
+    def self.parse_markdown(path)
+      return nil unless path && File.file?(path)
+
+      content = File.read(path)
+      return nil if content.strip.empty?
+
+      section = :powo
+      group = nil
+
+      powo = Hash.new { |h, k| h[k] = [] }
+      ipni = Hash.new { |h, k| h[k] = [] }
+
+      content.each_line do |line|
+        line = line.strip
+        next if line.empty?
+
+        if line == "# IPNI Search Terms"
+          section = :ipni
+          group = nil
+          next
+        end
+
+        if line.start_with?("## ")
+          header = line.delete_prefix("## ").downcase
+          group =
+            if section == :powo
+              POWO_GROUP_HEADERS[header]
+            else
+              IPNI_GROUP_HEADERS[header]
+            end
+          next
+        end
+
+        next unless line.start_with?("- ")
+        next unless group
+
+        term = line.delete_prefix("- ").strip
+        term = term.split(/\s+/).first
+        next if term.nil? || term.empty?
+
+        sym = term.downcase.to_sym
+        if section == :powo
+          powo[group] << sym
+        else
+          ipni[group] << sym
+        end
+      end
+
+      new(
+        source_path: path,
+        powo: powo.transform_values { |v| v.uniq.freeze }.freeze,
+        ipni: ipni.transform_values { |v| v.uniq.freeze }.freeze
+      )
+    rescue Errno::ENOENT, Errno::EACCES
+      nil
+    end
+
+    def initialize(source_path:, powo: nil, ipni: nil)
+      @source_path = source_path
+      @powo = powo || {
+        name: POWO_NAME,
+        characteristic: POWO_CHARACTERISTIC,
+        geography: POWO_GEOGRAPHY,
+        additional: POWO_ADDITIONAL
+      }.freeze
+      @ipni = ipni || {
+        name: IPNI_NAME,
+        author: IPNI_AUTHOR,
+        publication: IPNI_PUBLICATION
+      }.freeze
+    end
+
+    attr_reader :source_path
+
+    # Allow-list of supported POWO params as symbols.
+    #
+    # @return [Set<Symbol>]
+    def powo_allowed_params
+      @powo.values.flatten.to_set
+    end
+
+    # Allow-list of supported IPNI params as symbols.
+    #
+    # @return [Set<Symbol>]
+    def ipni_allowed_params
+      @ipni.values.flatten.to_set
+    end
+  end
+end

data/lib/powo_ruby/uri_utils.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module PowoRuby
+  # Small URI helper utilities.
+  module URIUtils
+    module_function
+
+    # Escape a value for safe inclusion in a URL path segment.
+    #
+    # This is used for `/taxon/<id>` lookups, where IDs can include characters like `/` or `:`.
+    #
+    # @param value [String]
+    # @return [String]
+    def escape_path_segment(value)
+      URI::DEFAULT_PARSER.escape(value, /[^A-Za-z0-9\-._~]/)
+    end
+  end
+end

data/lib/powo_ruby/validation.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module PowoRuby
+  # Tiny validation helpers used by the public API.
+  #
+  # These are intentionally small and strict: they fail fast with {PowoRuby::ValidationError}
+  # to keep endpoint methods predictable for callers.
+  module Validation
+    module_function
+
+    # Validate that a value is present.
+    #
+    # @param value [Object]
+    # @param name [String] parameter name for error messages
+    # @return [void]
+    def presence!(value, name:)
+      return unless value.nil? || value.to_s.strip.empty?
+
+      raise ValidationError, "#{name} must be provided"
+    end
+
+    # Validate that a value is a Hash.
+    #
+    # @param value [Object]
+    # @param name [String]
+    # @return [void]
+    def hash!(value, name:)
+      return if value.is_a?(Hash)
+
+      raise ValidationError, "#{name} must be a Hash"
+    end
+
+    # Validate that a value is boolean (true/false).
+    #
+    # @param value [Object]
+    # @param name [String]
+    # @return [void]
+    def boolean!(value, name:)
+      return if [true, false].include?(value)
+
+      raise ValidationError, "#{name} must be boolean (true/false)"
+    end
+  end
+end

data/lib/powo_ruby/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module PowoRuby
+  # Gem version.
+  VERSION = "0.1.0"
+end