ecoportal-api 0.8.5 → 0.9.2

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

@@ -1,135 +1,138 @@
-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, :filter_tags, :freemium
-
-        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
-
-        VALID_TAG_REGEX = /^[A-Za-z0-9 &_'\/-]+$/
-        VALID_EMAIL_REGEX = /^[^@\s]+@[^@\s]+\.[^@\s]+$/
-
-        # 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 || person&.external_id
-        end
-
-        # Sets the email of a person.
-        # @param value [String, nil] the email of this person.
-        def email=(value)
-          unless !value || value.match(VALID_EMAIL_REGEX)
-            raise "Invalid email #{value.inspect}"
-          end
-          doc["email"] = value&.downcase
-        end
-
-        # Validates the string tags of the array, and sets the `filter_tags` property of the account.
-        # @note all is set in upper case and preserves the original order.
-        # @raise [Exception] if there was any invalid string tag.
-        # @param value [Array<String>] array of tags.
-        def filter_tags=(value)
-          unless value.is_a?(Array)
-            raise "filter_tags= needs to be passed an Array, got #{value.class}"
-          end
-          end_tags = value.compact.map do |tag|
-            unless tag.match(VALID_TAG_REGEX)
-              raise "Invalid filter tag #{tag.inspect}"
-            end
-            tag.upcase
-          end
-          set_uniq_array_keep_order("filter_tags", end_tags)
-        end
-
-        # @return [Array<String>] the filter tags of this person.
-        def filter_tags
-          doc["filter_tags"] ||= []
-        end
-
-        def as_json
-          super.merge "details" => details&.as_json
-        end
-
-        def as_update(ref = :last, ignore: [])
-          super(ignore: ignore | ["subordinates"])
-        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
-            doc["details"] = nil
-          when person_details_class
-            doc["details"] = value.as_json
-          when Hash
-            doc["details"] = value.slice("schema_id", "fields")
-          else
-            raise "Invalid type set on details. Required nil, PersonDetails or Hash; got #{value.class}"
-          end
-          remove_instance_variable("@details") if defined?(@details)
-        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
-            when person_schema_class
-              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"] = {
-              "fields" => JSON.parse(doc["details"]["fields"].to_json)
-            }
-          end
-        end
-
-      end
-    end
-  end
-end
+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 contractor_organization_id [String] internal id of the contractor entity 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, :filter_tags
+        passthrough :supervisor_id, :subordinates, :contractor_organization_id
+        passthrough :freemium
+
+        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
+
+        VALID_TAG_REGEX = /^[A-Za-z0-9 &_'\/.-]+$/
+        VALID_EMAIL_REGEX = /^[^@\s]+@[^@\s]+\.[^@\s]+$/
+
+        # 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 || person&.external_id
+        end
+
+        # Sets the email of a person.
+        # @param value [String, nil] the email of this person.
+        def email=(value)
+          unless !value || value.match(VALID_EMAIL_REGEX)
+            raise "Invalid email #{value.inspect}"
+          end
+          doc["email"] = value&.downcase
+        end
+
+        # Validates the string tags of the array, and sets the `filter_tags` property of the account.
+        # @note all is set in upper case and preserves the original order.
+        # @raise [Exception] if there was any invalid string tag.
+        # @param value [Array<String>] array of tags.
+        def filter_tags=(value)
+          unless value.is_a?(Array)
+            raise "filter_tags= needs to be passed an Array, got #{value.class}"
+          end
+          end_tags = value.compact.map do |tag|
+            unless tag.match(VALID_TAG_REGEX)
+              raise "Invalid filter tag #{tag.inspect}"
+            end
+            tag.upcase
+          end
+          set_uniq_array_keep_order("filter_tags", end_tags)
+        end
+
+        # @return [Array<String>] the filter tags of this person.
+        def filter_tags
+          doc["filter_tags"] ||= []
+        end
+
+        def as_json
+          super.merge "details" => details&.as_json
+        end
+
+        def as_update(ref = :last, ignore: [])
+          super(ignore: ignore | ["subordinates"])
+        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
+            doc["details"] = nil
+          when person_details_class
+            doc["details"] = value.as_json
+          when Hash
+            doc["details"] = value.slice("schema_id", "fields")
+          else
+            raise "Invalid type set on details. Required nil, PersonDetails or Hash; got #{value.class}"
+          end
+          remove_instance_variable("@details") if defined?(@details)
+        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
+            when person_schema_class
+              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"] = {
+              "fields" => JSON.parse(doc["details"]["fields"].to_json)
+            }
+          end
+        end
+
+      end
+    end
+  end
+end

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

@@ -1,82 +1,94 @@
-module Ecoportal
-  module API
-    class V1
-      class PersonDetails < Common::BaseModel
-        class MissingId < StandardError
-        end
-
-        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"] || []).each_with_index.map do |field, i|
-            schema_field_value_class.new(field, parent: self, key: ["fields", i])
-          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.
-        # @raise MisssingId if the `id` or `alt_id` is missing.
-        # @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
-          else
-            raise MissingId.new("details[#{id.inspect}] is missing. Did you forget to load the schema?")
-          end
-        end
-
-        # Checks if an `id` or `alt_id` exists
-        # @param id [String] the `id` or the `alt_id` of the target field.
-        # @return [Boolean] `true` if it exists, `false` otherwise
-        def key?(id)
-          @fields_by_id.key?(id) || @fields_by_alt_id.key?(id)
-        end
-
-        protected
-
-        # 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
-end
+module Ecoportal
+  module API
+    class V1
+      class PersonDetails < Common::BaseModel
+        class MissingId < StandardError
+        end
+
+        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"] || []).each_with_index.map do |field, i|
+            schema_field_value_class.new(field, parent: self, key: ["fields", i])
+          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.
+        # @raise MisssingId if the `id` or `alt_id` is missing.
+        # @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
+          else
+            raise MissingId.new("details[#{id.inspect}] is missing. Did you forget to load the schema?")
+          end
+        end
+
+        # Checks if an `id` or `alt_id` exists
+        # @param id [String] the `id` or the `alt_id` of the target field.
+        # @return [Boolean] `true` if it exists, `false` otherwise
+        def key?(id)
+          @fields_by_id or index_fields
+          @fields_by_id.key?(id) || @fields_by_alt_id.key?(id)
+        end
+
+        # @return [Boolean] `true` if `id` exists and `value` has changed, `false` otherwise
+        def changed?(id, doc = :original)
+          return false unless field = get_field(id)
+          field.as_update.key?("value")
+        end
+
+        def original_value(id)
+          return nil unless field = get_field(id)
+          field.original_doc["value"]
+        end
+
+        protected
+
+        # 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
+end

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

@@ -1,53 +1,53 @@
-module Ecoportal
-  module API
-    class V1
-      class PersonSchema < Common::BaseModel
-        passthrough :id, :name
-        passthrough :enable_tags, :tags
-
-        class_resolver :schema_field_class, "Ecoportal::API::V1::SchemaField"
-
-        def fields
-          @fields_by_id or index_fields
-          @fields_by_id.values
-        end
-
-        def fields_by_id
-          @fields_by_id or index_fields
-          @fields_by_id
-        end
-
-        def fields_by_alt_id
-          @fields_by_alt_id or index_fields
-          @fields_by_alt_id
-        end
-
-        def [](id)
-          @fields_by_alt_id or index_fields
-          @fields_by_id[id] || @fields_by_alt_id[id]
-        end
-
-        def index_fields
-          @fields_by_id     = {}
-          @fields_by_alt_id = {}
-          doc["fields"].each do |field|
-            wrapped = schema_field_class.new(field)
-            @fields_by_id[wrapped.id] = wrapped
-            @fields_by_alt_id[wrapped.alt_id] = wrapped
-          end
-        end
-
-        def initialize_details(details)
-          details.schema_id = id
-          details.doc["fields"] = fields.map do |field|
-            field.doc.slice(*%w[id alt_id name multiple type shared]).merge(
-              "value" => field.multiple ? [] : nil
-            )
-          end
-        end
-
-      end
-    end
-  end
-end
-require 'ecoportal/api/v1/schema_field'
+module Ecoportal
+  module API
+    class V1
+      class PersonSchema < Common::BaseModel
+        passthrough :id, :name
+        passthrough :enable_tags, :tags
+
+        class_resolver :schema_field_class, "Ecoportal::API::V1::SchemaField"
+
+        def fields
+          @fields_by_id or index_fields
+          @fields_by_id.values
+        end
+
+        def fields_by_id
+          @fields_by_id or index_fields
+          @fields_by_id
+        end
+
+        def fields_by_alt_id
+          @fields_by_alt_id or index_fields
+          @fields_by_alt_id
+        end
+
+        def [](id)
+          @fields_by_alt_id or index_fields
+          @fields_by_id[id] || @fields_by_alt_id[id]
+        end
+
+        def index_fields
+          @fields_by_id     = {}
+          @fields_by_alt_id = {}
+          doc["fields"].each do |field|
+            wrapped = schema_field_class.new(field)
+            @fields_by_id[wrapped.id] = wrapped
+            @fields_by_alt_id[wrapped.alt_id] = wrapped
+          end
+        end
+
+        def initialize_details(details)
+          details.schema_id = id
+          details.doc["fields"] = fields.map do |field|
+            field.doc.slice(*%w[id alt_id name multiple type shared]).merge(
+              "value" => field.multiple ? [] : nil
+            )
+          end
+        end
+
+      end
+    end
+  end
+end
+require 'ecoportal/api/v1/schema_field'