wikirate4ruby 1.0.0

data/README.md

@@ -0,0 +1,48 @@
+# Wikirate4ruby
+
+Wikirate4ruby is a ruby library for the [Wikirate API](https://wikirate.org/Use_the_API) licensed under GNU GPL v3.
+
+## Installation
+
+    gem install wikirate4ruby
+
+## Usage
+
+```ruby
+# Initializing client
+client = Wikirate4ruby::REST::Client.new("YOUR_API_TOKEN")
+
+#get a company given the name or wikirate id
+company = client.get_company("Adidas_AG")
+#get a company's answers
+answers = client.get_company_answers(company.id, { 'year' => 2022 })
+#create a new company
+wikirate = client.add_company({ 'name' => 'Wikirate International e.V.', 'headquarters' => 'Germany' })
+#add answer to metric
+address = client.add_research_answer({ 'metric_name' => 'Address',
+                                       'metric_designer' => 'Commons',
+                                       'year' => 2023,
+                                       'value' => "Schlimannstrasse 29, Berlin",
+                                       'company' => wikirate.id,
+                                       'source' => 'Source-123' })
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can
+also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the
+version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version,
+push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/wikirate/wikirate4ruby. This project is
+intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to
+the [code of conduct](https://github.com/[USERNAME]/wikirate4ruby/blob/master/CODE_OF_CONDUCT.md).
+
+## Code of Conduct
+
+Everyone interacting in the Wikirate4ruby project's codebases, issue trackers, chat rooms and mailing lists is expected
+to follow the [code of conduct](https://github.com/wikirate/wikirate4ruby/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/test_*.rb"]
+end
+
+require "standard/rake"
+
+task default: %i[test standard]

data/lib/wikirate4ruby/client.rb

@@ -0,0 +1,395 @@
+require_relative 'entities/card'
+require_relative 'entities/metric'
+require_relative 'entities/company'
+require_relative 'entities/source'
+require_relative 'entities/topic'
+require_relative 'entities/dataset'
+require_relative 'entities/research_group'
+require_relative 'entities/company_group'
+require_relative 'entities/answer'
+require_relative 'entities/relationship_answer'
+require_relative 'entities/region'
+require_relative 'entities/checked_by'
+require_relative './request'
+require_relative './utils'
+require_relative './request_utils'
+require 'json'
+require 'logger'
+
+module Wikirate4ruby
+  module REST
+    class Client
+      include Wikirate4ruby::Entities
+      include Wikirate4ruby::Utils
+      include Wikirate4ruby::RequestUtils
+
+      BASE_URL = 'https://wikirate.org'
+      attr :request
+
+      def initialize(api_key, wikirate_api_url = BASE_URL, auth = {})
+        @request = Request.new(api_key, wikirate_api_url, auth)
+        @logger = Logger.new(STDOUT)
+      end
+
+      def get_company(identifier)
+        get_entity(identifier, Company)
+      end
+
+      def get_metric(identifier)
+        get_entity(identifier, Metric)
+      end
+
+      def get_answer(identifier)
+        get_entity(identifier, Answer)
+      end
+
+      def get_relationship_answer(identifier)
+        get_entity(identifier, RelationshipAnswer)
+      end
+
+      def get_dataset(identifier)
+        get_entity(identifier, Dataset)
+      end
+
+      def get_company_group(identifier)
+        get_entity(identifier, CompanyGroup)
+      end
+
+      def get_topic(identifier)
+        get_entity(identifier, Topic)
+      end
+
+      def get_research_group(identifier)
+        get_entity(identifier, ResearchGroup)
+      end
+
+      def get_source(identifier)
+        get_entity(identifier, Source)
+      end
+
+      def get_region(identifier)
+        get_entity(identifier, Region)
+      end
+
+      def get_card(identifier)
+        get_entity(identifier, Card)
+      end
+
+      def get_checked_by(identifier)
+        get_entity(identifier, CheckedBy)
+      end
+
+      def get_project(identifier)
+        get_entity(identifier, Card)
+      end
+
+      def get_companies(params = {})
+        companies = []
+        response = @request.get('/Companies.json', endpoint_params = %w[limit offset],
+                                filters = %w[name company_category company_group country], params)
+
+        response['items'].each do |item|
+          companies.append(Company.new(item))
+        end
+        companies
+      end
+
+      def get_metrics(params = {})
+        metrics = []
+        response = @request.get('/Metrics.json', endpoint_params = %w[limit offset],
+                                filters = %w[name bookmark wikirate_topic designer published metric_type value_type research_policy dataset], params)
+
+        response['items'].each do |item|
+          metrics.append(Metric.new(item))
+        end
+        metrics
+      end
+
+      def get_topics(params = {})
+        topics = []
+        response = @request.get('/Topics.json', endpoint_params = %w[limit offset],
+                                filters = %w[name bookmark], params)
+
+        response['items'].each do |item|
+          topics.append(Topic.new(item))
+        end
+        topics
+      end
+
+      def get_datasets(params = {})
+        datasets = []
+        response = @request.get('/Data_Sets.json', endpoint_params = %w[limit offset],
+                                filters = %w[name bookmark wikirate_topic], params)
+
+        response['items'].each do |item|
+          datasets.append(Dataset.new(item))
+        end
+        datasets
+      end
+
+      def get_projects(params = {})
+        projects = []
+        response = @request.get('/Projects.json', endpoint_params = %w[limit offset],
+                                filters = %w[name wikirate_status], params)
+
+        response['items'].each do |item|
+          projects.append(Card.new(item))
+        end
+        projects
+      end
+
+      def get_sources(params = {})
+        sources = []
+        response = @request.get('/Sources.json', endpoint_params = %w[limit offset],
+                                filters = %w[name wikirate_title wikirate_topic report_type year wikirate_link company_name], params)
+
+        response['items'].each do |item|
+          sources.append(Source.new(item))
+        end
+        sources
+      end
+
+      def get_research_groups(params = {})
+        research_groups = []
+        response = @request.get('/Research_Groups.json', endpoint_params = %w[limit offset],
+                                filters = %w[name], params)
+
+        response['items'].each do |item|
+          research_groups.append(ResearchGroup.new(item))
+        end
+        research_groups
+      end
+
+      def get_company_groups(params = {})
+        company_groups = []
+        response = @request.get('/Company_Groups.json', endpoint_params = %w[limit offset],
+                                filters = %w[name], params)
+
+        response['items'].each do |item|
+          company_groups.append(CompanyGroup.new(item))
+        end
+        company_groups
+      end
+
+      def get_answers(metric_name, metric_designer, params = {})
+        answers = []
+        response = @request.get("/#{tranform_to_wr_friendly_name(metric_designer)}+#{tranform_to_wr_friendly_name(metric_name)}+Answers.json",
+                                endpoint_params = %w[limit offset],
+                                filters = %w[year verification value value_from value_to status source updated updater published
+                                    dataset company_id company_name company_category company_group country], params)
+
+        response['items'].each do |item|
+          answers.append(Answer.new(item))
+        end
+        answers
+      end
+
+      def get_answers_by_metric_id(metric_id, params = {})
+        answers = []
+        response = @request.get("/#{str_identifier(metric_id)}+Answers.json", endpoint_params = %w[limit offset],
+                                filters = %w[year verification value value_from value_to status source updated updater published
+                                    dataset company_id company_name company_category company_group country], params)
+
+        response['items'].each do |item|
+          answers.append(Answer.new(item))
+        end
+        answers
+      end
+
+      def get_company_answers(identifier, params = {})
+        answers = []
+        endpoint = "/#{str_identifier(identifier)}+Answers.json"
+        response = @request.get(endpoint, endpoint_params = %w[limit offset],
+                                filters = %w[metric_name designer metric_type value_type research_policy year verification value
+                                    value_from value_to status source updated updater published dataset company_id
+                                    company_name company_category company_group country], params)
+
+        response['items'].each do |item|
+          answers.append(Answer.new(item))
+        end
+        answers
+      end
+
+      def get_relationship_answers(metric_name, metric_designer, params = {})
+        answers = []
+        response = @request.get("/#{tranform_to_wr_friendly_name(metric_designer)}+#{tranform_to_wr_friendly_name(metric_name)}+RelationshipAnswers.json",
+                                endpoint_params = %w[limit offset],
+                                filters = %w[year name company_category company_group dataset updated updater source published], params)
+
+        response['items'].each do |item|
+          answers.append(RelationshipAnswer.new(item))
+        end
+        answers
+      end
+
+      def get_relationship_answers_by_metric_id(metric_id, params = {})
+        answers = []
+        response = @request.get("/#{str_identifier(metric_id)}+RelationshipAnswers.json", endpoint_params = %w[limit offset],
+                                filters = %w[year name company_category company_group dataset updated updater source published], params)
+
+        response['items'].each do |item|
+          answers.append(RelationshipAnswer.new(item))
+        end
+        answers
+      end
+
+      # @param [Hash] data
+      # @return [Wikirate4ruby::Entities::Company]
+      def add_company(data = {})
+        required_params = %w[name headquarters]
+        required_params.each do |param|
+          if data[param].nil? || data[param] == ''
+            raise Wikirate4ruby::Error::Wikirate4rubyError, "Invalid set of params! You need to define all the following
+                                                             params to import a new company: #{required_params.to_s}"
+          end
+        end
+        card_name = data['name']
+        data.delete('name')
+        params = creation_params('Company', data, %w[headquarters oar_id wikipedia open_corporates sec_cik])
+        params['card[name]'] = card_name
+        params['confirmed'] = true
+        params['card[skip]'] = 'update_oc_mapping_due_to_headquarters_entry' if data['open_corporates'].nil?
+        response = @request.post('/card/create', params)
+        Company.new(response)
+      end
+
+      def update_company(data = {})
+        if data['company'].nil? || data['company'] == ''
+          raise Wikirate4ruby::Error::Wikirate4rubyError, "Invalid set of params! You need to define all the following params to update a
+                                      company: [company]"
+        end
+        card_name = str_identifier(data['company'])
+        data.delete 'company'
+
+        params = creation_params('Company', data, %w[headquarters open_corporates oar_id wikipedia sec_cik])
+        params['card[name]'] = card_name
+        response = @request.post('/card/update', params)
+        Company.new(response)
+      end
+
+      def add_research_metric_answer(data = {})
+        required_params = %w[metric_designer metric_name company year value source]
+        required_params.each do |param|
+          if data[param].nil? || data[param] == ''
+            raise Wikirate4ruby::Error::Wikirate4rubyError, "Invalid set of params! You need to define all the following params to import a
+                                      new research answer: #{required_params.to_s}"
+          end
+        end
+        card_name = "#{data['metric_designer']}+#{data['metric_name']}+#{str_identifier(data['company'])}+#{data['year']}"
+        %w[metric_designer metric_name company year].each do |key|
+          data.delete key
+        end
+        params = creation_params('Answer', data, %w[source value discussion])
+        params['card[name]'] = card_name
+        response = @request.post('/card/create', params)
+        Answer.new(response)
+      end
+
+      def update_research_metric_answer(data = {})
+        required_params = %w[metric_designer metric_name company]
+        if data['answer_id'].nil?
+          required_params.each do |param|
+            if data[param].nil? || data[param] == ''
+              raise Wikirate4ruby::Error::Wikirate4rubyError, "Invalid set of params! You need to define all the following params to import a
+                                      new research answer: #{required_params.to_s}"
+            end
+          end
+          card_name = "#{data['metric_designer']}+#{data['metric_name']}+#{str_identifier(data['company'])}+#{data['year']}"
+          %w[metric_designer metric_name company year].each do |key|
+            data.delete key
+          end
+          allowed_params = %w[source value discussion]
+        else
+          card_name = str_identifier(data['answer_id'])
+          data.delete 'answer_id'
+          allowed_params = %w[year source value discussion]
+        end
+
+        params = creation_params('Answer', data, allowed_params)
+        params['card[name]'] = card_name
+        puts(params)
+        response = @request.post('/card/update', params)
+        Answer.new(response)
+      end
+
+      def add_relationship_metric_answer(data = {})
+        required_params = %w[metric_designer metric_name subject_company object_company year value source]
+        required_params.each do |param|
+          if data[param].nil? || data[param] == ''
+            raise Wikirate4ruby::Error::Wikirate4rubyError, "Invalid set of params! You need to define all the following params to import a
+                                      new research answer: #{required_params.to_s}"
+          end
+        end
+        card_name = "#{data['metric_designer']}+#{data['metric_name']}+#{str_identifier(data['subject_company'])}+#{data['year']}+#{str_identifier(data['object_company'])}"
+        %w[metric_designer metric_name subject_company object_company year].each do |key|
+          data.delete key
+        end
+        params = creation_params('RelationshipAnswer', data, %w[source value comments])
+        params['card[name]'] = card_name
+        response = @request.post('/card/create', params)
+        RelationshipAnswer.new(response)
+      end
+
+      def update_relationship_metric_answer(data = {})
+        required_params = %w[metric_designer metric_name subject_company object_company year]
+        if data['answer_id'].nil?
+          required_params.each do |param|
+            if data[param].nil? || data[param] == ''
+              raise Wikirate4ruby::Error::Wikirate4rubyError, "Invalid set of params! You need to define all the following params to import a
+                                      new research answer: #{required_params.to_s}"
+            end
+          end
+          card_name = "#{data['metric_designer']}+#{data['metric_name']}+#{str_identifier(data['company'])}+#{data['year']}"
+          %w[metric_designer metric_name subject_company year object_company].each do |key|
+            data.delete key
+          end
+          allowed_params = %w[source value discussion]
+        else
+          card_name = str_identifier(data['answer_id'])
+          data.delete 'answer_id'
+          allowed_params = %w[year source value discussion]
+        end
+
+        params = creation_params('RelationshipAnswer', data, allowed_params)
+        response = @request.post("/update/#{card_name}", params)
+        RelationshipAnswer.new(response)
+      end
+
+      # @param [Hash] data
+      # @return [Wikirate4ruby::Entities::Source]
+      def add_source(data = {})
+        required_params = %w[link title]
+        required_params.each do |param|
+          if data[param].nil? || data[param] == ''
+            raise Wikirate4ruby::Error::Wikirate4rubyError, "Invalid set of params! You need to define all the following params to import a
+                                      new source: #{required_params.to_s}"
+          end
+        end
+        params = creation_params('Source', data, %w[link title company report_type year])
+        params['card[skip]'] = 'requirements'
+        response = @request.post('/card/create', params)
+        Source.new(response)
+      end
+
+      def update_source(data = {})
+        if data['source'].nil? || data['source'] == ''
+          raise Wikirate4ruby::Error::Wikirate4rubyError, "Invalid set of params! You need to define all the following params to update a
+                                      source: [source]"
+        end
+        card_name = str_identifier(data['source'])
+        data.delete 'source'
+        params = creation_params('Source', data, %w[link title company report_type year])
+        params['card[skip]'] = 'requirements'
+        response = @request.post("/update/#{card_name}", params)
+        Source.new(response)
+      end
+
+      private
+
+      def get_entity(identifier, klass)
+        klass.new(@request.get("/#{str_identifier(identifier)}.json"))
+      end
+
+    end
+  end
+end

data/lib/wikirate4ruby/entities/answer.rb

@@ -0,0 +1,26 @@
+require_relative '../error'
+
+module Wikirate4ruby
+  module Entities
+    class Answer < Entities::Card
+      ATTRIBUTES = %i[company year value comments record_url metric_name metric_designer sources checked_by].freeze
+      attr_reader(*ATTRIBUTES)
+
+      def initialize(answer)
+        super answer
+        raise parsing_error name = "IncompatibleCardType", message = "The input Card is not an Answer but a #{@type}" unless @type.include? 'Answer'
+
+        @metric_name = get_content('name').split('+')[1]
+        @metric_designer = get_content('name').split('+')[0]
+        @company = get_content 'company'
+        @value = get_content 'value'
+        @year = get_content 'year'
+        @sources = get_array_of 'sources', Source
+        @checked_by = get_content 'checked_by'
+        @comments = get_content 'comments'
+        @record_url = get_content 'record_url'
+
+      end
+    end
+  end
+end

data/lib/wikirate4ruby/entities/card.rb

@@ -0,0 +1,81 @@
+module Wikirate4ruby
+  module Entities
+    class Card
+      CARD_ATTRIBUTES = %i[id type name content url codename html_url created_at updated_at requested_at].freeze
+      attr_reader(*CARD_ATTRIBUTES)
+
+      def initialize(card)
+        @data = card
+        @id = get_content 'id'
+        @type = @data['type'].is_a?(String) ? @data['type'] : @data['type']['name']
+        @name = @data['name']
+        @content = @data['content']
+        @url = @data['url']
+        @codename = @data['codename']
+        @html_url = @data['html_url']
+        @created_at = @data['created_at']
+        @updated_at = @data['updated_at']
+        @requested_at = @data['requested_at']
+      end
+
+      def raw_json
+        JSON.pretty_generate(@data)
+      end
+
+      # @return [Hash{String->Unknown}]
+      def as_json
+        {
+          'id' => @id,
+          'type' => @type,
+          'name' => @name,
+          'content' => @content,
+          'url' => @url,
+          'codename' => @codename,
+          'html_url' => @html_url,
+          'created_at' => @created_at,
+          'updated_at' => @updated_at,
+          'requested_at' => @requested_at
+        }
+      end
+
+      def to_json(*_args)
+        JSON.pretty_generate(to_hash)
+      end
+
+      def to_s
+        to_json
+      end
+
+      protected
+
+      def to_hash
+        hash = {}
+        instance_variables.each { |var| var.to_s == '@data' || instance_variable_get(var).nil? ? nil : hash[var.to_s.delete('@')] = instance_variable_get(var) }
+        hash
+      end
+
+      def get_content(field)
+        @data[field].is_a?(Hash) ? @data[field]['content'] : @data[field]
+      end
+
+      def get_name(field)
+        @data[field].is_a?(Hash) ? @data[field]['name'] : @data[field]
+      end
+
+      def get_array_of(field, klass)
+        return @data[field] unless @data[field].is_a? Array
+
+        list = []
+        @data[field].each do |item|
+          list.append(klass.new(item))
+        end
+        list
+      end
+
+      def parsing_error(name, message)
+        error = Wikirate4ruby::Error::ParsingError.from_processing_response({ :name => name, :message => message })
+        return error
+      end
+    end
+  end
+end

data/lib/wikirate4ruby/entities/checked_by.rb

@@ -0,0 +1,19 @@
+require_relative '../error'
+
+module Wikirate4ruby
+  module Entities
+    class CheckedBy < Entities::Card
+      ATTRIBUTES = %i[checks].freeze
+      attr_reader(*ATTRIBUTES)
+
+      def initialize(checked_by)
+        super checked_by
+        raise parsing_error name = 'IncompatibleCardType', message = "The input Card is not a Checked By but a #{@type}" unless @name.end_with? 'checked by'
+
+        @checks = get_content 'checks'
+
+      end
+
+    end
+  end
+end

data/lib/wikirate4ruby/entities/company.rb

@@ -0,0 +1,25 @@
+require_relative '../error'
+
+module Wikirate4ruby
+  module Entities
+    class Company < Entities::Card
+      ATTRIBUTES = %i[headquarters wikipedia aliases open_corporates os_id cik answers_url].freeze
+      attr_reader(*ATTRIBUTES)
+
+      def initialize(company)
+        super company
+        raise parsing_error name = "IncompatibleCardType", message = "The input Card is not a Company but a #{@type}" if @type != "Company"
+
+        @headquarters = get_content 'headquarters'
+        @wikipedia = get_content 'wikipedia'
+        @aliases = get_content 'aliases'
+        @open_corporates = get_content 'open_corporates'
+        @os_id = get_content 'oar_id'
+        @cik = get_content 'cik'
+        @answers_url = get_content 'answers_url'
+
+      end
+
+    end
+  end
+end

data/lib/wikirate4ruby/entities/company_group.rb

@@ -0,0 +1,21 @@
+require_relative '../error'
+
+module Wikirate4ruby
+  module Entities
+    class CompanyGroup < Entities::Card
+      ATTRIBUTES = %i[links companies specification].freeze
+      attr_reader(*ATTRIBUTES)
+
+      def initialize(company_group)
+        super company_group
+        raise parsing_error name = "IncompatibleCardType", message = "The input Card is not a Company Group but a #{@type}" if @type != 'Company Group'
+
+        @links = get_content 'links'
+        @companies = get_content 'companies'
+        @specification = get_content 'specification'
+
+      end
+
+    end
+  end
+end

data/lib/wikirate4ruby/entities/dataset.rb

@@ -0,0 +1,21 @@
+require_relative '../error'
+
+module Wikirate4ruby
+  module Entities
+    class Dataset < Entities::Card
+      ATTRIBUTES = %i[answers metrics companies license].freeze
+      attr_reader(*ATTRIBUTES)
+
+      def initialize(dataset)
+        super dataset
+        raise parsing_error name = "IncompatibleCardType", message = "The input Card is not a Dataset but a #{@type}" if @type != 'Data Set'
+
+        @answers = get_array_of 'items', Answer
+        @metrics = get_content 'metrics'
+        @companies = get_content 'companies'
+        @license = get_content 'license'
+
+      end
+    end
+  end
+end