plazucchini 0.0.1

data/lib/plazucchini.rb

@@ -0,0 +1,569 @@
+# frozen_string_literal: true
+
+require "erb"
+require_relative "plazucchini/error"
+require_relative "plazucchini/version"
+require_relative "plazucchini/request"
+require "plazucchini/helpers/configuration"
+
+module Plazucchini
+  extend Configuration
+
+  define_setting :base_url, "http://api.plazi.org"
+  define_setting :mailto, ENV["PLAZI_API_EMAIL"]
+
+
+  # Authors Described Species
+  #   How many new species have been described in papers authored by the given author?
+  #
+  # @param author [String] The author (default: "Agosti, D")
+  # @param limit [nil, Integer] The optional result limit
+  # @param order_mode [nil, String] The optional sort order (ASC, DESC, nil)
+  # @param verbose [Boolean] Print headers to STDOUT
+  #
+  # @return [Array] An array with the authors' described species counts
+  def self.authors_described_species(author: nil, limit: nil, order_mode: nil, verbose: false)
+    endpoint = "/v1/Authors/DescribedSpecies"
+    Request.new(endpoint: endpoint, method: :get, format: :json, author:, limit: limit, order_mode: order_mode, verbose: verbose).perform
+  end
+
+
+  # Authors Material Type Citations
+  #   How many times the given taxon types appear in material citations?
+  #   NOTE: This endpoint is misplaced in the API - it queries by taxon, not author
+  #
+  # @param genus_epithet [String] The genus epithet (default: "Tyrannosaurus")
+  # @param species_epithet [String] The species epithet (default: "rex")
+  # @param limit [nil, Integer] The optional result limit
+  # @param order_mode [nil, String] The optional sort order (ASC, DESC, nil)
+  # @param verbose [Boolean] Print headers to STDOUT
+  #
+  # @return [Array] An array with material type citation counts
+  def self.authors_material_type_citations(genus_epithet: nil, species_epithet: nil, limit: nil, order_mode: nil, verbose: false)
+    endpoint = "/v1/Authors/MaterialTypeCitations"
+    Request.new(endpoint: endpoint, method: :get, format: :json, genus_epithet:, species_epithet:, limit: limit, order_mode: order_mode, verbose: verbose).perform
+  end
+
+
+  # Authors New Species
+  #   How many new species have been described by the given author?
+  #
+  # @param author [String] The author (required, default: "Malabarba")
+  # @param status [String] The taxonomic status (default: "sp. nov.")
+  # @param limit [nil, Integer] The optional result limit
+  # @param order_mode [nil, String] The optional sort order (ASC, DESC, nil)
+  # @param verbose [Boolean] Print headers to STDOUT
+  #
+  # @return [Array] An array with the authors' new species counts
+  def self.authors_new_species(author: nil, status: nil, limit: nil, order_mode: nil, verbose: false)
+    endpoint = "/v1/Authors/NewSpecies"
+    Request.new(endpoint: endpoint, method: :get, format: :json, author:, status:, limit: limit, order_mode: order_mode, verbose: verbose).perform
+  end
+
+
+  # Authors Publication Dates
+  #   When did the given author publish?
+  #
+  # @param author [String] The author (default: "Agosti, D")
+  # @param limit [nil, Integer] The optional result limit
+  # @param order_mode [nil, String] The optional sort order (ASC, DESC, nil)
+  # @param verbose [Boolean] Print headers to STDOUT
+  #
+  # @return [Array] An array with the authors' publication dates and counts
+  def self.authors_publication_dates(author: nil, limit: nil, order_mode: nil, verbose: false)
+    endpoint = "/v1/Authors/PublicationDate"
+    Request.new(endpoint: endpoint, method: :get, format: :json, author:, limit: limit, order_mode: order_mode, verbose: verbose).perform
+  end
+
+
+  # Authors Publication Journals
+  #   In which journals did the given author publish?
+  #
+  # @param author [String] The author (default: "Agosti, D")
+  # @param limit [nil, Integer] The optional result limit
+  # @param order_mode [nil, String] The optional sort order (ASC, DESC, nil)
+  # @param verbose [Boolean] Print headers to STDOUT
+  #
+  # @return [Array] An array with the authors' publication journals and counts
+  def self.authors_publication_journals(author: nil, limit: nil, order_mode: nil, verbose: false)
+    endpoint = "/v1/Authors/PublicationJournals"
+    Request.new(endpoint: endpoint, method: :get, format: :json, author:, limit: limit, order_mode: order_mode, verbose: verbose).perform
+  end
+
+
+  # Authors Publication Partners (Co-Authors)
+  #   With whom did the given author publish?
+  #
+  # @param author [String] The author (default: "Agosti, D")
+  # @param limit [nil, Integer] The optional result limit
+  # @param order_mode [nil, String] The optional sort order (ASC, DESC, nil)
+  # @param verbose [Boolean] Print headers to STDOUT
+  #
+  # @return [Array] An array with the authors' co-authors and collaboration counts
+  def self.authors_publication_partners(author: nil, limit: nil, order_mode: nil, verbose: false)
+    endpoint = "/v1/Authors/PublicationPartners"
+    Request.new(endpoint: endpoint, method: :get, format: :json, author:, limit: limit, order_mode: order_mode, verbose: verbose).perform
+  end
+
+
+  # Authors Specimen Locations
+  #   Where are the specimens collected by the given collector deposited?
+  #   NOTE: This endpoint is misplaced in the API - it queries by collector, not author
+  #
+  # @param collector [String] The collector (default: "Agosti")
+  # @param limit [nil, Integer] The optional result limit
+  # @param order_mode [nil, String] The optional sort order (ASC, DESC, nil)
+  # @param verbose [Boolean] Print headers to STDOUT
+  #
+  # @return [Array] An array with specimen deposit locations and counts
+  def self.authors_specimen_locations(collector: nil, limit: nil, order_mode: nil, verbose: false)
+    endpoint = "/v1/Authors/SpecimenLocation"
+    Request.new(endpoint: endpoint, method: :get, format: :json, collector:, limit: limit, order_mode: order_mode, verbose: verbose).perform
+  end
+
+
+  # Authors Treatment Count
+  #   How many treatments have been authored by the given author?
+  #
+  # @param author [String] The author (required, default: "Linnaeus")
+  # @param limit [nil, Integer] The optional result limit
+  # @param order_mode [nil, String] The optional sort order (ASC, DESC, nil)
+  # @param verbose [Boolean] Print headers to STDOUT
+  #
+  # @return [Array] An array with the authors' treatment counts
+  def self.authors_treatment_count(author: nil, limit: nil, order_mode: nil, verbose: false)
+    endpoint = "/v1/Authors/TreatmentCount"
+    Request.new(endpoint: endpoint, method: :get, format: :json, author:, limit: limit, order_mode: order_mode, verbose: verbose).perform
+  end
+
+
+  # Contributors Liberated Material Citations
+  #   How many material citations have been liberated by the given person?
+  #
+  # @param user [String] The user that made the contribution (default: "tatiana")
+  # @param limit [nil, Integer] The optional result limit
+  # @param order_mode [nil, String] The optional sort order (ASC, DESC, nil)
+  # @param verbose [Boolean] Print headers to STDOUT
+  #
+  # @return [Array] An array with the contributors' material citation counts
+  def self.contributors_material_citations(user: nil, limit: nil, order_mode: nil, verbose: false)
+    endpoint = "/v1/Contributors/LiberatedMaterialCitations"
+    Request.new(endpoint: endpoint, method: :get, format: :json, user:, limit: limit, order_mode: order_mode, verbose: verbose).perform
+  end
+
+
+  # Contributors Liberated Pages
+  #   How many pages have been liberated by the given person?
+  #
+  # @param user [String] The user that made the contribution (default: "tatiana")
+  # @param limit [nil, Integer] The optional result limit
+  # @param order_mode [nil, String] The optional sort order (ASC, DESC, nil)
+  # @param verbose [Boolean] Print headers to STDOUT
+  #
+  # @return [Array] An array with the contributors' page counts
+  def self.contributors_pages(user: nil, limit: nil, order_mode: nil, verbose: false)
+    endpoint = "/v1/Contributors/LiberatedPages"
+    Request.new(endpoint: endpoint, method: :get, format: :json, user:, limit: limit, order_mode: order_mode, verbose: verbose).perform
+  end
+
+
+  # Contributors Liberated Publications
+  #   How many publications have been liberated by the given person?
+  #
+  # @param user [String] The user that made the contribution (default: "tatiana")
+  # @param limit [nil, Integer] The optional result limit
+  # @param order_mode [nil, String] The optional sort order (ASC, DESC, nil)
+  # @param verbose [Boolean] Print headers to STDOUT
+  #
+  # @return [Array] An array with the contributors' publication counts
+  def self.contributors_publications(user: nil, limit: nil, order_mode: nil, verbose: false)
+    endpoint = "/v1/Contributors/LiberatedPublications"
+    Request.new(endpoint: endpoint, method: :get, format: :json, user:, limit: limit, order_mode: order_mode, verbose: verbose).perform
+  end
+
+
+  # Contributors Liberated Treatments
+  #   How many treatments have been liberated by the given person?
+  #
+  # @param user [String] The user that made the contribution (default: "tatiana")
+  # @param limit [nil, Integer] The optional result limit
+  # @param order_mode [nil, String] The optional sort order (ASC, DESC, nil)
+  # @param verbose [Boolean] Print headers to STDOUT
+  #
+  # @return [Array] An array with the contributors' treatment counts
+  def self.contributors_treatments(user: nil, limit: nil, order_mode: nil, verbose: false)
+    endpoint = "/v1/Contributors/LiberatedTreatments"
+    Request.new(endpoint: endpoint, method: :get, format: :json, user:, limit: limit, order_mode: order_mode, verbose: verbose).perform
+  end
+
+
+  # Institutions Cited Materials
+  #   How many publications cite materials deposited in the given institution?
+  #
+  # @param collection_code [String] The collection code (default: "MNHN")
+  # @param limit [nil, Integer] The optional result limit
+  # @param order_mode [nil, String] The optional sort order (ASC, DESC, nil)
+  # @param verbose [Boolean] Print headers to STDOUT
+  #
+  # @return [Array] An array with institutions' cited material counts
+  def self.institutions_cited_materials(collection_code: nil, limit: nil, order_mode: nil, verbose: false)
+    endpoint = "/v1/Institutions/CitedMaterials"
+    Request.new(endpoint: endpoint, method: :get, format: :json, collection_code:, limit: limit, order_mode: order_mode, verbose: verbose).perform
+  end
+
+
+  # Institutions Distribution Range
+  #   What is the range of distribution covered by the given institution?
+  #
+  # @param collection_code [String] The collection code (default: "MNHN")
+  # @param limit [nil, Integer] The optional result limit
+  # @param order_mode [nil, String] The optional sort order (ASC, DESC, nil)
+  # @param verbose [Boolean] Print headers to STDOUT
+  #
+  # @return [Array] An array with institutions' geographic distribution data
+  def self.institutions_distribution_range(collection_code: nil, limit: nil, order_mode: nil, verbose: false)
+    endpoint = "/v1/Institutions/DistributionRange"
+    Request.new(endpoint: endpoint, method: :get, format: :json, collection_code:, limit: limit, order_mode: order_mode, verbose: verbose).perform
+  end
+
+
+  # Institutions Journal Occurrences
+  #   In which journals is the data of the given institution published?
+  #   NOTE: The API endpoint is misspelled as "JournalOccurances"
+  #
+  # @param collection_code [String] The collection code (default: "MNHN")
+  # @param limit [nil, Integer] The optional result limit
+  # @param order_mode [nil, String] The optional sort order (ASC, DESC, nil)
+  # @param verbose [Boolean] Print headers to STDOUT
+  #
+  # @return [Array] An array with institutions' journal occurrence data
+  def self.institutions_journal_occurrences(collection_code: nil, limit: nil, order_mode: nil, verbose: false)
+    endpoint = "/v1/Institutions/JournalOccurances"  # API endpoint is misspelled
+    Request.new(endpoint: endpoint, method: :get, format: :json, collection_code:, limit: limit, order_mode: order_mode, verbose: verbose).perform
+  end
+
+
+  # Institutions Specimens Stored
+  #
+  # @param collection_code [String] The collection code (default: MNHN)
+  # @param limit [nil, Integer] The optional result limit
+  # @param order_mode [nil, String] The optional sort order (ASC, DESC, nil)
+  # @param verbose [Boolean] Print headers to STDOUT
+  #
+  # @return [Array] An array with institutions' specimens stored
+  def self.institutions_specimens_stored(collection_code: nil, limit: nil, order_mode: nil, verbose: false)
+    endpoint = "/v1/Institutions/SpecimenStored"
+    Request.new(endpoint: endpoint, method: :get, format: :json, collection_code:, limit: limit, order_mode: order_mode, verbose: verbose).perform
+  end
+
+
+  # Institutions Stored Types
+  #
+  # @param collection_code [String] The collection code (default: MNHN)
+  # @param limit [nil, Integer] The optional result limit
+  # @param order_mode [nil, String] The optional sort order (ASC, DESC, nil)
+  # @param verbose [Boolean] Print headers to STDOUT
+  #
+  # @return [Array] An array with institutions' stored types
+  def self.institutions_stored_types(collection_code: nil, limit: nil, order_mode: nil, verbose: false)
+    endpoint = "/v1/Institutions/StoredTypes"
+    Request.new(endpoint: endpoint, method: :get, format: :json, collection_code:, limit: limit, order_mode: order_mode, verbose: verbose).perform
+  end
+
+
+  # Journals Cited Collections
+  #
+  # @param journal [String] The journal name (default: Phytotaxa)
+  # @param limit [nil, Integer] The optional result limit
+  # @param order_mode [nil, String] The optional sort order (ASC, DESC, nil)
+  # @param verbose [Boolean] Print headers to STDOUT
+  #
+  # @return [Array] An array with journal cited collections
+  def self.journals_cited_collections(journal: nil, limit: nil, order_mode: nil, verbose: false)
+    endpoint = "/v1/Journals/CitedCollections"
+    Request.new(endpoint: endpoint, method: :get, format: :json, journal:, limit: limit, order_mode: order_mode, verbose: verbose).perform
+  end
+
+
+  # Journals Published Figures Count
+  #
+  # @param journal [String] The journal name (default: Zootaxa)
+  # @param limit [nil, Integer] The optional result limit
+  # @param order_mode [nil, String] The optional sort order (ASC, DESC, nil)
+  # @param verbose [Boolean] Print headers to STDOUT
+  #
+  # @return [Array] An array with published figures counts
+  def self.journals_published_figures_count(journal: nil, limit: nil, order_mode: nil, verbose: false)
+    endpoint = "/v1/Journals/PublishedFiguresCount"
+    Request.new(endpoint: endpoint, method: :get, format: :json, journal:, limit: limit, order_mode: order_mode, verbose: verbose).perform
+  end
+
+
+  # Journals Published Material Distribution
+  #
+  # @param journal [String] The journal name (default: Phytotaxa)
+  # @param limit [nil, Integer] The optional result limit
+  # @param order_mode [nil, String] The optional sort order (ASC, DESC, nil)
+  # @param verbose [Boolean] Print headers to STDOUT
+  #
+  # @return [Array] An array with published material distribution counts
+  def self.journals_published_material_distribution(journal: nil, limit: nil, order_mode: nil, verbose: false)
+    endpoint = "/v1/Journals/PublishedMaterialDistribution"
+    Request.new(endpoint: endpoint, method: :get, format: :json, journal:, limit: limit, order_mode: order_mode, verbose: verbose).perform
+  end
+
+
+  # Journals Published New Species Count
+  #
+  # @param journal [String] The journal name
+  # @param limit [nil, Integer] The optional result limit
+  # @param order_mode [nil, String] The optional sort order (ASC, DESC, nil)
+  # @param verbose [Boolean] Print headers to STDOUT
+  #
+  # @return [Array] An array with published new species counts
+  def self.journals_published_new_species_count(journal: nil, limit: nil, order_mode: nil, verbose: false)
+    endpoint = "/v1/Journals/PublishedNewSpeciesCount"
+    Request.new(endpoint: endpoint, method: :get, format: :json, journal:, limit: limit, order_mode: order_mode, verbose: verbose).perform
+  end
+
+
+  # Journals Published Page Count
+  #
+  # @param journal [String] The journal name (default: )
+  # @param limit [nil, Integer] The optional result limit
+  # @param order_mode [nil, String] The optional sort order (ASC, DESC, nil)
+  # @param verbose [Boolean] Print headers to STDOUT
+  #
+  # @return [Array] An array with published page counts
+  def self.journals_published_page_count(journal: nil, limit: nil, order_mode: nil, verbose: false)
+    endpoint = "/v1/Journals/PublishedPageCount"
+    Request.new(endpoint: endpoint, method: :get, format: :json, journal:, limit: limit, order_mode: order_mode, verbose: verbose).perform
+  end
+
+
+  # Journals Published Synonyms Count
+  #
+  # @param journal [String] The journal name
+  # @param limit [nil, Integer] The optional result limit
+  # @param order_mode [nil, String] The optional sort order (ASC, DESC, nil)
+  # @param verbose [Boolean] Print headers to STDOUT
+  #
+  # @return [Array] An array with published synonyms counts
+  def self.journals_published_synonyms(journal: nil, limit: nil, order_mode: nil, verbose: false)
+    endpoint = "/v1/Journals/PublishedSynonyms"
+    Request.new(endpoint: endpoint, method: :get, format: :json, journal:, limit: limit, order_mode: order_mode, verbose: verbose).perform
+  end
+
+
+  # Journals Published Tables Count
+  #
+  # @param journal [String] The journal name
+  # @param limit [nil, Integer] The optional result limit
+  # @param order_mode [nil, String] The optional sort order (ASC, DESC, nil)
+  # @param verbose [Boolean] Print headers to STDOUT
+  #
+  # @return [Array] An array with published tables counts
+  def self.journals_published_tables(journal: nil, limit: nil, order_mode: nil, verbose: false)
+    endpoint = "/v1/Journals/PublishedTabels"  # endpoint is misspelled in the API
+    Request.new(endpoint: endpoint, method: :get, format: :json, journal:, limit: limit, order_mode: order_mode, verbose: verbose).perform
+  end
+
+
+  # Journals Published Treatment Count
+  #
+  # @param journal [String] The journal name
+  # @param limit [nil, Integer] The optional result limit
+  # @param order_mode [nil, String] The optional sort order (ASC, DESC, nil)
+  # @param verbose [Boolean] Print headers to STDOUT
+  #
+  # @return [Array] An array with published treatment counts
+  def self.journals_published_treatment_count(journal: nil, limit: nil, order_mode: nil, verbose: false)
+    endpoint = "/v1/Journals/PublishedTreatmentCount"
+    Request.new(endpoint: endpoint, method: :get, format: :json, journal:, limit: limit, order_mode: order_mode, verbose: verbose).perform
+  end
+
+
+  # Metrics Journal Data Count
+  #
+  # @param limit [nil, Integer] The optional result limit
+  # @param order_mode [nil, String] The optional sort order (ASC, DESC, nil)
+  # @param verbose [Boolean] Print headers to STDOUT
+  #
+  # @return [Array] An array with metrics data counts
+  def self.metrics_journal_data_count(limit: nil, order_mode: nil, verbose: false)
+    endpoint = "/v1/Metrics/JournalDataCount"
+    Request.new(endpoint: endpoint, method: :get, format: :json, limit: limit, order_mode: order_mode, verbose: verbose).perform
+  end
+
+  
+  # Metrics User Contribution Count
+  #
+  # @param limit [nil, Integer] The optional result limit
+  # @param order_mode [nil, String] The optional sort order (ASC, DESC, nil)
+  # @param verbose [Boolean] Print headers to STDOUT
+  #
+  # @return [Array] An array with metrics data counts
+  def self.metrics_user_contribution_count(limit: nil, order_mode: nil, verbose: false)
+    endpoint = "/v1/Metrics/UserContributionCount"
+    Request.new(endpoint: endpoint, method: :get, format: :json, limit: limit, order_mode: order_mode, verbose: verbose).perform
+  end
+
+
+  # Specimens With Genes
+  #   How many specimens are documented with gene sequences?
+  #   NOTE: This endpoint is misplaced in the API under Authors - it queries by genus, not author
+  #
+  # @param genus_epithet [String] The genus (required, default: "Exobasidium")
+  # @param limit [nil, Integer] The optional result limit
+  # @param order_mode [nil, String] The optional sort order (ASC, DESC, nil)
+  # @param verbose [Boolean] Print headers to STDOUT
+  #
+  # @return [Array] An array with specimens that have gene sequence data
+  def self.specimens_with_genes(genus_epithet: nil, limit: nil, order_mode: nil, verbose: false)
+    endpoint = "/v1/Authors/SpecimenWithGenes"  # API endpoint is misplaced under Authors
+    Request.new(endpoint: endpoint, method: :get, format: :json, genus_epithet:, limit: limit, order_mode: order_mode, verbose: verbose).perform
+  end
+
+
+  # Taxon Materials Citations
+  #
+  # @param genus_epithet [String] The genus of the treatment
+  # @param species_epithet [String] The species of the treatment
+  # @param limit [nil, Integer] The optional result limit
+  # @param order_mode [nil, String] The optional sort order (ASC, DESC, nil)
+  # @param verbose [Boolean] Print headers to STDOUT
+  #
+  # @return [Array] An array with taxon materials citations
+  def self.taxon_materials_citations(genus_epithet: nil, species_epithet: nil, limit: nil, order_mode: nil, verbose: false)
+    endpoint = "/v1/Taxon/MaterialCitations"
+    Request.new(endpoint: endpoint, method: :get, format: :json, genus_epithet: genus_epithet, species_epithet: species_epithet,
+                limit: limit, order_mode: order_mode, verbose: verbose).perform
+  end
+
+  # Taxon Occurrence By Material Citation
+  #   NOTE: The API endpoint is misspelled as "OccuranceByMaterialCitation"
+  #
+  # @param limit [nil, Integer] The optional result limit
+  # @param order_mode [nil, String] The optional sort order (ASC, DESC, nil)
+  # @param verbose [Boolean] Print headers to STDOUT
+  #
+  # @return [Array] An array with taxon occurrence by material citation results
+  def self.taxon_occurrence_by_materials_citation(limit: nil, order_mode: nil, verbose: false)
+    endpoint = "/v1/Taxon/OccuranceByMaterialCitation"  # API endpoint is misspelled
+    Request.new(endpoint: endpoint, method: :get, format: :json, limit: limit, order_mode: order_mode, verbose: verbose).perform
+  end
+
+  # Taxon Specimens In Collections
+  #
+  # @param genus_epithet [String] The genus of the treatment
+  # @param limit [nil, Integer] The optional result limit
+  # @param order_mode [nil, String] The optional sort order (ASC, DESC, nil)
+  # @param verbose [Boolean] Print headers to STDOUT
+  #
+  # @return [Array] An array of taxon specimens in collections
+  def self.taxon_specimens_in_collections(genus_epithet: nil, limit: nil, order_mode: nil, verbose: false)
+    endpoint = "/v1/Taxon/SpecimensInCollections"
+    Request.new(endpoint: endpoint, method: :get, format: :json, genus_epithet: genus_epithet, limit: limit, order_mode: order_mode, verbose: verbose).perform
+  end
+
+  # Taxon Treatments for taxon
+  #
+  # @param genus_epithet [String] The genus of the treatment
+  # @param species_epithet [String] The species of the treatment
+  # @param limit [nil, Integer] The optional result limit
+  # @param order_mode [nil, String] The optional sort order (ASC, DESC, nil)
+  # @param verbose [Boolean] Print headers to STDOUT
+  #
+  # @return [Array] An array of taxon treatments for taxon results
+  def self.taxon_treatments_for_taxon(genus_epithet: nil, species_epithet: nil, limit: nil, order_mode: nil, verbose: false)
+    endpoint = "/v1/Taxon/TreatmentsForTaxon"
+    Request.new(endpoint: endpoint, method: :get, format: :json, genus_epithet: genus_epithet, species_epithet: species_epithet,
+                limit: limit, order_mode: order_mode, verbose: verbose).perform
+  end
+
+
+  # Taxon Treatments With Keys
+  #   Find treatments that contain taxonomic keys for the given genus
+  #
+  # @param genus_epithet [String] The genus of the treatment
+  # @param limit [nil, Integer] The optional result limit
+  # @param order_mode [nil, String] The optional sort order (ASC, DESC, nil)
+  # @param verbose [Boolean] Print headers to STDOUT
+  #
+  # @return [Array] An array of treatments with taxonomic keys
+  def self.taxon_treatments_with_keys(genus_epithet: nil, limit: nil, order_mode: nil, verbose: false)
+    endpoint = "/v1/Taxon/TreatmentsWithKeys"
+    Request.new(endpoint: endpoint, method: :get, format: :json, genus_epithet: genus_epithet, limit: limit, order_mode: order_mode, verbose: verbose).perform
+  end
+
+
+  # Treatments Fetch
+  #   Fetch the full treatment document by UUID
+  #
+  # @param uuid [String] The UUID of the treatment to fetch (required)
+  # @param verbose [Boolean] Print headers to STDOUT
+  #
+  # @return [Hash] The full treatment data as a hash (converted from XML)
+  def self.treatments_fetch(uuid:, verbose: false)
+    endpoint = "/v1/Treatments/fetch"
+    Request.new(endpoint: endpoint, method: :get, format: :xml, uuid:, verbose: verbose).perform
+  end
+
+
+  # Search treatments
+  #   Search for treatments by taxonomic rank
+  #
+  # @param kingdom_epithet [nil, String] The kingdom to search (optional)
+  # @param phylum_epithet [nil, String] The phylum to search (optional)
+  # @param class_epithet [nil, String] The class to search (optional)
+  # @param order_epithet [nil, String] The order to search (optional)
+  # @param family_epithet [nil, String] The family to search (optional)
+  # @param genus_epithet [nil, String] The genus to search (optional)
+  # @param species_epithet [nil, String] The species to search (optional)
+  # @param limit [nil, Integer] The search result limit (optional)
+  # @param order_mode [nil, String] The optional sort order (ASC, DESC, nil)
+  # @param verbose [Boolean] Print headers to STDOUT
+  #
+  # @return [Array] An array of matching treatments
+  def self.treatments_search(kingdom_epithet: nil, phylum_epithet: nil, class_epithet: nil, order_epithet: nil, family_epithet: nil, genus_epithet: nil, species_epithet: nil, limit: nil, order_mode: nil, verbose: false)
+    endpoint = "/v1/Treatments/search"
+    Request.new(endpoint: endpoint, method: :get, format: :json, kingdom_epithet:, phylum_epithet:, class_epithet:, order_epithet:, family_epithet:, genus_epithet:, species_epithet:, limit:, order_mode:, verbose: verbose).perform
+  end
+
+
+  # Search treatments by DOI
+  #   Find treatments associated with the given DOI
+  #
+  # @param doi [String] The DOI to search for (required)
+  # @param verbose [Boolean] Print headers to STDOUT
+  #
+  # @return [Array] An array of matching treatments
+  def self.treatments_search_by_doi(doi:, verbose: false)
+    endpoint = "/v1/Treatments/searchByDOI"
+    Request.new(endpoint: endpoint, method: :get, format: :json, doi:, verbose: verbose).perform
+  end
+
+  # Get a treatment summary
+  #   Fetch a summary of the treatment by UUID
+  #
+  # @param uuid [String] The UUID of the treatment (required)
+  # @param verbose [Boolean] Print headers to STDOUT
+  #
+  # @return [Array] An array with the treatment summary data
+  def self.treatments_summary(uuid:, verbose: false)
+    endpoint = "/v1/Treatments/summary"
+    Request.new(endpoint: endpoint, method: :get, format: :json, uuid:, verbose: verbose).perform
+  end
+
+  # Ping the API (check if the service is alive)                                                                                                                                                                                                             
+  #                                                                                                                                                                                                                                                          
+  # @param verbose [Boolean] Print headers to STDOUT                                                                                                                                                                                                         
+  #                                                                                                                                                                                                                                                          
+  # @return [Hash] Returns {"pong" => true} if the API is reachable                                                                                                                                                                                                  
+  # @raise [Plazucchini::Error] If the API is not reachable                                                                                                                                                                                                  
+  def self.ping(verbose: false)                                                                                                                                                                                                                              
+    endpoint = "/v1/Metrics/JournalDataCount"                                                                                                                                                                                                                
+    Request.new(endpoint: endpoint, method: :get, format: :json, limit: 1, verbose: verbose).perform                                                                                                                                                         
+    {"pong" => true}                                                                                                                                                                                                                                                   
+  end     
+end

data/plazucchini.gemspec

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "lib/plazucchini/version"
+
+Gem::Specification.new do |s|
+  s.name          = "plazucchini"
+  s.version       = Plazucchini::VERSION
+  s.authors       = ["Geoff Ower"]
+  s.email         = ["gdower@illinois.edu"]
+
+  s.summary       = "Plazi TreatmentBank API Client"
+  s.description   = "plazucchini is a low-level wrapper around the Plazi TreatmentBank API."
+  s.homepage      = "https://github.com/SpeciesFileGroup/plazucchini"
+  s.license       = "MIT"
+  s.required_ruby_version = ">= 2.5.0"
+
+  s.metadata["homepage_uri"] = s.homepage
+  s.metadata["source_code_uri"] = "https://github.com/SpeciesFileGroup/plazucchini"
+  s.metadata["changelog_uri"] = "https://github.com/SpeciesFileGroup/plazucchini/releases/tag/v#{s.version}"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  s.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|s|features)/}) }
+  end
+  s.bindir        = "exe"
+  s.executables   = s.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_development_dependency "bundler", "~> 2.1", ">= 2.1.4"
+  s.add_development_dependency "rake", "~> 13.0", ">= 13.0.1"
+  s.add_development_dependency "test-unit", "~> 3.3", ">= 3.3.6"
+  s.add_development_dependency "vcr", "~> 6.0"
+  s.add_development_dependency "webmock", "~> 3.18"
+  s.add_development_dependency "rexml", "~> 3.3", ">= 3.3.6"
+
+  s.add_runtime_dependency "faraday", "~> 2.2"
+  s.add_runtime_dependency "faraday-follow_redirects", "~> 0.1"
+  s.add_runtime_dependency "multi_json", "~> 1.15"
+  s.add_runtime_dependency "nokogiri", "~> 1.16"
+end