powo_ruby 0.1.0

data/lib/powo_ruby.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require_relative "powo_ruby/version"
+require_relative "powo_ruby/errors"
+require_relative "powo_ruby/validation"
+require_relative "powo_ruby/uri_utils"
+require_relative "powo_ruby/request"
+require_relative "powo_ruby/response"
+require_relative "powo_ruby/terms"
+require_relative "powo_ruby/configuration"
+require_relative "powo_ruby/client_resolver"
+require_relative "powo_ruby/paginator"
+require_relative "powo_ruby/resources/search"
+require_relative "powo_ruby/resources/taxa"
+require_relative "powo_ruby/client"
+
+# Unofficial, defensive Ruby client for Plants of the World Online (POWO).
+#
+# This gem exposes:
+# - module-level convenience clients (`PowoRuby.powo`, `PowoRuby.ipni`)
+# - a configurable `PowoRuby::Client` with endpoint wrappers (`#search`, `#taxa`)
+#
+# The underlying POWO API is undocumented and may change. This gem focuses on:
+# - validating parameters early
+# - providing cursor-based iteration helpers
+# - exposing errors with useful context (method/url/status/body)
+module PowoRuby
+  class << self
+    # Global configuration used by the convenience constructors.
+    #
+    # @return [PowoRuby::Configuration]
+    def config
+      @config ||= Configuration.new
+    end
+
+    # Configure the global `PowoRuby.config`.
+    #
+    # Calling this also resets any memoized per-thread convenience clients, so new calls
+    # to `PowoRuby.powo`/`PowoRuby.ipni` pick up the updated configuration.
+    #
+    # @yieldparam c [PowoRuby::Configuration]
+    # @return [PowoRuby::Configuration] the updated configuration
+    #
+    # @example
+    #   PowoRuby.configure do |c|
+    #     c.timeout = 10
+    #     c.cache = Rails.cache
+    #     c.cache_options = { expires_in: 60 }
+    #   end
+    def configure
+      yield(config)
+      reset_clients!
+      config
+    end
+
+    # Clears memoized convenience clients for the current thread.
+    #
+    # The convenience clients (`PowoRuby.powo`, `PowoRuby.ipni`) memoize a client per-thread
+    # to avoid re-parsing terms and rebuilding Faraday connections.
+    #
+    # @return [void]
+    def reset_clients!
+      Thread.current[:powo_ruby_default_powo_client] = nil
+      Thread.current[:powo_ruby_default_ipni_client] = nil
+    end
+
+    # Convenience constructor for a POWO-mode client.
+    #
+    # Uses a per-thread memoized client unless `config:` is provided.
+    #
+    # @param config [nil, Hash, PowoRuby::Configuration, PowoRuby::Client]
+    #   - `nil`: use memoized client
+    #   - `Hash`: override selected config keys for this call
+    #   - `PowoRuby::Configuration`: use exactly that configuration
+    #   - `PowoRuby::Client`: returned as-is
+    # @return [PowoRuby::Client]
+    #
+    # @example (default client)
+    #   client = PowoRuby.powo
+    #   client.search.query(query: "Acacia")
+    #
+    # @example (override for a single call)
+    #   client = PowoRuby.powo(config: { timeout: 2 })
+    def powo(config: nil)
+      ClientResolver.resolve(
+        Client,
+        config: config,
+        memo_key: :powo_ruby_default_powo_client,
+        default_overrides: { mode: :powo }
+      )
+    end
+
+    # Convenience constructor for an IPNI-mode client.
+    #
+    # This mode validates parameters against the IPNI allow-list (terms) but still calls
+    # the same underlying POWO `/search` and `/taxon/<id>` endpoints.
+    #
+    # @param config [nil, Hash, PowoRuby::Configuration, PowoRuby::Client] see {#powo}
+    # @return [PowoRuby::Client]
+    def ipni(config: nil)
+      ClientResolver.resolve(
+        Client,
+        config: config,
+        memo_key: :powo_ruby_default_ipni_client,
+        default_overrides: { mode: :ipni }
+      )
+    end
+  end
+end

data/sig/powo_ruby.rbs

@@ -0,0 +1,6 @@
+# Type definitions for `powo_ruby`
+
+module PowoRuby
+  VERSION: String
+end
+

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: powo_ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Reka Pap
+bindir: exe
+cert_chain: []
+date: 2026-02-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: A small, defensive, unofficial client for the undocumented POWO API.
+email:
+- rekapap28@gmail.com
+executables:
+- powo_ruby
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- docs/POWO_SEARCH_TERMS.md
+- exe/powo_ruby
+- lib/powo_ruby.rb
+- lib/powo_ruby/client.rb
+- lib/powo_ruby/client_resolver.rb
+- lib/powo_ruby/configuration.rb
+- lib/powo_ruby/errors.rb
+- lib/powo_ruby/paginator.rb
+- lib/powo_ruby/request.rb
+- lib/powo_ruby/request_support/cache_key_builder.rb
+- lib/powo_ruby/request_support/cache_store.rb
+- lib/powo_ruby/request_support/response_handler.rb
+- lib/powo_ruby/request_support/retry_policy.rb
+- lib/powo_ruby/resources/search.rb
+- lib/powo_ruby/resources/taxa.rb
+- lib/powo_ruby/response.rb
+- lib/powo_ruby/terms.rb
+- lib/powo_ruby/uri_utils.rb
+- lib/powo_ruby/validation.rb
+- lib/powo_ruby/version.rb
+- sig/powo_ruby.rbs
+homepage: https://github.com/rekapap/powo_ruby
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/rekapap/powo_ruby
+  changelog_uri: https://github.com/rekapap/powo_ruby/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.3
+specification_version: 4
+summary: Unofficial Ruby client for Kew POWO (Plants of the World Online) API
+test_files: []