ecoportal-api-oozes 0.5.5 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f6ecefc83d30f273a4ededb781765cde494d5e6e0facad8a501fc6ef023e73ee
-  data.tar.gz: b1e0b4dab879d237580bb4d599ea500fe7a5154f6f7f874e418360bfefc9700d
+  metadata.gz: 65d013d143d1c5dc7b19de58086d973dedc454dbdc89f4ac1d5525e58342c457
+  data.tar.gz: f083e27753e51add116d0aeb12ebc13632dc1834a42e5b690f0da353216b2f4f
 SHA512:
-  metadata.gz: 98694b883b97f35fc71c0633717d92ec9da2704bd6d63c824a38c43eca512645ab6f3ecd77924d41ae527d112ffc36fcc4190f82e06b4b6453d21ccca44de22d
-  data.tar.gz: 9ef14de17795590c48d3b3cb0a6e2ba96be3b1d1ff76cee959a1860cbf1689d17b0551842352b7326094d1c8071a8569cf58c6b8feb5dd8933da8cd6a69521fc
+  metadata.gz: 90b0d48b663d8698b33e56d113a44b84197a48fc47b29640abae653fe4b49740bc975fb6e0781e24dea5ee5bc3a29dababafab008adc893c13fda0157ae91793
+  data.tar.gz: af2a47022b66bc5238b2c5a3235c192d5f164493d221d3f94c95f3156962dcbdb5749376abc8218cd8023d84b03c6a31fd8c23d54c2324f815c4e41b3e464041

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Change Log
+All notable changes to this project will be documented in this file.
+
+## [0.6.0] - 2020-07-xx
+
+### Added
+### Changed
+  - upgraded `ecoportal-api` gem
+### Fixed
+
+## [0.5.9] - 2020-07-02
+
+### Added
+  - helper `Ecoportal::API::Common::Content::StringDigest#indexable_label`: to see the part of a label that gets indexed
+  - this `CHANGELOG.md` file
+### Changed
+### Fixed

data/ecoportal-api-oozes.gemspec

@@ -5,7 +5,7 @@ require "ecoportal/api/v2/version"
 
 Gem::Specification.new do |spec|
   spec.name          = "ecoportal-api-oozes"
-  spec.version       = Ecoportal::API::V2::VERSION
+  spec.version       = Ecoportal::API::V2::GEM_VERSION
   spec.authors       = ["Oscar Segura"]
   spec.email         = ["rien@ecoportal.co.nz", "oscar@ecoportal.co.nz", "bozydar@ecoportal.co.nz"]
 
@@ -27,5 +27,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "redcarpet", "~> 3.5", ">= 3.5.0"
   spec.add_development_dependency "pry"
 
-  spec.add_dependency 'ecoportal-api',  '~> 0.5', '>= 0.5.5'
+  spec.add_dependency 'ecoportal-api',  '~> 0.6', '>= 0.6.0'
 end

data/lib/ecoportal/api-oozes.rb

@@ -6,5 +6,5 @@ module Ecoportal
   end
 end
 
-require "ecoportal/api/common"
-require "ecoportal/api/v2"
+require_relative "api/common"
+require_relative "api/v2"

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

@@ -219,7 +219,6 @@ module Ecoportal
             end
           end
 
-          # TODO
           def insert_one(value, pos: NOT_USED, before: NOT_USED, after: NOT_USED)
             i = index(value)
             return i if (i && uniq?)

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

@@ -145,18 +145,20 @@ module Ecoportal
           # Tries to find the element `value`, if it exists, it updates it
           # Otherwise it pushes it to the end
           # @return the element
-          def upsert!(value)
+          def upsert!(value, pos: NOT_USED, before: NOT_USED, after: NOT_USED)
             unless value.is_a?(Hash) || value.is_a?(Content::DoubleModel)
               raise "'Content::DoubleModel' or 'Hash' doc required"
             end
             item_doc = value.is_a?(Content::DoubleModel)? value.doc : value
+            item_doc = JSON.parse(item_doc.to_json)
             if item = self[value]
-              item.replace_doc(JSON.parse(item_doc.to_json))
+              item.replace_doc(item_doc)
             else
-              item = new_item(item_doc)
-              _doc_items << item.doc
+              _doc_upsert(item_doc, pos: pos, before: before, after: after)
+            end
+            (item || self[item_doc]).tap do |item|
+              yield(item) if block_given?
             end
-            item
           end
 
           protected
@@ -165,6 +167,10 @@ module Ecoportal
           def uniq?;          self.class.uniq;          end
           def items_key;      self.class.items_key;     end
 
+          def on_change
+            variables_remove!
+          end
+
           # Gets the `key` of the object
           def get_key(value)
             case value
@@ -198,11 +204,9 @@ module Ecoportal
             self.class.new_item(value, parent: self)
           end
 
-          private
-
           # Helper to remove tracked down instance variables
           def variable_remove!(key)
-            if (k = get_key(key)) && (item = @items_by_key[k])
+            if @items_by_key && (k = get_key(key)) && (item = @items_by_key[k])
               _items.delete(item) if _items.include?(item)
               @items_by_key.delete(k)
             else
@@ -216,6 +220,36 @@ module Ecoportal
             super
           end
 
+          def _doc_upsert(value, pos: NOT_USED, before: NOT_USED, after: NOT_USED)
+            current_pos = _doc_key(value)
+            pos = case
+              when used_param?(pos)
+                pos
+              when used_param?(before)
+                _doc_key(before)
+              when used_param?(after)
+                puts "to add after #{after.id}"
+                if i = _doc_key(after)
+                  i + 1
+                end
+              end
+
+            pos ||= current_pos
+
+            if current_pos && pos
+              _doc_items.delete(current_pos)
+              pos = (pos <= current_pos)? pos : pos - 1
+            end
+            
+            pos = (pos && pos < _doc_items.length)? pos : _doc_items.length
+
+            pos.tap do |i|
+              _doc_items.insert(pos, value)
+              on_change
+            end
+
+          end
+
         end
       end
     end

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

@@ -1,3 +1,5 @@
+require 'securerandom'
+
 module Ecoportal
   module API
     module Common
@@ -28,6 +30,10 @@ module Ecoportal
               @key = value.to_s.freeze
             end
 
+            def new_uuid(length: 12)
+              SecureRandom.hex(length)
+            end
+
             # Same as `attr_reader` but links to a subjacent `Hash` model property
             # @note it does **not** create an _instance variable_
             def pass_reader(*methods)
@@ -153,6 +159,7 @@ module Ecoportal
 
               embeds_one(method, key: key, multiple: true, klass: dim_class)
             end
+
           end
 
           attr_reader :_parent, :_key
@@ -250,16 +257,6 @@ module Ecoportal
           #  self
           #end
 
-          protected
-
-          def is_root?
-            _parent == self && !!defined?(@doc)
-          end
-
-          def linked?
-            is_root? || !!_parent.doc
-          end
-
           def replace_doc(new_doc)
             raise UnlinkedModel.new(from: "#{self.class}#replace_doc", key: _key) unless linked?
             if is_root?
@@ -271,6 +268,16 @@ module Ecoportal
             end
           end
 
+          protected
+
+          def is_root?
+            _parent == self && !!defined?(@doc)
+          end
+
+          def linked?
+            is_root? || !!_parent.doc
+          end
+
           def replace_original_doc(new_doc)
             raise UnlinkedModel.new(from: "#{self.class}#replace_original_doc", key: _key) unless linked?
             if is_root?
@@ -298,7 +305,7 @@ module Ecoportal
 
           # Removes all the persistent variables
           def variables_remove!
-            @_dim_vars.map {|k| variable_remove!(k)}
+            @_dim_vars.dup.map {|k| variable_remove!(k)}
           end
 
           private

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

@@ -31,6 +31,8 @@ module Ecoportal
             # 3. the `data` property holds the specific changes of the object
             #   - the `patch_ver` (compulsory) is **incremental** (for data integrity)
             #   - the properties that have changed
+            # @note
+            #   * there should not be difference between `null` and `""` (empty string)
             # @param a [Hash] current hash model
             # @param b [Hash] previous hash model
             # @return [Hash] a `patch data`
@@ -51,12 +53,19 @@ module Ecoportal
 
             private
 
+            def equal_values(a, b)
+              if a.is_a?(String) || b.is_a?(String)
+                return true if a.to_s.strip.empty? && b.to_s.strip.empty?
+              end
+              a == b
+            end
+
             def patch_data(a, b = nil)
               {}.tap do |data_hash|
                 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)
-                  skip_equals = b_has_key && a_value == b_value
+                  skip_equals = b_has_key && equal_values(a_value, b_value)
                   next if is_meta_key || skip_equals
                   data_hash[key] = patch_diff(a_value, b_value)
                   data_hash.delete(key) if data_hash[key] == NO_CHANGES
@@ -99,14 +108,19 @@ module Ecoportal
             end
 
             def patch_data_array(a, b)
+              original_b = b
               a ||= []; b ||= []
               if !nested_array?(a, b)
                 if a.length == b.length && (a & b).length == b.length
-                  NO_CHANGES
+                  if original_b
+                    NO_CHANGES
+                  else
+                    a
+                  end
                 else
                   a
                 end
-              else
+              else # array with nested elements
                 a_ids = array_ids(a)
                 b_ids = array_ids(b)
 
@@ -116,19 +130,20 @@ module Ecoportal
 
                 arr_delete = del_ids.map do |id|
                   patch_delete(array_id_item(b, id))
-                end
+                end.compact
 
                 arr_update = oth_ids.map do |id|
                   patch_update(array_id_item(a, id), array_id_item(b, id))
-                end
+                end.compact
 
                 arr_new = new_ids.map do |id|
                   patch_new(array_id_item(a, id))
-                end
+                end.compact
 
                 (arr_delete.concat(arr_update).concat(arr_new)).tap do |patch_array|
                   # remove data with no `id`
                   patch_array.reject! {|item| !item.is_a?(Hash)}
+                  return NO_CHANGES if patch_array.empty?
                 end
               end
             end

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

@@ -7,12 +7,17 @@ module Ecoportal
         module StringDigest
           MAX_HASH_LABEL = 64
 
+          def indexable_label(str)
+            return nil unless str
+            lbl = str.downcase.gsub(/[^A-Za-z]+/,"-").slice(0, MAX_HASH_LABEL)
+            return nil unless lbl.length >= 3
+            lbl
+          end
+
           # Calculates the Hash of the field based on label
           def hash_label(str)
-            return false unless str
-            label = str.downcase.gsub(/[^A-Za-z]+/,"-").slice(0, MAX_HASH_LABEL)
-            return false unless label.length >= 3
-            return "z" +  Digest::MD5.hexdigest(label).slice(0, 8);
+            return nil unless lbl = indexable_label(str)
+            "z" +  Digest::MD5.hexdigest(lbl).slice(0, 8);
           end
 
         end

data/lib/ecoportal/api/v2.rb

@@ -45,4 +45,3 @@ end
 
 require 'ecoportal/api/v2/registers'
 require 'ecoportal/api/v2/pages'
-#require 'ecoportal/api/v2/stages'

data/lib/ecoportal/api/v2/page.rb

@@ -2,6 +2,7 @@ module Ecoportal
   module API
     class V2
       class Page < Common::Content::DoubleModel
+        ALLOWED_KEYS  = %w[id patch_ver name template_id base_tags tags time_zone created_at updated_at can components sections stages]
         passkey     :id
         passthrough :patch_ver
         passthrough :name, :template_id
@@ -17,6 +18,17 @@ module Ecoportal
         embeds_one :components, multiple: true, klass: :components_class
         embeds_one :sections,   multiple: true, klass: :sections_class
         embeds_one :stages,     multiple: true, klass: :stages_class
+
+        def as_update
+          super.tap do |hash|
+            unless !hash
+              hash["data"].select! do |key, value|
+                ALLOWED_KEYS.include?(key)
+              end
+            end
+          end
+        end
+
       end
     end
   end

data/lib/ecoportal/api/v2/page/component.rb

@@ -23,6 +23,13 @@ module Ecoportal
           class_resolver :law_field_class,        "Ecoportal::API::V2::Page::Component::LawField"
 
           class << self
+            def new_doc(type:)
+              {
+                "id"   => new_uuid,
+                "type" => type
+              }
+            end
+
             def get_class(doc)
               if doc.is_a?(Hash)
                 case doc["type"]
@@ -81,6 +88,10 @@ module Ecoportal
             root.sections.find {|sec| sec.component?(id)}
           end
 
+          def indexable_label
+            self.class.indexable_label(label)
+          end
+
         end
       end
     end

data/lib/ecoportal/api/v2/page/component/action_field.rb

@@ -4,8 +4,8 @@ module Ecoportal
       class Page
         class Component
           class ActionField < Page::Component
-            class_resolver :action_class, "Ecoportal::API::V2::Page::Component::Action"
-            embeds_multiple :actions, klass: :action_class, order_key: :weight
+            #class_resolver :action_class, "Ecoportal::API::V2::Page::Component::Action"
+            embeds_multiple :actions, klass: "Ecoportal::API::V2::Page::Component::Action", order_key: :weight
           end
         end
       end

data/lib/ecoportal/api/v2/page/component/checklist_field.rb

@@ -4,8 +4,8 @@ module Ecoportal
       class Page
         class Component
           class ChecklistField < Page::Component
-            class_resolver :checklist_item_class, "Ecoportal::API::V2::Page::Component::ChecklistItem"
-            embeds_multiple :items, klass: :checklist_item_class, order_key: :weight
+            #class_resolver :checklist_item_class, "Ecoportal::API::V2::Page::Component::ChecklistItem"
+            embeds_multiple :items, klass: "Ecoportal::API::V2::Page::Component::ChecklistItem", order_key: :weight
           end
         end
       end

data/lib/ecoportal/api/v2/page/component/files_field.rb

@@ -4,8 +4,8 @@ module Ecoportal
       class Page
         class Component
           class FilesField < Page::Component
-            class_resolver :file_class, "Ecoportal::API::V2::Page::File"
-            embeds_multiple :items, klass: :file_class, order_key: :position
+            #class_resolver :file_class, "Ecoportal::API::V2::Page::File"
+            embeds_multiple :items, klass: "Ecoportal::API::V2::Page::File", order_key: :position
           end
         end
       end

data/lib/ecoportal/api/v2/page/component/images_field.rb

@@ -4,8 +4,8 @@ module Ecoportal
       class Page
         class Component
           class ImagesField < Page::Component
-            class_resolver :image_class, "Ecoportal::API::V2::Page::Image"
-            embeds_multiple :images, klass: :image_class, order_key: :weight
+            #class_resolver :image_class, "Ecoportal::API::V2::Page::Image"
+            embeds_multiple :images, klass: "Ecoportal::API::V2::Page::Image", order_key: :weight
           end
         end
       end

data/lib/ecoportal/api/v2/page/component/people_field.rb

@@ -5,6 +5,11 @@ module Ecoportal
         class Component
           class PeopleField < Page::Component
             passarray :people_ids
+
+            def add(id)
+              people_ids << id
+            end
+
           end
         end
       end

data/lib/ecoportal/api/v2/page/component/selection_field.rb

@@ -6,8 +6,69 @@ module Ecoportal
           class SelectionField < Page::Component
             passthrough :multiple, :other, :other_desc
 
-            class_resolver :selection_option_class, "Ecoportal::API::V2::Page::Component::SelectionOption"
-            embeds_multiple :options, klass: :selection_option_class, order_key: :weight
+            #class_resolver :selection_option_class, "Ecoportal::API::V2::Page::Component::SelectionOption"
+            embeds_multiple :options, klass: "Ecoportal::API::V2::Page::Component::SelectionOption", order_key: :weight
+
+            def select(value)
+              opt = options.find {|opt| opt.value == value}
+              sel = selected
+              return true if !multiple && opt == sel
+              sel.selected = false if !multiple && sel
+              opt.selected = true unless !opt
+            end
+
+            def selected
+              if multiple
+                options.select {|opt| opt.selected}
+              else
+                options.find {|opt| opt.selected}
+              end
+            end
+
+            def value
+              if multiple
+                selected.map {|opt| opt.value}
+              else
+                selected&.value
+              end
+            end
+
+            # a server bug prevents to add new options to an existing field
+            def add_option(name:, value:, pos: NOT_USED, before: NOT_USED, after: NOT_USED)
+              opt_doc = Ecoportal::API::V2::Page::Component::SelectionOption.new_doc
+              options.upsert!(opt_doc, pos: pos, before: before, after: after) do |option|
+                option.name  = name
+                option.value = value
+                if prev = previous_option(option)
+                  option.weight = prev.weight
+                end
+                yield(option) if block_given?
+                fix_option_weights!
+              end
+            end
+
+            def ordered_options
+              options.each_with_index.sort_by do |option, index|
+                (option.weight >= 9999) ? [index, index] : [option.weight, index]
+              end.map(&:first)
+            end
+
+            private
+
+            def fix_option_weights!
+              ordered_options.each_with_index do |option, index|
+                option.weight = index
+              end
+            end
+
+            def previous_option(value)
+              opts = ordered_options
+              pos  = opts.index(value) - 1
+              return if pos < 0
+              opts[pos]
+            end
+
+
           end
         end
       end

data/lib/ecoportal/api/v2/page/component/selection_option.rb

@@ -4,6 +4,15 @@ module Ecoportal
       class Page
         class Component
           class SelectionOption < Common::Content::DoubleModel
+            class << self
+              def new_doc
+                {
+                  "id"     => new_uuid,
+                  "weight" => 9999
+                }
+              end
+            end
+
             passkey     :id
             passthrough :patch_ver, :name, :value
             passthrough :weight, :selected

data/lib/ecoportal/api/v2/page/components.rb

@@ -13,6 +13,28 @@ module Ecoportal
 
           order_matters = true
 
+          def get_by_type(type)
+            self.select do |comp|
+              comp.type.downcase == type.to_s.strip.downcase
+            end
+          end
+
+          def get_by_name(name, type: nil)
+            pool = type ? get_by_type(type) : self
+            
+            pool.select do |comp|
+              comp.label.to_s.strip.downcase == name.to_s.strip.downcase
+            end.first
+          end
+
+          def add(label:, type:)
+            fld_doc = Ecoportal::API::V2::Page::Component.new_doc(type: type)
+            upsert!(fld_doc) do |fld|
+              fld.label  = label
+              yield(fld) if block_given?
+            end
+          end
+
         end
       end
     end

data/lib/ecoportal/api/v2/page/section.rb

@@ -3,6 +3,28 @@ module Ecoportal
     class V2
       class Page
         class Section < Common::Content::DoubleModel
+          class << self
+            def new_doc(split: false)
+              {
+                "id"     => new_uuid,
+                "type"   => split ? "split" : "content",
+                "weight" => 9999
+              }.tap do |out|
+                component_ids = if split
+                    {
+                      "left_component_ids" => [],
+                      "right_component_ids" => []
+                    }
+                  else
+                    {
+                      "component_ids" => []
+                    }
+                  end
+                out.merge!(component_ids)
+              end
+            end
+          end
+
           passkey     :id
           passthrough :patch_ver, :weight, :type
           passthrough :heading, :left_heading, :right_heading
@@ -22,9 +44,9 @@ module Ecoportal
           end
 
           def components
-            sec_ids = all_component_ids
-            root.components.values_at(*sec_ids).select.with_index do |fld, i|
-              puts "Warning: section #{id} points to missing field #{sec_ids[i]}" if !fld
+            fld_ids = all_component_ids
+            root.components.values_at(*fld_ids).select.with_index do |fld, i|
+              puts "Warning: field #{id} points to missing field #{fld_ids[i]}" if !fld
               fld && (!block_given? || yield(fld))
             end
           end

data/lib/ecoportal/api/v2/page/sections.rb

@@ -7,6 +7,39 @@ module Ecoportal
 
           self.klass = :section_class
 
+          def add(name: nil, split: false, pos: NOT_USED, before: NOT_USED, after: NOT_USED)
+            sec_doc = Ecoportal::API::V2::Page::Section.new_doc(split: split)
+            upsert!(sec_doc, pos: pos, before: before, after: after) do |section|
+              section.heading  = name
+              if prev = previous_section(section)
+                section.weight = prev.weight
+              end
+              yield(section) if block_given?
+              #fix_weights! # a server bug prevents to set the weight of existing sections
+            end
+          end
+
+          def ordered
+            each_with_index.sort_by do |section, index|
+              (section.weight >= 9999) ? [index, index] : [section.weight, index]
+            end.map(&:first)
+          end
+
+          private
+
+          def fix_weights!
+            ordered.each_with_index do |section, index|
+              section.weight = index
+            end
+          end
+
+          def previous_section(value)
+            secs = ordered
+            pos  = secs.index(value) - 1
+            return if pos < 0
+            secs[pos]
+          end
+
         end
       end
     end

data/lib/ecoportal/api/v2/page/stage.rb

@@ -9,6 +9,19 @@ module Ecoportal
           passarray   :subtags, order_matters: false
           passarray   :section_ids
           passthrough :can
+
+          def sections
+            sec_ids = section_ids.to_a
+            root.sections.values_at(*sec_ids).select.with_index do |sec, i|
+              puts "Warning: section #{id} points to missing section #{sec_ids[i]}" if !sec
+              fld && (!block_given? || yield(sec))
+            end.sort_by {|sec| sec.weight}
+          end
+
+          def attach_section(section)
+            section_ids.insert_one(section.id)
+          end
+
         end
       end
     end

data/lib/ecoportal/api/v2/page/stages.rb

@@ -7,6 +7,12 @@ module Ecoportal
 
           self.klass = :stage_class
 
+          def get_by_name(name)
+            find do |stage|
+              stage.name.strip.downcase == name.to_s.strip.downcase
+            end
+          end
+
         end
       end
     end

data/lib/ecoportal/api/v2/pages.rb

@@ -3,9 +3,11 @@ module Ecoportal
     class V2
       # @attr_reader client [Common::Client] a `Common::Client` object that holds the configuration of the api connection.
       class Pages
+        STAGE_REX = /stages\/(?<sid>.*)/
         extend Common::BaseClass
         include Common::Content::DocHelpers
 
+        class_resolver :stages_class, "Ecoportal::API::V2::Pages::Stages"
         class_resolver :page_class,  "Ecoportal::API::V2::Page"
 
         attr_reader :client
@@ -16,14 +18,30 @@ module Ecoportal
           @client = client
         end
 
+        # Obtain specific object for pages api requests.
+        # @return [V2::Pages::Stages] an instance object ready to make pages api requests.
+        def stages
+          stages_class.new(client)
+        end
+
         # Gets a page via api.
-        # @note if the request has `success?` the returned `object.result` gives an object with that `Page`.
+        # @note
+        #   - if the request has `success?` the returned `object.result` gives an object with that `Page`.
+        #   - if it failed to obtain the full page, it returns a `PageStage` with the active stage data.
         # @param doc [String, Hash, Page] data containing an `id` of the target page.
-        # @return [Ecoportal::API::V2::Page] the target page.
+        # @return [Ecoportal::API::V2::Page, Ecoportal::API::V2::Pages::PageStage] the target page.
         def get(doc)
-          id       = get_id(doc)
-          response = client.get("/pages/#{CGI.escape(id)}")
-          Common::Content::WrappedResponse.new(response, page_class).result
+          pid      = get_id(doc)
+          response = client.get("/pages/#{CGI.escape(pid)}")
+          wrapped  = Common::Content::WrappedResponse.new(response, page_class)
+
+          return wrapped.result if wrapped.success?
+          if (response.status == 302) && (url = response.body["data"])
+            if sid = url_to_stage_id(url)
+              return stages.get(pid: pid, sid: sid)
+            end
+          end
+          raise "Could not get page #{pid} - Error #{response.status}: #{response.body}"
         end
 
         # Gets a `new` non-existing page via api with all the ids initialized.
@@ -32,8 +50,10 @@ module Ecoportal
         def get_new(from)
           id       = get_id(from)
           response = client.get("/pages/new", params: {template_id: id})
-          # TODO: make it so the obtained `doc` can be used as `doc`, yet `source_doc` to be empty {}
-          #Common::Content::WrappedResponse.new(response, page_class).result
+          wrapped  = Common::Content::WrappedResponse.new(response, page_class)
+
+          return wrapped.result if wrapped.success?
+          raise "Could not get new page from template #{id} - Error #{response.status}: #{response.body}"
         end
 
         # Requests a creation of a page via api.
@@ -55,9 +75,16 @@ module Ecoportal
           client.patch("/pages/#{CGI.escape(id)}", data: body)
         end
 
+        private
+
+        def url_to_stage_id(url)
+          (matches = url.match(STAGE_REX)) && matches[:sid]
+        end
+
       end
     end
   end
 end
 
 require 'ecoportal/api/v2/page'
+require 'ecoportal/api/v2/pages/stages'

data/lib/ecoportal/api/v2/pages/page_stage.rb

@@ -0,0 +1,11 @@
+module Ecoportal
+  module API
+    class V2
+      class Pages
+        class PageStage < V2::Page
+          
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/v2/pages/stages.rb

@@ -0,0 +1,52 @@
+module Ecoportal
+  module API
+    class V2
+      class Pages
+        # This API Integration level has been added due to relative permissions
+        #   - a **user** with api access may have access to a specific `stage` but not to the full `page`
+        #
+        # @attr_reader client [Common::Client] a `Common::Client` object that holds the configuration of the api connection.
+        class Stages
+          extend Common::BaseClass
+          include Common::Content::DocHelpers
+
+          class_resolver :page_stage_class,  "Ecoportal::API::V2::Pages::PageStage"
+
+          attr_reader :client
+
+          # @param client [Common::Client] a `Common::Client` object that holds the configuration of the api connection.
+          # @return [Schemas] an instance object ready to make schema api requests.
+          def initialize(client)
+            @client = client
+          end
+
+          # Gets a stage via api.
+          # @note if the request has `success?` the returned `object.result` gives an object with that `Stage`.
+          # @param doc [String, Hash, Stage] data containing an `id` of the target page.
+          # @return [Ecoportal::API::V2::Stage, Ecoportal::API::V2::Pages::PageStage] the target stage.
+          def get(pid:, sid:)
+            pid      = get_id(pid)
+            response = client.get("/pages/#{CGI.escape(pid)}/stages/#{CGI.escape(sid)}/")
+            wrapped  = Common::Content::WrappedResponse.new(response, page_stage_class)
+
+            return wrapped.result if wrapped.success?
+            raise "Could not get stage {#{sid}} of page #{pid} - Error #{response.status}: #{response.body}"
+          end
+
+          # Requests to update an existing stage via api.
+          # @param doc [Hash, Stage] data that at least contains an `id` (internal or external) of the target stage.
+          # @return [Response] an object with the api response.
+          def update(doc, pid: nil, sid:)
+            body = get_body(doc)
+            pid  = pid || get_id(doc)
+            path = "/pages/#{CGI.escape(pid)}/stages/#{CGI.escape(sid)}/"
+            client.patch(path, data: body)
+          end
+
+        end
+      end
+    end
+  end
+end
+
+require 'ecoportal/api/v2/pages/page_stage'

data/lib/ecoportal/api/v2/version.rb

@@ -1,7 +1,7 @@
 module Ecoportal
   module API
     class V2
-      VERSION = "0.5.5"
+      GEM_VERSION = "0.6.0"
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ecoportal-api-oozes
 version: !ruby/object:Gem::Version
-  version: 0.5.5
+  version: 0.6.0
 platform: ruby
 authors:
 - Oscar Segura
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-03-30 00:00:00.000000000 Z
+date: 2020-07-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -110,22 +110,22 @@ dependencies:
   name: ecoportal-api
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.5'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.5.5
+        version: 0.6.0
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.5'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.5.5
+        version: 0.6.0
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
 description: 
 email:
 - rien@ecoportal.co.nz
@@ -140,6 +140,7 @@ files:
 - ".rubocop.yml"
 - ".travis.yml"
 - ".yardopts"
+- CHANGELOG.md
 - Gemfile
 - LICENSE
 - README.md
@@ -189,6 +190,8 @@ files:
 - lib/ecoportal/api/v2/page/stage.rb
 - lib/ecoportal/api/v2/page/stages.rb
 - lib/ecoportal/api/v2/pages.rb
+- lib/ecoportal/api/v2/pages/page_stage.rb
+- lib/ecoportal/api/v2/pages/stages.rb
 - lib/ecoportal/api/v2/register.rb
 - lib/ecoportal/api/v2/registers.rb
 - lib/ecoportal/api/v2/template.rb