powo_ruby 0.1.0

data/lib/powo_ruby/client.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module PowoRuby
+  # Main POWO client.
+  #
+  # Public API is endpoint-oriented (e.g. `client.search.query`, `client.taxa.lookup`).
+  #
+  # In most cases you won't instantiate this directly; prefer `PowoRuby.powo` / `PowoRuby.ipni`.
+  #
+  # @example
+  #   client = PowoRuby.powo
+  #   response = client.search.query(query: "Acacia", filters: { accepted: true })
+  #   response.results.first #=> Hash
+  class Client
+    OPTION_KEYS =
+      %i[
+        base_url
+        timeout
+        open_timeout
+        max_retries
+        retries
+        logger
+        cache
+        cache_options
+        cache_namespace
+        user_agent
+        terms_path
+      ].freeze
+
+    # Create a client instance.
+    #
+    # @param mode [Symbol, String] `:powo` or `:ipni` (controls allowed params and grouping)
+    # @param options [Hash, nil] base option hash (usually from {PowoRuby::Configuration#client_kwargs})
+    # @param overrides [Hash] per-instance overrides merged into options
+    #
+    # Supported keys are listed in `OPTION_KEYS`. Unknown keys raise `ArgumentError`.
+    #
+    # @return [PowoRuby::Client]
+    def initialize(
+      mode: :powo,
+      options: nil,
+      **overrides
+    )
+      @mode = mode.to_sym
+      opts = merge_options(options, overrides)
+      @terms = Terms.load(opts.fetch(:terms_path))
+
+      @request = Request.new(
+        user_agent: opts.fetch(:user_agent),
+        base_url: opts.fetch(:base_url),
+        timeout: opts.fetch(:timeout),
+        open_timeout: opts.fetch(:open_timeout),
+        max_retries: opts.fetch(:max_retries),
+        retries: opts.fetch(:retries),
+        logger: opts.fetch(:logger),
+        cache: opts.fetch(:cache),
+        cache_options: opts.fetch(:cache_options),
+        cache_namespace: opts.fetch(:cache_namespace)
+      )
+    end
+
+    # Access the `/search` endpoint wrapper.
+    #
+    # @return [PowoRuby::Resources::Search]
+    def search
+      @search ||= Resources::Search.new(request: request, allowed_params: allowed_params, group_keys: group_keys)
+    end
+
+    # Access the `/taxon/<id>` endpoint wrapper.
+    #
+    # @return [PowoRuby::Resources::Taxa]
+    def taxa
+      @taxa ||= Resources::Taxa.new(request: request)
+    end
+
+    private
+
+    attr_reader :request, :terms
+
+    def merge_options(options, overrides)
+      base = PowoRuby.config.client_kwargs
+      merged = base.merge(normalize_options_hash(options)).merge(normalize_options_hash(overrides))
+      unknown = merged.keys - OPTION_KEYS
+      raise ArgumentError, "Unknown client option keys: #{unknown.inspect}" unless unknown.empty?
+
+      merged
+    end
+
+    def normalize_options_hash(hash)
+      return {} if hash.nil?
+      raise ArgumentError, "options must be a Hash" unless hash.is_a?(Hash)
+
+      hash.each_with_object({}) do |(k, v), out|
+        key = k.is_a?(String) || k.is_a?(Symbol) ? k.to_sym : k
+        out[key] = v
+      end
+    end
+
+    def allowed_params
+      case @mode
+      when :powo
+        terms.powo_allowed_params
+      when :ipni
+        terms.ipni_allowed_params
+      else
+        raise ArgumentError, "Unknown client mode: #{@mode.inspect} (expected :powo or :ipni)"
+      end
+    end
+
+    def group_keys
+      case @mode
+      when :powo
+        %i[name characteristic geography]
+      when :ipni
+        %i[name author publication]
+      else
+        raise ArgumentError, "Unknown client mode: #{@mode.inspect} (expected :powo or :ipni)"
+      end
+    end
+  end
+end

data/lib/powo_ruby/client_resolver.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module PowoRuby
+  # Resolves a client instance for the module-level API.
+  #
+  # `config` may be:
+  # - nil (use the default, memoized client)
+  # - Hash (merge into defaults for this call)
+  # - PowoRuby::Configuration
+  # - a client instance of the requested klass
+  class ClientResolver
+    # Resolve a client instance based on the `config` argument.
+    #
+    # @param klass [Class] client class to construct (usually {PowoRuby::Client})
+    # @param config [nil, Hash, PowoRuby::Configuration, Object] see class docstring
+    # @param memo_key [Symbol] thread-local key used for memoization when config is nil
+    # @param default_overrides [Hash] overrides always applied when building new instances
+    # @return [Object] instance of `klass`
+    def self.resolve(klass, config:, memo_key:, default_overrides: {})
+      case config
+      when klass
+        config
+      when Hash
+        klass.new(options: PowoRuby.config.with(config).client_kwargs, **default_overrides)
+      when Configuration
+        klass.new(options: config.client_kwargs, **default_overrides)
+      when nil
+        Thread.current[memo_key] ||= klass.new(
+          options: PowoRuby.config.client_kwargs,
+          **default_overrides
+        )
+      else
+        raise ArgumentError, "config must be nil, a Hash, PowoRuby::Configuration, or #{klass}"
+      end
+    end
+  end
+end

data/lib/powo_ruby/configuration.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module PowoRuby
+  # Global configuration for the convenience constructors (`PowoRuby.powo`, `PowoRuby.ipni`).
+  #
+  # Users can override defaults via:
+  #
+  #   PowoRuby.configure do |c|
+  #     c.base_url = "..."
+  #     c.timeout = 5
+  #   end
+  #
+  class Configuration
+    attr_accessor :base_url, :timeout, :open_timeout, :max_retries, :retries, :logger,
+                  :cache, :cache_options, :cache_namespace,
+                  :user_agent, :terms_path
+
+    def initialize
+      @base_url = "https://powo.science.kew.org/api/2"
+      @timeout = 10
+      @open_timeout = 5
+      @max_retries = 3
+
+      @retries = true
+      @logger = nil
+      @cache = nil
+      @cache_options = {}
+      @cache_namespace = nil
+      @user_agent = "powo_ruby/#{PowoRuby::VERSION}"
+      @terms_path = File.expand_path("../../../docs/POWO_SEARCH_TERMS.md", __dir__)
+    end
+
+    # Keyword arguments used to build a {PowoRuby::Client}/{PowoRuby::Request}.
+    #
+    # @return [Hash] normalized options hash suitable for `Client.new(options: ...)`
+    def client_kwargs
+      {
+        base_url: base_url,
+        timeout: timeout,
+        open_timeout: open_timeout,
+        max_retries: max_retries,
+        retries: retries,
+        logger: logger,
+        cache: cache,
+        cache_options: cache_options,
+        cache_namespace: cache_namespace,
+        user_agent: user_agent,
+        terms_path: terms_path
+      }
+    end
+
+    # Returns a copy of this configuration with selected overrides applied.
+    #
+    # This is used internally when `PowoRuby.powo(config: { ... })` is called.
+    #
+    # @param overrides [Hash{Symbol,String => Object}]
+    # @return [PowoRuby::Configuration]
+    def with(overrides)
+      dup.tap do |copy|
+        overrides.each do |k, v|
+          writer = "#{k}="
+          raise ArgumentError, "Unknown configuration key: #{k.inspect}" unless copy.respond_to?(writer)
+
+          copy.public_send(writer, v)
+        end
+      end
+    end
+  end
+end

data/lib/powo_ruby/errors.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module PowoRuby
+  # Base error class for this gem.
+  class Error < StandardError; end
+
+  # Raised when configuration is invalid or incomplete.
+  class ConfigurationError < Error; end
+
+  # Raised when user input fails validation (e.g. missing query, wrong type).
+  class ValidationError < Error; end
+
+  # Raised when an HTTP request fails or cannot be processed.
+  #
+  # Most request errors include contextual fields like HTTP status, URL and response body.
+  class RequestError < Error
+    attr_reader :status, :method, :url, :body, :headers
+
+    # @param message [String]
+    # @param status [Integer, nil] HTTP status code
+    # @param method [Symbol, String, nil] HTTP method (e.g. `:get`)
+    # @param url [String, nil] full URL requested
+    # @param body [Object, nil] response body (may be a String or parsed JSON)
+    # @param headers [Hash, nil] response headers
+    def initialize(message, status: nil, method: nil, url: nil, body: nil, headers: nil)
+      super(message)
+      @status = status
+      @method = method
+      @url = url
+      @body = body
+      @headers = headers
+    end
+  end
+
+  # Raised for 4xx responses (excluding 429).
+  class ClientError < RequestError; end
+
+  # Raised for HTTP 429 responses (rate limiting).
+  class RateLimitedError < RequestError; end
+
+  # Raised for 5xx responses.
+  class ServerError < RequestError; end
+
+  # Raised when the request times out.
+  class TimeoutError < RequestError; end
+
+  # Raised when Faraday cannot establish a connection.
+  class ConnectionFailedError < RequestError; end
+
+  # Raised when JSON parsing fails for a successful response.
+  class ParseError < RequestError; end
+end

data/lib/powo_ruby/paginator.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module PowoRuby
+  # Generic, Response-driven paginator for page-based APIs.
+  #
+  # POWO primarily uses cursor-based paging for search, but this utility exists as a
+  # reusable helper for any endpoints that return {PowoRuby::Response} objects with
+  # `#each` and `#next_page?`.
+  class Paginator
+    # Build an enumerator that fetches pages starting at `start_page`.
+    #
+    # The block must return a {PowoRuby::Response} (or any object responding to `#each`
+    # and `#next_page?`).
+    #
+    # @param start_page [Integer]
+    # @yieldparam page [Integer]
+    # @yieldreturn [#each,#next_page?]
+    # @return [Enumerator]
+    #
+    # @example
+    #   enum = PowoRuby::Paginator.enumerator do |page|
+    #     client.some_endpoint.page(page: page)
+    #   end
+    def self.enumerator(start_page: 1, &fetch_page)
+      raise ArgumentError, "block required" unless fetch_page
+
+      Enumerator.new do |y|
+        current_page = Integer(start_page)
+
+        loop do
+          response = fetch_page.call(current_page)
+          response.each { |row| y << row }
+
+          break unless response.next_page?
+
+          current_page += 1
+        end
+      end
+    end
+  end
+end

data/lib/powo_ruby/request.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "uri"
+
+require_relative "request_support/cache_key_builder"
+require_relative "request_support/cache_store"
+require_relative "request_support/response_handler"
+require_relative "request_support/retry_policy"
+
+module PowoRuby
+  # Central HTTP wrapper for POWO requests.
+  #
+  # Defensive by default:
+  # - timeouts
+  # - retries with exponential backoff for 429 and 5xx
+  # - JSON parsing with helpful errors
+  #
+  # This class is considered an internal building block; most users will interact with it
+  # indirectly via {PowoRuby::Client} and endpoint wrappers.
+  class Request
+    # @param user_agent [String] sent as the `User-Agent` header
+    # @param base_url [String] POWO API base, e.g. `https://powo.science.kew.org/api/2`
+    # @param timeout [Numeric] request timeout (seconds)
+    # @param open_timeout [Numeric] connection open timeout (seconds)
+    # @param max_retries [Integer] number of retries (not counting the first attempt)
+    # @param backoff_base [Numeric] base backoff seconds for retries
+    # @param backoff_max [Numeric] max backoff seconds for retries
+    # @param retries [Boolean] enable/disable retry behavior
+    # @param logger [#warn, nil] optional logger
+    # @param cache_kwargs [Hash] cache configuration
+    # @option cache_kwargs [#fetch, nil] :cache cache adapter (e.g. Rails.cache)
+    # @option cache_kwargs [Hash] :cache_options adapter options (e.g. `{ expires_in: 60 }`)
+    # @option cache_kwargs [String, nil] :cache_namespace namespace used in cache keys
+    def initialize(
+      user_agent:,
+      base_url:,
+      timeout:,
+      open_timeout:,
+      max_retries:,
+      backoff_base: 0.5,
+      backoff_max: 8.0,
+      retries: true,
+      logger: nil,
+      **cache_kwargs
+    )
+      raise ConfigurationError, "base_url must be provided" if base_url.to_s.strip.empty?
+      raise ConfigurationError, "user_agent must be provided" if user_agent.to_s.strip.empty?
+
+      allowed_cache_kwargs = %i[cache cache_options cache_namespace]
+      unknown_cache_kwargs = cache_kwargs.keys - allowed_cache_kwargs
+      unless unknown_cache_kwargs.empty?
+        raise ArgumentError, "Unknown Request cache kwargs: #{unknown_cache_kwargs.inspect}"
+      end
+
+      @base_url = base_url
+      @user_agent = user_agent
+      @timeout = timeout
+      @open_timeout = open_timeout
+      @max_retries = Integer(max_retries)
+      @backoff_base = Float(backoff_base)
+      @backoff_max = Float(backoff_max)
+      @retry_enabled = retries ? true : false
+      @logger = logger
+      @cache = cache_kwargs[:cache]
+      @cache_options = cache_kwargs[:cache_options] || {}
+      @cache_namespace = cache_kwargs[:cache_namespace]
+
+      @cache_store = RequestSupport::CacheStore.new(cache)
+      @cache_key_builder = RequestSupport::CacheKeyBuilder.new
+      @retry_policy =
+        RequestSupport::RetryPolicy.new(
+          enabled: @retry_enabled,
+          max_retries: @max_retries,
+          backoff_base: @backoff_base,
+          backoff_max: @backoff_max,
+          logger: @logger
+        )
+      @response_handler = RequestSupport::ResponseHandler.new
+    end
+
+    attr_reader :base_url, :user_agent, :timeout, :open_timeout, :max_retries, :backoff_base, :backoff_max,
+                :retry_enabled, :logger, :cache, :cache_options, :cache_namespace
+
+    # Convenience GET wrapper used by endpoints.
+    #
+    # @param path [String] endpoint path relative to the base URL (e.g. `"search"`)
+    # @param params [Hash] query string params
+    # @return [Hash, Array] parsed JSON response
+    def get(path, params: {})
+      request(:get, path, params: params)
+    end
+
+    private
+
+    # ... private helpers ...
+
+    def request(method, path, params:)
+      url = build_url(path)
+      cache_key =
+        @cache_key_builder.build(
+          method: method,
+          url: url,
+          params: params,
+          namespace: cache_namespace,
+          version: PowoRuby::VERSION
+        )
+
+      @cache_store.fetch(cache_key) do
+        @retry_policy.with_retry(method: method, url: url) do
+          response = connection.send(method) do |req|
+            req.url(path)
+            req.params.update(stringify_keys(params))
+            req.headers["Accept"] = "application/json"
+            req.headers["User-Agent"] = user_agent
+          end
+
+          @response_handler.handle(response, method: method, url: url)
+        end
+      end
+    rescue Faraday::TimeoutError => e
+      raise TimeoutError.new(e.message, method: method, url: url, body: nil)
+    rescue Faraday::ConnectionFailed => e
+      raise ConnectionFailedError.new(e.message, method: method, url: url, body: nil)
+    end
+
+    def connection
+      @connection ||= Faraday.new(url: base_url) do |conn|
+        conn.options.timeout = timeout
+        conn.options.open_timeout = open_timeout
+        conn.request :url_encoded
+        conn.adapter Faraday.default_adapter
+      end
+    end
+
+    def build_url(path)
+      URI.join(base_url.end_with?("/") ? base_url : "#{base_url}/", path.sub(%r{\A/+}, "")).to_s
+    end
+
+    def stringify_keys(hash)
+      return {} if hash.nil?
+
+      hash.transform_keys(&:to_s)
+    end
+  end
+end

data/lib/powo_ruby/request_support/cache_key_builder.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module PowoRuby
+  module RequestSupport
+    # Builds a stable cache key for a request.
+    #
+    # The goal is:
+    # - stable ordering (hash keys sorted)
+    # - support nested params (bracket notation)
+    # - repeat keys for arrays (k=v1&k=v2)
+    class CacheKeyBuilder
+      # Build a cache key string.
+      #
+      # @param method [Symbol, String]
+      # @param url [String] fully qualified URL (without query)
+      # @param params [Hash] query params
+      # @param namespace [String, nil] optional namespace included in the key
+      # @param version [String, nil] optional gem version included in the key
+      # @return [String]
+      def build(method:, url:, params:, namespace: nil, version: nil)
+        pairs = flatten_params(stringify_keys(params))
+        query = pairs.empty? ? "" : "?#{URI.encode_www_form(pairs)}"
+
+        prefix =
+          [
+            "powo_ruby",
+            (namespace.to_s.strip.empty? ? nil : "ns=#{namespace}"),
+            (version.to_s.strip.empty? ? nil : "v=#{version}")
+          ].compact.join(" ")
+
+        "#{prefix} #{method.to_s.upcase} #{url}#{query}"
+      end
+
+      private
+
+      # @param hash [Hash, nil]
+      # @return [Hash]
+      def stringify_keys(hash)
+        return {} if hash.nil?
+
+        hash.transform_keys(&:to_s)
+      end
+
+      # Produces a stable, URI-encodable list of [key, value] pairs.
+      # - Hash keys are sorted for stability.
+      # - Array values become repeated keys (k=v1&k=v2), preserving array order.
+      # - Nested hashes are supported using bracket notation: a[b]=1
+      #
+      # @param obj [Object]
+      # @param prefix [String, nil]
+      # @return [Array<Array(String, String)>]
+      def flatten_params(obj, prefix = nil)
+        case obj
+        when nil
+          []
+        when Hash
+          obj
+            .sort_by { |k, _| k.to_s }
+            .flat_map do |k, v|
+              key = prefix ? "#{prefix}[#{k}]" : k.to_s
+              flatten_params(v, key)
+            end
+        when Array
+          obj.flat_map do |v|
+            # If no prefix, we can't encode a value without a key.
+            next [] if prefix.nil?
+
+            flatten_params(v, prefix)
+          end
+        else
+          return [] if prefix.nil?
+
+          [[prefix.to_s, obj.to_s]]
+        end
+      end
+    end
+  end
+end

data/lib/powo_ruby/request_support/cache_store.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module PowoRuby
+  module RequestSupport
+    # Thin adapter around a user-provided cache object.
+    #
+    # Supports a range of adapters:
+    # - Rails cache (`fetch(key, options = nil) { ... }`)
+    # - minimal custom caches (`fetch(key) { ... }`)
+    #
+    # If `cache` does not respond to `fetch`, this acts like a no-op cache and always yields.
+    class CacheStore
+      # @param cache [Object] cache adapter
+      def initialize(cache)
+        @cache = cache
+      end
+
+      # Fetch a value from the cache (or compute it).
+      #
+      # @param key [String]
+      # @param options [Hash, nil] adapter-specific fetch options (e.g. TTL)
+      # @yieldreturn [Object]
+      # @return [Object]
+      def fetch(key, options = nil, &block)
+        return block.call unless @cache.respond_to?(:fetch)
+
+        return @cache.fetch(key, &block) if options.nil? || (options.respond_to?(:empty?) && options.empty?)
+
+        # Prefer passing options (e.g., ActiveSupport::Cache supports `fetch(key, options = nil) { ... }`),
+        # but fall back to a plain `fetch(key)` for minimal adapters.
+        @cache.fetch(key, options, &block)
+      rescue ArgumentError
+        @cache.fetch(key, &block)
+      end
+    end
+  end
+end

data/lib/powo_ruby/request_support/response_handler.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "../errors"
+
+module PowoRuby
+  module RequestSupport
+    # Translates an HTTP response into either parsed JSON or a rich error.
+    #
+    # POWO typically returns JSON bodies; this handler:
+    # - raises typed errors for 4xx/5xx/429
+    # - parses JSON for successful responses
+    class ResponseHandler
+      # Handle an HTTP response.
+      #
+      # @param response [#status,#body,#headers]
+      # @param method [Symbol, String]
+      # @param url [String]
+      # @return [Hash, Array]
+      def handle(response, method:, url:)
+        status = response.status.to_i
+        body = response.body
+        headers = response.headers
+
+        if status == 429
+          raise RateLimitedError.new(
+            "Rate limited by POWO (HTTP 429)",
+            status: status,
+            method: method,
+            url: url,
+            body: body,
+            headers: headers
+          )
+        end
+
+        if status >= 500
+          raise ServerError.new(
+            "POWO server error (HTTP #{status})",
+            status: status,
+            method: method,
+            url: url,
+            body: body,
+            headers: headers
+          )
+        end
+
+        if status >= 400
+          raise ClientError.new(
+            "POWO request failed (HTTP #{status})",
+            status: status,
+            method: method,
+            url: url,
+            body: body,
+            headers: headers
+          )
+        end
+
+        parse_json(body, method: method, url: url)
+      end
+
+      private
+
+      # Parse a JSON response body.
+      #
+      # @param body [String, Hash, Array, Object]
+      # @param method [Symbol, String]
+      # @param url [String]
+      # @return [Hash, Array, Object]
+      def parse_json(body, method:, url:)
+        return body if body.is_a?(Hash) || body.is_a?(Array)
+
+        text = body.to_s
+        return {} if text.strip.empty?
+
+        JSON.parse(text)
+      rescue JSON::ParserError => e
+        raise ParseError.new("Failed to parse JSON response: #{e.message}", method: method, url: url, body: body)
+      end
+    end
+  end
+end