ecoportal-api-oozes 0.7.0 → 0.7.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5cb0d1b8ffc0213cf73870b6e1947fddf97633b2156c8f77199195041fda9656
-  data.tar.gz: 0d59146cdd6ad87b710333c165ee5c2a704db9dafdfe89d4c056388bc6ed0394
+  metadata.gz: 5929f4395b13bbc49387e6df11b391d868533454b9c4e7a8a82059471dcc0c3e
+  data.tar.gz: 3dec1899afedfa10558c61cd24e3d2e2717bcaa2173284c960b93e1317ba74c8
 SHA512:
-  metadata.gz: 760f145f8caaca3e50e9ec063f7876bcec24ab0427b4ba72307e026d83cd9510c4b8a91d263d06bdd60038d92b51ef350f52c53ba02c9bb45ba7d47a793656cf
-  data.tar.gz: c3c42a6d60e77b23c8228f1d60320947a7884abae78e89439c8cfd721e9da5a39fe111b701f3549d07d13ffc2488defc3494b79ab44708ff59a511f669c0cd68
+  metadata.gz: 5ddfa85f7e4a424b421ef9f4163d7d3f97dc4f25c049bb04e8971472efb3fdc9857ba4b3d0cde701b09e8bb6add6bdb0c046be7e6609b8c6985e8fff36397c04
+  data.tar.gz: 99459754a151c61633212238c23d77cfc0fb3999ca5bf4fd5be6ee01219399f8d32fbc9b16b66fb84678fca4623edcaa1ebcd7d2a4a52b09f643111ab897f7c9

data/CHANGELOG.md

@@ -1,7 +1,109 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
-## [0.7.0] - 2020-07-xx
+## [0.7.5] - 2021-02-xx
+
+### Added
+  - `Ecoportal::API::Common::ClassHelpers` added inheritable attribute values
+  - `Ecoportal::API::V2::Pages::PageStage` added missing properties
+  - `Ecoportal::API::V2::Page::Stages#ordered_stages` method to obtain stages in order
+  - `Ecoportal::API::V2::Registers#search` method search pages in the register, which includes new classes:
+    - `Ecoportal::API::V2::Registers::PageResult`
+    - `Ecoportal::API::V2::Registers::StagesResult`
+    - `Ecoportal::API::V2::Registers::StageResult`
+  - `Ecoportal::API::V2::Pages#get` added parameter `stage_id:` to be able to directly obtain the stage
+
+### Changed
+  - Moved some classes to the new namespace `Ecoportal::API::V2::Registers`
+    - `Ecoportal::API::V2::Registers::Register`
+    - `Ecoportal::API::V2::Registers::Template`
+
+### Fixed
+  - `Ecoportal::API::Common::Content::HashDiffPatch`: `deleted` operation wording and `data.patch_ver`
+  - `Ecoportal::API::V2::Page::Component.new_doc` should delegate to child classes that have their own implementation
+    - `Ecoportal::API::V2::Page::Component::ImagesField.new_doc` should include `layout`
+    - `Ecoportal::API::V2::Page::Component::SignatureField.new_doc` should include `color`
+
+## [0.7.4] - 2021-02-12
+
+### Added
+  - `Ecoportal::API::V2::Page::Component::GaugeStop#color=` enabled setting colours using a `symbol`
+    - `:blue`, `:blue_greyed`, `:blue_light`
+    - `:turquoise`, `:jade`, `:green`, `:pistachio`, `:avocado`
+    - `:yellow`, `:orange`, `:pumpkin`, `:red`, `:magenta`, `:fuchsia`, `:purple`, `:violet`
+  - `Ecoportal::API::V2::Page::Component::GaugeStop#color_sym` to get the color as `symbol` name
+  - added support for chart fields:
+    - `Ecoportal::API::V2::Page::Component::ChartField` with the different `mode` types
+    - `Ecoportal::API::V2::Page::Component::ChartFrField` (LTIFR)
+
+### Changed
+  - `Ecoportal::API::Page::Component::DateField` Date objects + Timezones
+    - `#value` should be shown in local time
+    - `#value=` should be set by local time
+  - `Ecoportal::API::Common::Content::DoubleModel.embeds_multiple` renamed to `embeds_many`
+  - `Ecoportal::API::Common::Content::DoubleModel.embeds_one` removed parameter `:multiple`
+  - Fields under `Ecoportal::API::Page::Component` that `embeds_many` should generate new elements in a standard way
+    - added `Ecoportal::API::Common::Content::CollectionModel#items_class` method
+
+### Fixed
+  - solved `pretty_print` name collision renaming to `Ecoportal::API::Common::Content::DoubleModel#print_pretty`
+
+## [0.7.3] - 2021-02-01
+
+### Added
+  - `Ecoportal::API::Common::Content::CollectionModel#delete!` finally scoped how delete should work :)
+  - `Ecoportal::API::V2.new` better feedback on key error.
+  - `Ecoportal::API::V2::Page::Component::SignatureField` added property `signed_by_name`
+  - `Ecoportal::API::V2::Page::Component#required` this field property is currently supported
+  - `Ecoportal::API::V2::Page::Component::DateField` more supported properties:
+    * `show_time`, `today_button`, `past_only`, `create_event`, `remind_me_in`, `renews`, `renews_every`, `renews_unit`, `renews_until`
+  - `Ecoportal::API::V2::Page::Component::ChecklistField`
+    * added more methods: `add_item`, `ordered_items`
+  - `Ecoportal::API::V2::Page::Component::GaugeField`
+    * more supported properties: `max`, `active_color` and `stops`
+      - for `stops` added class `Ecoportal::API::V2::Page::Component::GaugeStop`
+    * added more methods: `add_stop`, `ordered_stops`
+  - `Ecoportal::API::V2::Page::Component::ReferenceField` more supported properties:
+    * `register_id`, `hide_create`, `hide_attach`, `hide_metadata`, `hide_dashboards`, `display_fields`, `display_fields_in_lookup`
+  - `Ecoportal::API::V2::Page::Component::ActionField`
+    * more supported properties:`create_actions`, `required_number_of_completed_actions`, `permits_and_rules_integration`, `add_subscribed`, `add_subscribed_to_tasks`
+    * added more methods: `add_task`, `ordered_tasks`
+    - `Ecoportal::API::V2::Page::Component::Action` modified, provided that some properties are `read_only`
+  - `Ecoportal::API::V2::Page::Component::PeopleField` more supported properties:
+    * `is_me_button`, `attach_mode`, `person_schema_id`, `viewable_fields`, `singular`, `requires_number`, `cached_people`, `attached_people_permissions_enabled`, `apply_attached_people_permissions_to`, `attached_people_permissions_editable`, `attached_people_permissions_flags`
+  - `Ecoportal::API::V2::Page::Component::PlainTextField` more supported properties:
+    * `multiline`, `max_length`, `exact_index`
+  - `Ecoportal::API::V2::Page::Component::SelectionField` more supported properties:
+    * `flat`
+  - `Ecoportal::API::V2::Page::Component::TagField` more supported properties:
+    * `single_select`, `use_defaults`, `tag_tree_id`, `button_text`
+  - `Ecoportal::API::V2::Page::Section` more supported properties:
+    * `minimized`
+
+### Changed
+  - upgraded `ecoportal-api` dependency
+
+### Fixed
+  - `Ecoportal::API::Common::Content::CollectionModel#upsert!` was not actually moving the element to the new position when it already existed
+
+## [0.7.2] - 2020-10-07
+
+### Added
+  - automatic key builder
+    - helper: `Ecoportal::API::V2::v2key` method
+    - `user_key:` and `org_key:` as constructor methods for `Ecoportal::API::V2`
+### Changed
+### Fixed
+
+## [0.7.1] - 2020-10-07
+
+### Added
+### Changed
+  - updated dependencies
+### Fixed
+
+
+## [0.7.0] - 2020-09-10
 
 ### Added
 ### Changed

data/README.md

@@ -1,3 +1,5 @@
+**Moved to ---> 'ecoportal-api-v2'**
+
 # Ecoportal::API::V2
 
 This is a basic collection of helpers that can be used to interact with the

data/ecoportal-api-oozes.gemspec

@@ -13,6 +13,8 @@ Gem::Specification.new do |spec|
   spec.homepage      = "https://www.ecoportal.com"
   spec.licenses      = %w[MIT]
 
+  spec.required_ruby_version = '>= 2.4.4'
+
   spec.files         = `git ls-files -z`.split("\x0").reject do |f|
     f.match(%r{^(test|spec|features)/})
   end
@@ -20,12 +22,17 @@ 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",   "~> 2.1"
-  spec.add_development_dependency "rake",      "~> 12.0"
-  spec.add_development_dependency "rspec",     "~> 3.0"
-  spec.add_development_dependency "yard",      "~> 0.9", ">= 0.9.18"
-  spec.add_development_dependency "redcarpet", "~> 3.5", ">= 3.5.0"
+  spec.add_development_dependency "bundler",   ">= 2.1.3",  "< 2.2"
+  spec.add_development_dependency "rspec",     ">= 3.9",    "< 4"
+  spec.add_development_dependency "rake",      ">= 12.3.0", "< 13"
+  spec.add_development_dependency "yard",      ">= 0.9.18", "< 0.10"
+  spec.add_development_dependency "redcarpet", ">= 3.5.0",  "< 3.6"
   spec.add_development_dependency "pry"
 
-  spec.add_dependency 'ecoportal-api',  '~> 0.7', '>= 0.6.0'
+  spec.add_dependency 'ecoportal-api', '>= 0.7.4', '< 0.8'
+
+  spec.post_install_message = %{
+    The 'ecoportal-api-oozes' gem has been deprecated and has been replaced by 'ecoportal-api-v2'.
+    See: https://rubygems.org/gems/ecoportal-api-v2
+  }
 end

data/lib/ecoportal/api/common/content/class_helpers.rb

@@ -104,6 +104,41 @@ module Ecoportal
             val != NOT_USED
           end
 
+          # Keeps track on class instance variables that should be inherited by child classes.
+          # @note
+          #   - subclasses will inherit the value as is at that moment
+          #   - any change afterwards will be only on the specific class (in line with class instance variables)
+          #   - adapted from https://stackoverflow.com/a/10729812/4352306
+          # TODO: this separates the logic of the method to the instance var. Think if would be possible to join them somehow.
+          def inheritable_class_vars(*vars)
+            @inheritable_class_vars ||= [:inheritable_class_vars]
+            @inheritable_class_vars += vars
+          end
+
+          # Builds the attr_reader and attr_writer of `attrs` and registers the associated instance variable as inheritable.
+          def inheritable_attrs(*attrs)
+            attrs.each do |attr|
+              class_eval %(
+                class << self; attr_accessor :#{attr} end
+              )
+            end
+            inheritable_class_vars(*attrs)
+          end
+
+          # This callback method is called whenever a subclass of the current class is created.
+          # @note
+          #   - values of the instance variables are copied as they are (no dups or clones)
+          #   - the above means: avoid methods that change the state of the mutable object on it
+          #   - mutating methods would reflect the changes on other classes as well
+          #   - therefore, `freeze` will be called on the values that are inherited.
+          def inherited(subclass)
+            inheritable_class_vars.each do |var|
+              instance_var = instance_variable_name(var)
+              value        = instance_variable_get(instance_var)
+              subclass.instance_variable_set(instance_var, value.freeze)
+            end
+          end
+
         end
       end
     end

data/lib/ecoportal/api/common/content/collection_model.rb

@@ -101,6 +101,11 @@ module Ecoportal
             super(ini_doc, parent: parent, key: key)
           end
 
+          # @return [Class] the class of the elements of the Collection
+          def items_class
+            self.class.klass
+          end
+
           # Transforms `value` into the actual `key` to access the object in the doc `Array`
           def _doc_key(value)
             #print "*(#{value.class})"
@@ -134,6 +139,7 @@ module Ecoportal
             end
           end
 
+          # Get an element usign the `key`.
           def [](value)
             items_by_key[get_key(value)]
           end
@@ -161,6 +167,15 @@ module Ecoportal
             end
           end
 
+          def delete!(value)
+            unless value.is_a?(Hash) || value.is_a?(Content::DoubleModel)
+              raise "'Content::DoubleModel' or 'Hash' doc required"
+            end
+            if item = self[value]
+              _doc_delete(item.doc)
+            end
+          end
+
           protected
 
           def order_matters?; self.class.order_matters; end
@@ -220,6 +235,13 @@ module Ecoportal
             super
           end
 
+          def _doc_delete(value)
+            if current_pos = _doc_key(value)
+              _doc_items.delete_at(current_pos)
+              on_change
+            end
+          end
+
           def _doc_upsert(value, pos: NOT_USED, before: NOT_USED, after: NOT_USED)
             current_pos = _doc_key(value)
             pos = case
@@ -228,7 +250,7 @@ module Ecoportal
               when used_param?(before)
                 _doc_key(before)
               when used_param?(after)
-                puts "to add after #{after.id}"
+                #puts "to add after #{after.id}"
                 if i = _doc_key(after)
                   i + 1
                 end
@@ -237,10 +259,10 @@ module Ecoportal
             pos ||= current_pos
 
             if current_pos && pos
-              _doc_items.delete(current_pos)
+              _doc_items.delete_at(current_pos)
               pos = (pos <= current_pos)? pos : pos - 1
             end
-            
+
             pos = (pos && pos < _doc_items.length)? pos : _doc_items.length
 
             pos.tap do |i|

data/lib/ecoportal/api/common/content/double_model.rb

@@ -131,7 +131,32 @@ module Ecoportal
             end
 
             # Helper to embed one nested object under one property
-            def embeds_one(method, key: method, nullable: false, multiple: false, klass:)
+            def embeds_one(method, key: method, nullable: false, klass:)
+              embed(method, key: key, nullable: nullable, multiple: false, klass: klass)
+            end
+
+            # @note
+            #   - if you have a dedicated `Enumerable` class to manage `many`, you should use `:enum_class`
+            #   - otherwise, just indicate the child class in `:klass` and it will auto generate the class
+            # @param
+            def embeds_many(method, key: method, order_matters: false, order_key: nil, klass: nil, enum_class: nil)
+              if enum_class
+                eclass = enum_class
+              elsif klass
+                eclass = new_class(method, inherits: Common::Content::CollectionModel) do |dim_class|
+                  dim_class.klass         = klass
+                  dim_class.order_matters = order_matters
+                  dim_class.order_key     = order_key
+                end
+              else
+                raise "You should either specify the 'klass' of the elements or the 'enum_class'"
+              end
+              embed(method, key: key, multiple: true, klass: eclass)              
+            end
+
+            private
+
+            def embed(method, key: method, nullable: false, multiple: false, klass:)
               method = method.to_s.freeze
               var    = instance_variable_name(method).freeze
               k      = key.to_s.freeze
@@ -150,16 +175,6 @@ module Ecoportal
               end
             end
 
-            def embeds_multiple(method, key: method, order_matters: false, order_key: nil, klass:)
-              dim_class = new_class(method, inherits: Common::Content::CollectionModel) do |dklass|
-                dklass.klass         = klass
-                dklass.order_matters = order_matters
-                dklass.order_key     = order_key
-              end
-
-              embeds_one(method, key: key, multiple: true, klass: dim_class)
-            end
-
           end
 
           attr_reader :_parent, :_key
@@ -252,7 +267,7 @@ module Ecoportal
             end
           end
 
-          def pretty_print
+          def print_pretty
             puts JSON.pretty_generate(as_json)
             self
           end

data/lib/ecoportal/api/common/content/hash_diff_patch.rb

@@ -60,8 +60,13 @@ module Ecoportal
               a == b
             end
 
-            def patch_data(a, b = nil)
+            def patch_data(a, b = nil, delete: false)
               {}.tap do |data_hash|
+                if delete
+                  patch_ver = (a && a["patch_ver"]) || 1
+                  data_hash["patch_ver"] = patch_ver
+                  next
+                end
                 a.each do |key, a_value|
                   b_value = b[key] if b_has_key = b && b.key?(key)
                   is_meta_key = META_KEYS.include?(key)
@@ -83,7 +88,8 @@ module Ecoportal
               return NO_CHANGES unless b.is_a?(Hash) && id = get_id(b, exception: false)
               {
                 "id"        => id,
-                "operation" => "delete"
+                "operation" => "deleted",
+                "data"      => patch_data(b, delete: true)
               }
             end
 

data/lib/ecoportal/api/common/content/wrapped_response.rb

@@ -27,7 +27,7 @@ module Ecoportal
           def data
             return @data if instance_variable_defined?(:@data)
             @data = (response.body || {})["data"]
-            @data = @data[key] if @key && @data
+            @data = @data[@key] if @key && @data
             @data
           end
 

data/lib/ecoportal/api/v2.rb

@@ -1,3 +1,5 @@
+require 'base64'
+
 module Ecoportal
   module API
     # @attr_reader client [Common::Client] a `Common::Client` object that holds the configuration of the api connection.
@@ -8,25 +10,48 @@ module Ecoportal
 
       VERSION = "v2"
 
+      class << self
+        def v2key (ukey, gkey)
+          Base64.urlsafe_encode64({
+            organization: gkey,
+            user:         ukey
+          }.to_json)
+        end
+      end
+
+      class_resolver :people_class,    "Ecoportal::API::V2::People"
       class_resolver :registers_class, "Ecoportal::API::V2::Registers"
       class_resolver :pages_class,     "Ecoportal::API::V2::Pages"
 
       attr_reader :client, :logger
 
       # Creates an `V2` object to scope version specific api requests.
+      # @note
+      #   - You should use either `api_key` or `user_key` and `org_key`
+      #   - The const `VERSION` determineds the api version that client will query against.
+      #   - This means that each subclass of `V2` should define their own `VERSION` constant.
       # @param api_key [String] the key version to stablish the api connection.
+      # @param user_key [String] the user key used for the api connection (requires `org_key`).
+      # @param org_key [String] the org key used for the api connection (requires `user_key`).
       # @param host [String] api server domain.
       # @param logger [Logger] an object with `Logger` interface to generate logs.
-      def initialize(api_key, host: "live.ecoportal.com", logger: default_logger)
+      def initialize(api_key = nil, user_key: nil, org_key: nil, host: "live.ecoportal.com", logger: default_logger)
+        v2key   = get_key(api_key: api_key, user_key: user_key, org_key: org_key)
         @logger = logger
         @client = Common::Content::Client.new(
-          api_key: api_key,
+          api_key: v2key,
           host:    host,
           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
+        people_class.new(client)
+      end
+
       # Obtain specific object for schema api requests.
       # @return [Registers] an instance object ready to make registers api requests.
       def registers
@@ -39,9 +64,19 @@ module Ecoportal
         pages_class.new(client)
       end
 
+      private
+
+      def get_key(api_key: nil, user_key: nil, org_key: nil)
+        return self.class.v2key(user_key, org_key) if user_key && org_key
+        return api_key if api_key #|| ENV['X_ECOPORTAL_API_KEY']
+        raise "You need to provide either an api_key or user_key" unless user_key
+        raise "You need to provide an org_key as well (not just a user_key)" unless org_key
+      end
+
     end
   end
 end
 
-require 'ecoportal/api/v2/registers'
+require 'ecoportal/api/v2/people'
 require 'ecoportal/api/v2/pages'
+require 'ecoportal/api/v2/registers'