ecoportal-api 0.3.8 → 0.4.1

data/lib/ecoportal/api/internal/policy_group.rb

@@ -2,7 +2,7 @@ module Ecoportal
   module API
     class Internal
       class PolicyGroup < Common::BaseModel
-        passthrough :id, :name, to: :doc
+        passthrough :id, :name
       end
     end
   end

data/lib/ecoportal/api/internal/policy_groups.rb

@@ -1,16 +1,25 @@
 module Ecoportal
   module API
     class Internal
+      # @attr_reader client [Common::Client] a `Common::Client` object that holds the configuration of the api connection.
       class PolicyGroups
         include Enumerable
+
         attr_reader :client
+
+        # @param client [Common::Client] a `Common::Client` object that holds the configuration of the api connection.
+        # @return [PolicyGroups] an instance object ready to make policy groups api requests.
         def initialize(client)
           @client = client
         end
+
+        # Gets all the policy groups via api request.
+        # @return [Enumerable<PolicyGroup>] an `Enumerable` with all the policy groups already wrapped as `PolicyGroup` objects.
         def get_all
-          response = @client.get("/policy_groups")
+          response = client.get("/policy_groups")
           Common::WrappedResponse.new(response, Internal::PolicyGroup)
         end
+
         def each(&block)
           return to_enum(:each) unless block
           get_all.each(&block)

data/lib/ecoportal/api/v1.rb

@@ -1,26 +1,49 @@
 module Ecoportal
   module API
+    # @attr_reader client [Common::Client] a `Common::Client` object that holds the configuration of the api connection.
+    # @attr_reader logger [Logger] the logger.
     class V1
+      extend Common::BaseClass
       include Common::Logging
+
+      VERSION = "v1"
+      class_resolver :people_class,  "Ecoportal::API::V1::People"
+      class_resolver :person_schemas_class,  "Ecoportal::API::V1::PersonSchemas"
+
       attr_reader :client, :logger
+
+      # Creates an `V1` object to scope version specific api requests.
+      # @note
+      #   - The const `VERSION` determineds the api version that client will query against.
+      #   - This means that each sublcass of `V1` should define their own `VERSION` constant.
+      # @param api_key [String] the key version to stablish the api connection.
+      # @param host [String] api server domain.
+      # @param logger [Logger] an object with `Logger` interface to generate logs.
+      # @return [V1] an object with the api version suit.
       def initialize(api_key, host: "live.ecoportal.com", logger: default_logger)
         @logger = logger
         @client = Common::Client.new(
           api_key: api_key,
           host:    host,
-          version: "v1",
+          version: self.class::VERSION,
           logger:  @logger
         )
       end
+
+      # Obtain specific object for people api requests.
+      # @return [People] an instance object ready to make people api requests.
       def people
-        V1::People.new(client)
+        people_class.new(client)
       end
+
+      # Obtain specific object for schema api requests.
+      # @return [PersonSchemas] an instance object ready to make schema api requests.
       def person_schemas
-        V1::PersonSchemas.new(client)
+        person_schemas_class.new(client)
       end
     end
   end
 end
 
-require 'ecoportal/api/v1/people'
 require 'ecoportal/api/v1/person_schemas'
+require 'ecoportal/api/v1/people'

data/lib/ecoportal/api/v1/people.rb

@@ -1,21 +1,36 @@
-require 'ecoportal/api/common/doc_helpers'
 module Ecoportal
   module API
     class V1
+      # @attr_reader client [Common::Client] a `Common::Client` object that holds the configuration of the api connection.
       class People
+        extend Common::BaseClass
         include Enumerable
         include Common::DocHelpers
+
+        class_resolver :person_class,  "Ecoportal::API::V1::Person"
+
         attr_reader :client
 
+        # @param client [Common::Client] a `Common::Client` object that holds the configuration of the api connection.
+        # @return [People] an instance object ready to make people api requests.
         def initialize(client)
           @client = client
         end
 
+        # Iterates all the people of the organization.
+        # @note
+        #   - it ignores the key `page:` of `params:`.
+        #   - `each` is called by `to_a`
+        # @param params [Hash]
+        # @option params [String] :per_page the number of people you get per request.
+        # @option params [String] :q some text to search. Omit this parameter to target all the people.
+        # @yield [person] does some stuff with the person.
+        # @yieldparam person [Person]
         def each(params: {}, &block)
           return to_enum(:each) unless block
           page = 1
           loop do
-            response = @client.get("/people", params: params.merge(page: page))
+            response = client.get("/people", params: params.merge(page: page))
             raise "Request failed." unless response.success?
             response.body["results"].each do |person|
               yield person_class.new(person)
@@ -26,62 +41,84 @@ module Ecoportal
           self
         end
 
-        def get(doc)
-          response = @client.get("/people/"+CGI::escape(get_id(doc)))
-          Common::WrappedResponse.new(response, person_class)
-        end
-
+        # Gets all the people via api requests.
+        # @note it ignores the key `:page` in `params:`.
+        # @param params [Hash]
+        # @option params [Integer] :per_page the number of people you get per request.
+        # @option params [String] :q some text to search.
+        # @return [Array<Person>] the array of people got via api.
         def get_all(params: {})
           each(params: params).to_a
         end
 
+        # Gets a person via api.
+        # @note if the request has `success?` the returned `object.result` gives an object with that `Person`.
+        # @param doc [String, Hash, Person] data containing an `id` (internal or external) of the target person.
+        # @return [WrappedResponse] an object with the api response.
+        def get(doc)
+          response = client.get("/people/"+CGI::escape(get_id(doc)))
+          Common::WrappedResponse.new(response, person_class)
+        end
+
+        # Requests an update of a person via api.
+        # @param doc [Person, Hash] data that at least contains an `id` (internal or external) of the target person.
+        # @return [Response] an object with the api response.
         def update(doc)
           body = get_body(doc)
           id   = get_id(doc)
-          @client.patch("/people/"+CGI::escape(id), data: body)
+          client.patch("/people/"+CGI::escape(id), data: body)
         end
 
+        # Requests to create a person via api.
+        # @param doc [Person, Hash] data that at least contains an `id` (internal or external) of the target person.
+        # @return [Response] an object with the api response.
         def create(doc)
           body = get_body(doc)
-          @client.post("/people", data: body)
+          client.post("/people", data: body)
         end
 
+        # Requests to update an existing person or if it does not exist, to create it, via api.
+        # @param doc [Person, Hash] data that at least contains an `id` (internal or external) of the target person.
+        # @return [Response] an object with the api response.
         def upsert(doc)
           body = get_body(doc)
           id   = get_id(doc)
-          @client.post("/people/"+CGI::escape(id), data: body)
+          client.post("/people/"+CGI::escape(id), data: body)
+        end
+
+        # Requests to completelly remove from an organization an existing person via api.
+        # @param doc [Person, Hash] data that at least contains an `id` (internal or external) of the target person.
+        # @return [Response] an object with the api response.
+        def delete(doc)
+          id = get_id(doc)
+          client.delete("/people/"+CGI::escape(id))
         end
 
+        # Creates a `BatchOperation` and yields it to the given bock.
+        # @yield [batch_op] adds multiple api requests for the current batch.
+        # @yieldparam batch_op [BatchOperation]
         def batch
-          operation = Common::BatchOperation.new("/people", person_class, logger: @client.logger)
+          operation = Common::BatchOperation.new("/people", person_class, logger: client.logger)
           yield operation
           # The batch operation is responsible for logging the output
-          @client.without_response_logging do
-            @client.post("/people/batch", data: operation.as_json).tap do |response|
+          client.without_response_logging do
+            client.post("/people/batch", data: operation.as_json).tap do |response|
               operation.process_response(response)
             end
           end
         end
 
-        def delete(doc)
-          id = get_id(doc)
-          @client.delete("/people/"+CGI::escape(id))
-        end
-
+        # Creates a new `Person` object.
+        # @return [Person] new empty person object of the current version.
         def new
           person_class.new
         end
 
-        private
-
-        def person_class
-          V1::Person
-        end
       end
     end
   end
 end
 
-require 'ecoportal/api/v1/person'
-require 'ecoportal/api/v1/person_details'
 require 'ecoportal/api/v1/schema_field_value'
+require 'ecoportal/api/v1/person_details'
+require 'ecoportal/api/v1/person'

data/lib/ecoportal/api/v1/person.rb

@@ -1,29 +1,55 @@
 module Ecoportal
   module API
     class V1
+      # @attr id [String] the internal unique id of this person (unique in all the system).
+      # @attr external_id [String] the alternative unique id of this person (unique in one organization).
+      # @attr name [String] the name of the person.
+      # @attr supervisor_id [String] internal or external id of the supervisor of this person.
+      # @attr_reader subordinates [Integer] the number of people this person is supervisor of.
+      # @attr details [PersonDetails, nil] the details of the person or `nil` if missing.
       class Person < Common::BaseModel
-        passthrough :id, :external_id, :name, :email, :supervisor_id, :subordinates, to: :doc
+        passthrough :id, :external_id, :name, :email, :supervisor_id, :subordinates
 
+        class_resolver :person_schema_class,  "Ecoportal::API::V1::PersonSchema"
+        class_resolver :person_details_class, "Ecoportal::API::V1::PersonDetails"
+        embeds_one :details, nullable: true, klass: :person_details_class
+
+        # Gets the supervisor (`Person`) of this person, with given his `supervisor_id`.
+        #
+        # **Example Usage**:
+        # ```ruby
+        # API_KEY = 'some-private-api-key-version'
+        # HOST    = "live.ecoportal.com"
+        # api     = Ecoportal::API::Internal.new(API_KEY, host: HOST)
+        # person  = api.people.get({"id": "my-dummy-user"})
+        # super   = person.supervisor(api.client)
+        # pp "#{person.name}'s supervisor is #{super.name}."
+        # ```
+        #
+        # @param client [Common::Client] the api client to make the request.
         def supervisor(client)
           return @supervisor if defined?(@supervisor)
           return @supervisor = nil if supervisor_id.nil?
           @supervisor = client.people.get(supervisor_id).result
         end
 
+        # Sets the supervisor of a person.
+        # @param person [Person, nil] the supervisor of this person.
         def supervisor=(person)
-          self.supervisor_id = person.id
+          self.supervisor_id = person&.id || person&.external_id
         end
 
         def as_json
           super.merge "details" => details&.as_json
         end
 
-        def details
-          return @details if defined?(@details)
-          return @details = nil if doc["details"].nil?
-          @details = person_details_class.new(doc["details"])
-        end
-
+        # Sets the PersonDetails to the person, depending on the paramter received:
+        #  - `nil`: blanks the details.
+        #  - `PersonDetails`: sets a copy of the object param as details.
+        #  - `Hash`: sets respectivelly the `schema_id` and the `fields` keys of the Hash to the person details.
+        # @note unique point of access to update the PersonDetails.
+        # @param value [nil, PersonDetails, Hash] value to be set.
+        # @return [nil, PersonDetails] the resulting `PersonDetails` set to the person.
         def details=(value)
           case value
           when NilClass
@@ -33,15 +59,20 @@ module Ecoportal
           when Hash
             doc["details"] = value.slice("schema_id", "fields")
           else
-            raise "Invalid set on details: Need nil, PersonDetails or Hash; got #{value.class}"
+            raise "Invalid type set on details. Required nil, PersonDetails or Hash; got #{value.class}"
           end
           remove_instance_variable("@details") if defined?(@details)
-          details.tap do |details|
-            # When reassigning details, mark the whole thing as dirty
-            details&.instance_variable_set("@original_doc", {})
-          end
         end
 
+        # Sets the PersonDetails to the person, depending on the parameter received:
+        #  - `PersonSchema`: initializes the `PersonDetails` as per the schema specified (`schema_id` and `fields`).
+        #  - `String`: it just sets the `schema_id` on the `PersonDetails` (as `fields` is not include, `details[key]=` will throw error).
+        # (see #details=)
+        # @note
+        #   - this method alone only sets the internal structure of the details.
+        #   - you will not be able to `reset!` after using this method.
+        # @param schema_or_id [PersonSchema, String,  nil, PersonDetails, Hash] value to be set.
+        # @return [nil, PersonDetails] the resulting `PersonDetails` that set to the person.
         def add_details(schema_or_id)
           person_details_class.new.tap do |new_details|
             case schema_or_id
@@ -49,29 +80,17 @@ module Ecoportal
               schema_or_id.initialize_details(new_details)
             when String
               new_details.schema_id = schema_or_id
+            else
+              raise "Invalid set on details: Requierd PersonSchema or String; got #{schema_or_id.class}"
             end
             self.details = new_details
             # Patch out static data from as_update
-            @original_doc["details"] = {
+            original_doc["details"] = {
               "fields" => JSON.parse(doc["details"]["fields"].to_json)
             }
           end
-          self.details.tap do |details|
-            # Patch out static data from as_update
-            original = details.instance_variable_get("@original_doc")
-            original["fields"] = JSON.parse(doc["details"]["fields"].to_json)
-          end
         end
 
-        private
-
-        def person_schema_class
-          V1::PersonSchema
-        end
-
-        def person_details_class
-          V1::PersonDetails
-        end
       end
     end
   end

data/lib/ecoportal/api/v1/person_details.rb

@@ -2,17 +2,24 @@ module Ecoportal
   module API
     class V1
       class PersonDetails < Common::BaseModel
-        passthrough :schema_id, to: :doc
+        passthrough :schema_id
+
+        class_resolver :schema_field_value_class, "Ecoportal::API::V1::SchemaFieldValue"
 
         def as_json
           super.merge "fields" => fields.map(&:as_json)
         end
 
+        # Sets the `id` of the PersonDetails.
+        # @note unless the new `id` is `nil`, this does not reset the `fields`.
+        # @param value [nil, String] the id of the schema.
         def schema_id=(value)
           @fields          = [] if value.nil?
           doc["schema_id"] = value
         end
 
+        # Gets all the fields of the PersonDetails.
+        # @return [Array<SchemaFieldValue>] the array of fields of the schema.
         def fields
           return @fields if defined?(@fields)
           @fields = (doc["fields"] || []).map do |field|
@@ -20,24 +27,24 @@ module Ecoportal
           end
         end
 
-        def index_fields
-          @fields_by_id     = {}
-          @fields_by_alt_id = {}
-          fields.each do |wrapped|
-            @fields_by_id[wrapped.id] = wrapped
-            @fields_by_alt_id[wrapped.alt_id] = wrapped
-          end
-        end
-
+        # Gets one specific field of the PersonDetails.
+        # @param id [String] the `id` or the `alt_id` of the target field.
+        # @return [nil, SchemaFieldValue] the field or `nil` if missing.
         def get_field(id)
           @fields_by_id or index_fields
           @fields_by_id[id] || @fields_by_alt_id[id]
         end
 
+        # Gets the value of one specific field of the PersonDetails.
+        # @param id [String] the `id` or the `alt_id` of the target field.
+        # @return [String, Array<String>, Boolean, Array<Boolean>, Date, Array<Date>, Numberic, Array<Numeric>] the value of field or `nil` if missing.
         def [](id)
           get_field(id)&.value
         end
 
+        # Sets the value to one specific field of the PersonDetails.
+        # @param id [String] the `id` or the `alt_id` of the target field.
+        # @return [void]
         def []=(id, value)
           if field = get_field(id)
             field.value = value
@@ -46,11 +53,18 @@ module Ecoportal
           end
         end
 
-        private
+        protected
 
-        def schema_field_value_class
-          V1::SchemaFieldValue
+        # Rebuilds the internal `id` and `alt_id` references to the fields.
+        def index_fields
+          @fields_by_id     = {}
+          @fields_by_alt_id = {}
+          fields.each do |wrapped|
+            @fields_by_id[wrapped.id] = wrapped
+            @fields_by_alt_id[wrapped.alt_id] = wrapped
+          end
         end
+
       end
     end
   end

data/lib/ecoportal/api/v1/person_schema.rb

@@ -2,7 +2,9 @@ module Ecoportal
   module API
     class V1
       class PersonSchema < Common::BaseModel
-        passthrough :id, :name, to: :doc
+        passthrough :id, :name
+
+        class_resolver :schema_field_class, "Ecoportal::API::V1::SchemaField"
 
         def fields
           @fields_by_id or index_fields
@@ -43,11 +45,6 @@ module Ecoportal
           end
         end
 
-        private
-
-        def schema_field_class
-          V1::SchemaField
-        end
       end
     end
   end