citedhealth 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d1412f03c7f37f1c6e05d1cf651bd2185e9fe0a3697793bb352387199f907acf
+  data.tar.gz: 3237403eebbb4a5710df421e9462e43353a9c9eb8f772f1b99617e08695aee36
+SHA512:
+  metadata.gz: 7fa44b8d9936beb53096330f88563dfcde9a17b4d45e8383da02ba4bd0e6ee937fbcade18f5eeae66d2989f7d9f7baec811c2850d7b88062265593648045ea1c
+  data.tar.gz: ded37c88e38fe195e3efe64a7e6383dbd10105621b1d6c68e8e915a41cfed52288caf78bd9441863e1e6526c001287a74aeaa4dc50284b69b1b215757ba8fc3c

data/lib/citedhealth/client.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module CitedHealth
+  # HTTP client for the Cited Health REST API.
+  #
+  # All methods return typed Ruby objects (Ingredient, Paper, EvidenceLink).
+  # Zero runtime dependencies — uses only Ruby stdlib (net/http, json, uri).
+  #
+  #   client = CitedHealth::Client.new
+  #   ingredient = client.get_ingredient("vitamin-d")
+  #   puts ingredient.name  # => "Vitamin D"
+  #
+  class Client
+    DEFAULT_BASE_URL = "https://citedhealth.com"
+    DEFAULT_TIMEOUT  = 30
+
+    def initialize(base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT)
+      @base_url = base_url.chomp("/")
+      @timeout = timeout
+    end
+
+    # Search ingredients by query and/or category.
+    #
+    # @param query [String] search term (default: "")
+    # @param category [String] filter by category (default: "")
+    # @return [Array<Ingredient>] list of matching ingredients
+    def search_ingredients(query: "", category: "")
+      params = {}
+      params[:q] = query unless query.empty?
+      params[:category] = category unless category.empty?
+
+      data = get("/api/ingredients/", params)
+      results = data["results"] || []
+      results.map { |h| Ingredient.from_hash(h) }
+    end
+
+    # Get a single ingredient by slug.
+    #
+    # @param slug [String] ingredient slug (e.g. "vitamin-d")
+    # @return [Ingredient]
+    # @raise [NotFoundError] if the ingredient does not exist
+    def get_ingredient(slug)
+      data = get("/api/ingredients/#{slug}/")
+      Ingredient.from_hash(data)
+    end
+
+    # Get evidence linking an ingredient to a condition.
+    #
+    # @param ingredient_slug [String] ingredient slug
+    # @param condition_slug [String] condition slug
+    # @return [EvidenceLink] the first matching evidence link
+    # @raise [NotFoundError] if no evidence exists for the pair
+    def get_evidence(ingredient_slug:, condition_slug:)
+      data = get("/api/evidence/", ingredient: ingredient_slug, condition: condition_slug)
+      results = data["results"] || []
+      raise NotFoundError, "No evidence found: #{ingredient_slug} × #{condition_slug}" if results.empty?
+
+      EvidenceLink.from_hash(results.first)
+    end
+
+    # Get a single evidence link by ID.
+    #
+    # @param id [Integer] evidence link ID
+    # @return [EvidenceLink]
+    # @raise [NotFoundError] if the evidence link does not exist
+    def get_evidence_by_id(id)
+      data = get("/api/evidence/#{id}/")
+      EvidenceLink.from_hash(data)
+    end
+
+    # Search research papers by query and/or publication year.
+    #
+    # @param query [String] search term (default: "")
+    # @param year [Integer, nil] filter by publication year
+    # @return [Array<Paper>] list of matching papers
+    def search_papers(query: "", year: nil)
+      params = {}
+      params[:q] = query unless query.empty?
+      params[:year] = year.to_s unless year.nil?
+
+      data = get("/api/papers/", params)
+      results = data["results"] || []
+      results.map { |h| Paper.from_hash(h) }
+    end
+
+    # Get a single paper by PubMed ID.
+    #
+    # @param pmid [String] PubMed ID
+    # @return [Paper]
+    # @raise [NotFoundError] if the paper does not exist
+    def get_paper(pmid)
+      data = get("/api/papers/#{pmid}/")
+      Paper.from_hash(data)
+    end
+
+    private
+
+    def get(path, params = {})
+      uri = URI("#{@base_url}#{path}")
+      uri.query = URI.encode_www_form(params) unless params.empty?
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @timeout
+      http.read_timeout = @timeout
+
+      request = Net::HTTP::Get.new(uri)
+      request["Accept"] = "application/json"
+      request["User-Agent"] = "citedhealth-rb/#{VERSION}"
+
+      response = http.request(request)
+
+      case response
+      when Net::HTTPSuccess
+        JSON.parse(response.body)
+      when Net::HTTPNotFound
+        raise NotFoundError, "Not found: #{path}"
+      when Net::HTTPTooManyRequests
+        retry_after = response["Retry-After"]&.to_i
+        raise RateLimitError.new("Rate limit exceeded", retry_after: retry_after)
+      else
+        raise Error, "HTTP #{response.code}: #{response.body}"
+      end
+    end
+  end
+end

data/lib/citedhealth/errors.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module CitedHealth
+  # General API error.
+  class Error < StandardError; end
+
+  # Raised when the server returns HTTP 404.
+  class NotFoundError < Error; end
+
+  # Raised when the server returns HTTP 429.
+  # Exposes the Retry-After header value when present.
+  class RateLimitError < Error
+    attr_reader :retry_after
+
+    def initialize(message = "Rate limit exceeded", retry_after: nil)
+      @retry_after = retry_after
+      super(message)
+    end
+  end
+end

data/lib/citedhealth/types.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module CitedHealth
+  # A health ingredient with dosage and form information.
+  class Ingredient
+    attr_reader :id, :name, :slug, :category, :mechanism,
+                :recommended_dosage, :forms, :is_featured
+
+    def initialize(id:, name:, slug:, category: "", mechanism: "",
+                   recommended_dosage: {}, forms: [], is_featured: false)
+      @id = id
+      @name = name
+      @slug = slug
+      @category = category
+      @mechanism = mechanism
+      @recommended_dosage = recommended_dosage
+      @forms = forms
+      @is_featured = is_featured
+    end
+
+    def self.from_hash(hash)
+      new(
+        id: hash["id"],
+        name: hash["name"],
+        slug: hash["slug"],
+        category: hash["category"] || "",
+        mechanism: hash["mechanism"] || "",
+        recommended_dosage: hash["recommended_dosage"] || {},
+        forms: hash["forms"] || [],
+        is_featured: hash["is_featured"] || false
+      )
+    end
+  end
+
+  # A health condition referenced in evidence links.
+  class Condition
+    attr_reader :slug, :name
+
+    def initialize(slug:, name:)
+      @slug = slug
+      @name = name
+    end
+
+    def self.from_hash(hash)
+      new(
+        slug: hash["slug"],
+        name: hash["name"]
+      )
+    end
+  end
+
+  # A research paper from PubMed.
+  class Paper
+    attr_reader :id, :pmid, :title, :journal, :publication_year,
+                :study_type, :citation_count, :is_open_access, :pubmed_link
+
+    def initialize(id:, pmid:, title:, journal: "", publication_year: nil,
+                   study_type: "", citation_count: 0, is_open_access: false,
+                   pubmed_link: "")
+      @id = id
+      @pmid = pmid
+      @title = title
+      @journal = journal
+      @publication_year = publication_year
+      @study_type = study_type
+      @citation_count = citation_count
+      @is_open_access = is_open_access
+      @pubmed_link = pubmed_link
+    end
+
+    def self.from_hash(hash)
+      new(
+        id: hash["id"],
+        pmid: hash["pmid"],
+        title: hash["title"],
+        journal: hash["journal"] || "",
+        publication_year: hash["publication_year"],
+        study_type: hash["study_type"] || "",
+        citation_count: hash["citation_count"] || 0,
+        is_open_access: hash["is_open_access"] || false,
+        pubmed_link: hash["pubmed_link"] || ""
+      )
+    end
+  end
+
+  # Nested ingredient reference within an evidence link.
+  class NestedIngredient
+    attr_reader :slug, :name
+
+    def initialize(slug:, name:)
+      @slug = slug
+      @name = name
+    end
+
+    def self.from_hash(hash)
+      new(
+        slug: hash["slug"],
+        name: hash["name"]
+      )
+    end
+  end
+
+  # An evidence link connecting an ingredient to a condition with a grade.
+  class EvidenceLink
+    attr_reader :id, :ingredient, :condition, :grade, :grade_label,
+                :summary, :direction, :total_studies, :total_participants
+
+    def initialize(id:, ingredient:, condition:, grade: "", grade_label: "",
+                   summary: "", direction: "", total_studies: 0,
+                   total_participants: 0)
+      @id = id
+      @ingredient = ingredient
+      @condition = condition
+      @grade = grade
+      @grade_label = grade_label
+      @summary = summary
+      @direction = direction
+      @total_studies = total_studies
+      @total_participants = total_participants
+    end
+
+    def self.from_hash(hash)
+      ingredient_data = hash["ingredient"] || {}
+      condition_data = hash["condition"] || {}
+
+      new(
+        id: hash["id"],
+        ingredient: NestedIngredient.from_hash(ingredient_data),
+        condition: Condition.from_hash(condition_data),
+        grade: hash["grade"] || "",
+        grade_label: hash["grade_label"] || "",
+        summary: hash["summary"] || "",
+        direction: hash["direction"] || "",
+        total_studies: hash["total_studies"] || 0,
+        total_participants: hash["total_participants"] || 0
+      )
+    end
+  end
+end

data/lib/citedhealth/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module CitedHealth
+  VERSION = "0.2.0"
+end

data/lib/citedhealth.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "citedhealth/version"
+require_relative "citedhealth/errors"
+require_relative "citedhealth/types"
+require_relative "citedhealth/client"

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: citedhealth
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Cited Health
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: API client for citedhealth.com. Search ingredients, evidence links, and
+  research papers for evidence-based health supplement information. Zero dependencies.
+email:
+- hello@citedhealth.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/citedhealth.rb
+- lib/citedhealth/client.rb
+- lib/citedhealth/errors.rb
+- lib/citedhealth/types.rb
+- lib/citedhealth/version.rb
+homepage: https://citedhealth.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://citedhealth.com
+  source_code_uri: https://github.com/citedhealth/citedhealth-rb
+  changelog_uri: https://github.com/citedhealth/citedhealth-rb/blob/main/CHANGELOG.md
+  documentation_uri: https://citedhealth.com/developers/
+  bug_tracker_uri: https://github.com/citedhealth/citedhealth-rb/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Ruby client for the Cited Health evidence-based supplement API
+test_files: []