ecoportal-api 0.3.8 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ecc5fc4d6be63751a1e9629798350e16eb2db7b0f7284efd6e77d0d18527338e
-  data.tar.gz: 3ea7c357cd0ec82dc62065dcae78425910c0c1b7fbd74167dd9c120475086bc0
+  metadata.gz: 1336e02ab24ebd2ffa1ee734fa8c41ce18bb8afc892e771e38aac15c50c5ba72
+  data.tar.gz: 2e7ec0cb920b9972d666e3645d43ae3a503cd9425d968c24519712257751b14a
 SHA512:
-  metadata.gz: 59c4c973da0173148a3c7f8deeaf7f439cbb0f5cbd96489bbb0c9bde30ffc715ab4e33f178c58c9d82c84bfe4c53f91ce015c8d3db951c138cfd8a861792c9a6
-  data.tar.gz: c2597d285cf99804dc76343d02cae48f654ad3e33db954462d9731af1a67c4bb547fe1ef2fc010ce2ebfd8442831eb9c774f33a3140247365f7ad44843f76cf1
+  metadata.gz: a877e517ddb1ee1cd71e6e40806a685a2bcb09ee7a7c73726e4fbd1527175cdb0e84bf24e592cb56b7f3686ab1b6729931346636add41edf5b987156444f1942
+  data.tar.gz: d60a8dc08b2d26b28b4aeaec0bd0cf708f2a05977761554362ab848c640d5cc5f5b74b9054eddcf5f4d62f0952a24719da086bf3572ccea980c0754295d8db01

data/.gitignore

@@ -1,11 +1,19 @@
+# it's a gem, ignore the lockfile
+Gemfile.lock
+
+# build artifacts
+*.gem
 /.bundle/
+/vendor/bundle
+/spec/reports/
+/tmp/
+/pkg/
+
+# docs
 /.yardoc
 /_yardoc/
 /coverage/
 /doc/
-/pkg/
-/spec/reports/
-/tmp/
 
 # rspec failure tracking
 .rspec_status

data/.yardopts

@@ -0,0 +1,10 @@
+--readme README.md
+--charset utf-8
+--markup-provider=redcarpet
+--markup=markdown
+--no-private
+--output-dir ./doc
+'lib/**/*.rb'
+-
+CHANGELOG.md
+LICENSE

data/Gemfile.lock

@@ -1,14 +1,14 @@
 PATH
   remote: .
   specs:
-    ecoportal-api (0.3.3)
+    ecoportal-api (0.4.1)
       hash-polyfill (~> 0)
       http (~> 3)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.5.2)
+    addressable (2.6.0)
       public_suffix (>= 2.0.2, < 4.0)
     diff-lcs (1.3)
     domain_name (0.5.20180417)
@@ -23,8 +23,9 @@ GEM
       domain_name (~> 0.5)
     http-form_data (2.1.1)
     http_parser.rb (0.6.0)
-    public_suffix (3.0.2)
+    public_suffix (3.0.3)
     rake (10.5.0)
+    redcarpet (3.4.0)
     rspec (3.7.0)
       rspec-core (~> 3.7.0)
       rspec-expectations (~> 3.7.0)
@@ -40,16 +41,20 @@ GEM
     rspec-support (3.7.1)
     unf (0.1.4)
       unf_ext
-    unf_ext (0.0.7.5)
+    unf_ext (0.0.7.6)
+    yard (0.9.18)
 
 PLATFORMS
   ruby
+  x64-mingw32
 
 DEPENDENCIES
   bundler (~> 1.16)
   ecoportal-api!
   rake (~> 10.0)
+  redcarpet (~> 3.4, >= 3.4.0)
   rspec (~> 3.0)
+  yard (~> 0.9, >= 0.9.18)
 
 BUNDLED WITH
-   1.16.1
+   1.17.3

data/Rakefile

@@ -1,6 +1,27 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
+require "yard"
+require "redcarpet"
 
+desc "run the specs"
 RSpec::Core::RakeTask.new(:spec)
 
-task :default => :spec
+desc "run rspec showing backtrace"
+RSpec::Core::RakeTask.new(:spec_trace) do |task|
+  task.rspec_opts = ['--backtrace']
+end
+
+desc "run rspec stopping on first fail, and show backtrace"
+RSpec::Core::RakeTask.new(:spec_fast) do |task|
+  task.rspec_opts = ['--fail-fast', '--backtrace']
+end
+
+# default task name is yard
+desc "Yard: generate all the documentation"
+YARD::Rake::YardocTask.new(:doc) do |t|
+  #t.files = ['lib/**/*.rb']
+end
+
+task :default     => [:spec]
+task :rspec_trace => :spec_trace
+task :rspec_fast  => :spec_fast

data/ecoportal-api.gemspec

@@ -20,10 +20,12 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.16"
-  spec.add_development_dependency "rake", "~> 10.0"
-  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "bundler",   "~> 1.16"
+  spec.add_development_dependency "rake",      "~> 10.0"
+  spec.add_development_dependency "rspec",     "~> 3.0"
+  spec.add_development_dependency "yard",      "~> 0.9", ">= 0.9.18"
+  spec.add_development_dependency "redcarpet", "~> 3.4", ">= 3.4.0"
 
-  spec.add_dependency 'http', '~> 3'
+  spec.add_dependency 'http',          '~> 3'
   spec.add_dependency 'hash-polyfill', '~> 0'
 end

data/lib/ecoportal/api/common.rb

@@ -4,11 +4,14 @@ module Ecoportal
     end
   end
 end
-require 'ecoportal/api/common/client'
+
+require 'ecoportal/api/common/base_class'
+require 'ecoportal/api/common/hash_diff'
+require 'ecoportal/api/common/base_model'
+require 'ecoportal/api/common/doc_helpers'
 require 'ecoportal/api/common/logging'
+require 'ecoportal/api/common/client'
 require 'ecoportal/api/common/response'
 require 'ecoportal/api/common/wrapped_response'
-require 'ecoportal/api/common/base_model'
-require 'ecoportal/api/common/batch_operation'
 require 'ecoportal/api/common/batch_response'
-require 'ecoportal/api/common/hash_diff'
+require 'ecoportal/api/common/batch_operation'

data/lib/ecoportal/api/common/base_class.rb

@@ -0,0 +1,29 @@
+module Ecoportal
+  module API
+    module Common
+      module BaseClass
+
+        def class_resolver(name, klass)
+          define_singleton_method(name) { resolve_class(klass) }
+          define_method(name) { self.class.resolve_class(klass) }
+        end
+
+        def resolve_class(klass)
+          @resolved ||= {}
+          @resolved[klass] ||=
+            case klass
+              when Class
+                klass
+              when String
+                Kernel.const_get(klass)
+              when Symbol
+                resolve_class(self.send(klass))
+              else
+                raise "Unknown class: #{klass}"
+            end
+        end
+
+      end
+    end
+  end
+end

data/lib/ecoportal/api/common/base_model.rb

@@ -2,21 +2,65 @@ module Ecoportal
   module API
     module Common
       class BaseModel
-        attr_reader :doc
-        def initialize(doc = {})
-          @doc          = doc
-          @original_doc = JSON.parse(doc.to_json)
+        class UnlinkedModel < Exception
+          def initialize (msg = "Something went wrong when linking the document.")
+            super(msg)
+          end
         end
 
-        def self.build(doc = {})
-          new(doc).tap do |instance|
-            instance.instance_variable_set("@original_doc", {})
+        extend BaseClass
+
+        class << self
+          def passthrough(*methods, to: :doc)
+            methods.each do |method|
+              method = method.to_s
+              define_method method do
+                send(to)[method]
+              end
+              define_method "#{method}=" do |value|
+                send(to)[method] = value
+              end
+            end
           end
+
+          def embeds_one(method, key: method, nullable: false, klass:)
+            method = method.to_s.freeze
+            var    = "@#{method}".freeze
+            key    = key.to_s.freeze
+            define_method(method) do
+              return instance_variable_get(var) if instance_variable_defined?(var)
+              doc[key] ||= {} unless nullable
+              return instance_variable_set(var, nil) unless doc[key]
+
+              self.class.resolve_class(klass).new(
+                doc[key], parent: self, key: key
+              ).tap {|obj| instance_variable_set(var, obj)}
+            end
+          end
+
         end
 
-        def print
-          puts JSON.pretty_generate(as_json)
-          self
+        attr_reader :_parent, :_key
+
+        def initialize(doc = {}, parent: self, key: nil)
+          @_parent = parent
+          @_key    = key
+          if !_parent || !_key
+            @doc          = doc
+            @original_doc = JSON.parse(@doc.to_json)
+          end
+        end
+
+        def doc
+          raise UnlinkedModel.new  unless linked?
+          return _parent.doc[_key] unless _parent == self
+          @doc
+        end
+
+        def original_doc
+          raise UnlinkedModel.new  unless linked?
+          return _parent.original_doc[_key] unless _parent == self
+          @original_doc
         end
 
         def as_json
@@ -29,20 +73,45 @@ module Ecoportal
 
         def as_update
           new_doc = as_json
-          Common::HashDiff.diff(new_doc, @original_doc)
+          Common::HashDiff.diff(new_doc, original_doc)
         end
 
-        def self.passthrough(*methods, to:)
-          methods.each do |method|
-            method = method.to_s
-            define_method method do
-              send(to)[method]
-            end
-            define_method "#{method}=" do |value|
-              send(to)[method] = value
-            end
+        def dirty?
+          as_update != {}
+        end
+
+        def consolidate!
+          raise UnlinkedModel.new  unless linked?
+          case
+          when @original_doc
+            @original_doc = JSON.parse(@doc.to_json)
+          else
+            _parent.original_doc[_key] = JSON.parse(doc.to_json)
           end
         end
+
+        def reset!
+          raise UnlinkedModel.new  unless linked?
+          case
+          when @doc
+            @doc = JSON.parse(@original_doc.to_json)
+          else
+            _parent.doc[_key] = JSON.parse(original_doc.to_json)
+          end
+        end
+
+        def print
+          puts JSON.pretty_generate(as_json)
+          self
+        end
+
+        protected
+
+        def linked?
+          is_root = _parent == self && defined?(@doc)
+          is_root || _parent.doc[_key]
+        end
+
       end
     end
   end

data/lib/ecoportal/api/common/batch_operation.rb

@@ -1,4 +1,3 @@
-require 'ecoportal/api/common/doc_helpers'
 module Ecoportal
   module API
     module Common

data/lib/ecoportal/api/common/batch_response.rb

@@ -2,20 +2,25 @@ module Ecoportal
   module API
     module Common
       class BatchResponse
+
         attr_reader :status, :body, :result
+
         def initialize(status, body, result = nil)
           @status = HTTP::Response::Status.new(status)
           @body   = body
           @result = result
         end
+
         def success?
           status.success?
         end
+
         def each
           [*@result].each do |doc|
             yield doc
           end
         end
+        
         def print
           if success?
             each(&:print)

data/lib/ecoportal/api/common/client.rb

@@ -2,9 +2,22 @@ require 'http'
 module Ecoportal
   module API
     module Common
+      # @note
+      #   - You can see the documentation of the `HTTP` module in [the repository](https://github.com/httprb/http)
+      #     - it does `extend` the module `Chainable` ([chainable.rb](https://github.com/httprb/http/blob/master/lib/http/chainable.rb)),
+      #     - where all the http requests are dev by using `HTTP::Client#request` ([client.rb](https://github.com/httprb/http/blob/master/lib/http/client.rb))
+      #     - which calls `build_request` (new `HTTP::Request`) and `perform` (new `HTTP::Connection`)
+      #     - to return `HTTP::Response` ([response.rb](https://github.com/httprb/http/blob/master/lib/http/response.rb))
+      # @attr_reader logger [Logger] the logger.
       class Client
         attr_accessor :logger
 
+        # @note the `api_key` will be automatically added as parameter `X-ApiKey` in the header of the http requests.
+        # @param api_key [String] the key version to stablish the api connection.
+        # @param version [String] it is part of the base url and will determine the api version we query against.
+        # @param host [String] api server domain.
+        # @param logger [Logger] an object with `Logger` interface to generate logs.
+        # @return [Client] an object that holds the configuration of the api connection.
         def initialize(api_key:, version: "v1", host: "live.ecoportal.com", logger: nil)
           @version  = version
           @api_key  = api_key
@@ -21,10 +34,27 @@ module Ecoportal
           @response_logging_enabled = true
         end
 
+        # Logger interface.
+        # @example:
+        #   log(:info) {"General information on what's going on"}
+        #   log(:warn) {"This is a warning that something is likely to have gone amiss"}
+        #   log(:error) {"Something went wrong"}
+        #   log(:fatal) {"An unrecoverable error has happend"}
+        # @param level [Symbol] the level that the message should be logged.
+        # @yield [] generates the message.
+        # @yieldreturn [String] the generated message.
         def log(level, &block)
-          @logger.send(level, &block) if @logger
+          logger.send(level, &block) if logger
         end
 
+        # Sends an http `GET` request against the api version using `path` to complete the base url,
+        # and adding the key_value pairs of `params` in the http _header_.
+        # @param path [String] the tail that completes the url of the request.
+        # @param params [Hash] the header paramters of the http request (not including the api key).
+        # @option params [String] :page the current page we are requesting with given the `:per_page` offset.
+        # @option params [String] :per_page the offset or the number of entries you get per request.
+        # @option params [String] :q some text to search. Omit this parameter to target all the entries.
+        # @return [Common::Reponse] the basic custom response object.
         def get(path, params: {})
           instrument("GET", path, params) do
             request do |http|
@@ -33,6 +63,12 @@ module Ecoportal
           end
         end
 
+        # Sends an http `POST` request against the api version using `path` to complete the base url,
+        # and the `data` as a body of the http request.
+        # @note it automatically adds the http header param `Content-Type` as `application/json`
+        # @param path [String] the tail that completes the url of the request.
+        # @param data [String] the body of the query in json format.
+        # @return [Common::Reponse] the basic custom response object.
         def post(path, data:)
           instrument("POST", path, data) do
             request do |http|
@@ -41,6 +77,12 @@ module Ecoportal
           end
         end
 
+        # Sends an http `PATCH` request against the api version using `path` to complete the base url,
+        # and the `data` as a body of the http request.
+        # @note it automatically adds the http header param `Content-Type` as `application/json`
+        # @param path [String] the tail that completes the url of the request.
+        # @param data [String] the body of the query in json format.
+        # @return [Common::Reponse] the basic custom response object.
         def patch(path, data:)
           instrument("PATCH", path, data) do
             request do |http|
@@ -49,6 +91,9 @@ module Ecoportal
           end
         end
 
+        # Sends an http `DELETE` request against the api version using `path` to complete the base url.
+        # @param path [String] the tail that completes the url of the request.
+        # @return [Common::Reponse] the basic custom response object.
         def delete(path)
           instrument("DELETE", path) do
             request do |http|
@@ -57,18 +102,33 @@ module Ecoportal
           end
         end
 
+        # Allows to launch a different operation via `block`, providing the
+        # basic HTTP connection to the block.
+        # @yield [http] launch specific http request.
+        # @yieldparam http [HTTP] the http connection.
+        # @yieldreturn [Common::Response] the basic custom reponse object.
+        # @return [Common::Reponse] the basic custom response object.
         def request
           wrap_response yield(base_request)
         end
 
+        # Wrap with basic custom object of the gem for responses.
+        # @param response [HTTP::Response]
+        # @return [Common::Reponse] the basic custom response object.
         def wrap_response(response)
           Ecoportal::API::Common::Response.new(response)
         end
 
+        # Creates a HTTP object adding the `X-ApiKey` param to the header.
+        # @note It configures HTTP so it only allows body data in json format.
+        # @return [HTTP] HTTP object.
         def base_request
           @base_request ||= HTTP.headers("X-ApiKey" => @api_key).accept(:json)
         end
 
+        # Full URl builder of the request
+        # @param path [String] the tail that completes the url of the request.
+        # @return [String] the final url.
         def url_for(path)
           @base_uri+@version+path
         end