osm 0.1.17 → 0.2.0

data/lib/osm/model.rb

@@ -42,6 +42,27 @@ module Osm
       id
     end
 
+    # Get a list of attributes which have changed
+    # @return Array[String] the names of attributes which have changed
+    def changed_attributes
+      attributes.keys.select{ |k| attributes[k] != @original_attributes[k] }
+    end
+
+    # Reset the list of attributes which have changed
+    def reset_changed_attributes
+      @original_attributes = attributes
+    end
+
+
+    # Override initialize to set @orig_attributes
+    old_initialize = instance_method(:initialize)
+    define_method :initialize do |*args|
+      ret_val = old_initialize.bind(self).call(*args)
+      @original_attributes = attributes
+      return ret_val
+    end
+
+
     private
     # Wrap cache calls
     def self.cache_read(api, key)
@@ -67,47 +88,116 @@ module Osm
     end
 
 
-    # Get access permission for an API user
-    # @param [Osm::Api] The api to use to make the request
-    # @param [Fixnum, nil] section_id to get permissions for, if nil a Hash of all section's permissions is returned
+    # Raise an exception if the user does not have access to a section
+    # @param [Osm::Api] api The api to use to make the request
+    # @param [Osm::Section, Fixnum, #to_i] section The Section (or its ID) the permission is required on
+    # @!macro options_get
+    # @raise [Osm::Forbidden] If the Api user can not access the section
+    def self.require_access_to_section(api, section, options={})
+      unless api.get_user_permissions(options).keys.include?(section.to_i)
+        raise Osm::Forbidden, "You do not have access to that section"
+      end
+    end
+
+    # Check if the user has access to a section
+    # @param [Osm::Api] api The api to use to make the request
+    # @param [Osm::Section, Fixnum, #to_i] section The Section (or its ID) the permission is required on
+    # @!macro options_get
+    def self.can_access_section?(api, section, options={})
+      api.get_user_permissions(options).keys.include?(section.to_i)
+    end
+
+    # Raise an exception if the user does not have the relevant permission
+    # @param [Osm::Api] api The api to use to make the request
+    # @param [Symbol] to What action is required to be done (e.g. :read or :write)
+    # @param [Symbol] on What the OSM permission is required on (e.g. :member or :programme)
+    # @param [Osm::Section, Fixnum, #to_i] section The Section (or its ID) the permission is required on
+    # @!macro options_get
+    # @raise [Osm::Forbidden] If the Api user does not have the required permission
+    def self.require_permission(api, to, on, section, options={})
+      section_id = section.to_i
+
+      # Check user's permissions in OSM
+      permissions = api.get_user_permissions(options)
+      permissions = permissions[section_id] || {}
+      permissions = permissions[on] || []
+      unless permissions.include?(to)
+        raise Osm::Forbidden, "Your OSM user does not have permission to #{to} on #{on} for #{Osm::Section.get(api, section_id, options).try(:name)}"
+      end
+
+      # Check what the user gave our API
+      permissions = Osm::ApiAccess.get_ours(api, section_id, options).permissions
+      permissions = permissions[on] || []
+      unless permissions.include?(to)
+        raise Osm::Forbidden, "You have not granted the #{to} permissions on #{on} to the #{api.api_name} API for #{Osm::Section.get(api, section_id, options).try(:name)}"
+      end
+    end
+
+    # Raise an exception if the user does not have the relevant permission
+    # @param [Osm::Api] api The api to use to make the request
+    # @param [Symbol] level The OSM subscription level required (e.g. :gold)
+    # @param [Osm::Section, Fixnum, #to_i] section The Section (or its ID) the subscription is required on
     # @!macro options_get
-    # @return [Hash] the permissions Hash
-    def self.get_user_permissions(api, section_id=nil, options={})
-      key = ['permissions', api.user_id]
-      permissions = (!options[:no_cache] && cache_exist?(api, key)) ? cache_read(api, key) : Osm::Section.fetch_user_permissions(api)
-      permissions ||= {}
-      return section_id.nil? ? (permissions || {}) : (permissions[section_id] || {})
-    end
-
-    # Get an access permission for an API user
-    # @param [Osm::Api] The api to use to make the request
-    # @param [Fixnum, nil] section_id to get permissions for, if nil a Hash of all section's permissions is returned
-    # @param [Symbol] permission
+    # @raise [Osm::Forbidden] If the Section does not have the required OSM Subscription (or higher)
+    def self.require_subscription(api, level, section, options={})
+      section = Osm::Section.get(api, section, options) if section.is_a?(Fixnum)
+      if level.is_a?(Symbol) # Convert to Fixnum
+        case level
+        when :bronze
+          level = 1
+        when :silver
+          level = 2
+        when :gold
+          level = 3
+        else
+          level = 0
+        end
+      end
+      if section.nil? || section.subscription_level < level
+        raise Osm::Forbidden, "Insufficent OSM subscription level (#{level} required for #{section.name})"
+      end
+    end
+
+    # Raise an exception if the user does not have the relevant permission
+    # @param [Osm::Api] api The api to use to make the request
+    # @param [Symbol] to What action is required to be done (e.g. :read or :write)
+    # @param [Symbol] on What the OSM permission is required on (e.g. :member or :programme)
+    # @param [Osm::Section, Fixnum, #to_i] section The Section (or its ID) the permission is required on
     # @!macro options_get
-    # @return [Array<Symbol>] the actions the user can perform for the provided permission
-    def self.get_user_permission(api, section_id, permission, options={})
-      permissions = get_user_permissions(api, section_id, options)[permission]
-      return (permissions || [])
+    def self.require_ability_to(api, to, on, section, options={})
+      require_permission(api, to, on, section, options)
+      require_subscription(api, :silver, section, options) if [:register, :contact, :events, :flexi].include?(on)
+      require_subscription(api, :gold, section, options) if [:finance].include?(on)
     end
 
 
-    # Set access permission for an API user
-    # @param [Osm::Api] The api to use to make the request
-    # @param [Fixnum, nil] section_id to set permissions for, if nil the Hash of all section's permissions is set
-    # @param [Hash] permissions the permissions Hash
-    def self.set_user_permissions(api, section_id=nil, permissions)
-      key = ['permissions', api.user_id]
-      if section_id
-        permissions = get_user_permissions(api).merge(section_id => permissions)
+    # Get a list of items given a list of item IDs
+    # @param [Osm::Api] api The api to use to make the request
+    # @param [Array<Fixnum>] ids The ids of the items to get
+    # @param [String] key The key for getting an item from the cache (the key [key, id] is generated)
+    # @param [Array] argumentss The arguments to pass to get_all
+    # @!macro options_get
+    # @param [Symbol] get_all_method The method to get all items (either :get_all or :get_for_section)
+    # @return [Array] An array of the items
+    def self.get_from_ids(api, ids, key, arguments=[], options, get_all_method)
+      raise ArgumentError, "get_al_method is invalid" unless [:get_all, :get_for_section].include?(get_all_method)
+      items = Array.new
+      ids.each do |id|
+        if cache_exist?(api, [key, id])
+          items.push cache_read(api, [*key, id])
+        else
+          # At least this one item is not in the cache - we might as well refresh the lot
+          return self.send(get_all_method, api, *arguments, options.merge(:no_cache => true))
+        end
       end
-      cache_write(api, key, permissions)
+      return items
     end
 
 
     # Make selected class methods instance methods too
     %w{
-      cache_read cache_write cache_exist? cache_delete
-      get_user_permissions get_user_permission set_user_permission
+      cache_read cache_write cache_exist? cache_delete require_access_to_section
+      can_access_section? require_permission require_subscription require_ability_to
     }.each do |method_name|
       define_method method_name do |*options|
         self.class.send(method_name, *options)

data/lib/osm/register.rb

@@ -4,16 +4,17 @@ module Osm
 
     # Get register structure
     # @param [Osm::Api] api The api to use to make the request
-    # @param [Osm::Section, Fixnum] section the section (or its ID) to get the structure for
-    # @param [Osm::Term, Fixnum, nil] section the term (or its ID) to get the structure for, passing nil causes the current term to be used
+    # @param [Osm::Section, Fixnum, #to_i] section The section (or its ID) to get the structure for
+    # @param [Osm::Term, Fixnum, #to_i, nil] term The term (or its ID) to get the structure for, passing nil causes the current term to be used
     # @!macro options_get
     # @return [Array<Osm::Register::Field>] representing the fields of the register
     def self.get_structure(api, section, term=nil, options={})
+      Osm::Model.require_ability_to(api, :read, :register, section, options)
       section_id = section.to_i
       term_id = term.nil? ? Osm::Term.get_current_term_for_section(api, section).id : term.to_i
       cache_key = ['register_structure', section_id, term_id]
 
-      if !options[:no_cache] && Osm::Model.cache_exist?(api, cache_key) && Osm::Model.get_user_permission(api, section_id, :register).include?(:read)
+      if !options[:no_cache] && Osm::Model.cache_exist?(api, cache_key)
         return Osm::Model.cache_read(api, cache_key)
       end
 
@@ -40,16 +41,17 @@ module Osm
 
     # Get register attendance
     # @param [Osm::Api] api The api to use to make the request
-    # @param [Osm::Section, Fixnum] section the section (or its ID) to get the register for
-    # @param [Osm::Term, Fixnum, nil] section the term (or its ID) to get the register for, passing nil causes the current term to be used
+    # @param [Osm::Section, Fixnum, #to_i] section The section (or its ID) to get the register for
+    # @param [Osm::Term, Fixnum, #to_i, nil] term The term (or its ID) to get the register for, passing nil causes the current term to be used
     # @!macro options_get
     # @return [Array<Register::Attendance>] representing the attendance of each member
     def self.get_attendance(api, section, term=nil, options={})
+      Osm::Model.require_ability_to(api, :read, :register, section, options)
       section_id = section.to_i
       term_id = term.nil? ? Osm::Term.get_current_term_for_section(api, section).id : term.to_i
       cache_key = ['register_attendance', section_id, term_id]
 
-      if !options[:no_cache] && Osm::Model.cache_exist?(api, cache_key) && Osm::Model.get_user_permission(api, section_id, :register).include?(:read)
+      if !options[:no_cache] && Osm::Model.cache_exist?(api, cache_key)
         return Osm::Model.cache_read(api, cache_key)
       end
 
@@ -83,19 +85,26 @@ module Osm
     # @param [Hash] data
     # @option data [Osm::Api] :api The api to use to make the request
     # @option data [Osm::Section] :section the section to update the register for
-    # @option data [Osm::Term, Fixnum, nil] :term the term (or its ID) to get the register for, passing nil causes the current term to be used
+    # @option data [Osm::Term, #to_i, nil] :term The term (or its ID) to get the register for, passing nil causes the current term to be used
     # @option data [Osm::Evening, DateTime, Date] :evening the evening to update the register on
     # @option data [String] :attendance what to mark the attendance as, one of "Yes", "No" or "Absent"
     # @option data [Fixnum, Array<Fixnum>, Osm::Member, Array<Osm::Member>] :members the members (or their ids) to update
     # @option data [Array<Hash>] :completed_badge_requirements (optional) the badge requirements to mark as completed, selected from the Hash returned by the get_badge_requirements_for_evening method
     # @return [Boolean] whether the update succedded
+    # @raise [Osm::ArgumentIsInvalid] If data[:attendance] is not "Yes", "No" or "Absent"
+    # @raise [Osm::ArgumentIsInvalid] If data[:section] is missing
+    # @raise [Osm::ArgumentIsInvalid] If data[:evening] is missing
+    # @raise [Osm::ArgumentIsInvalid] If data[:members] is missing
+    # @raise [Osm::ArgumentIsInvalid] If data[:api] is missing
     def self.update_attendance(data={})
-      raise ArgumentIsInvalid, ':attendance is invalid' unless ['Yes', 'No', 'Absent'].include?(data[:attendance])
-      raise ArgumentIsInvalid, ':section is missing' if data[:section].nil?
-      raise ArgumentIsInvalid, ':evening is missing' if data[:evening].nil?
-      raise ArgumentIsInvalid, ':members is missing' if data[:members].nil?
-
+      raise Osm::ArgumentIsInvalid, ':attendance is invalid' unless ['Yes', 'No', 'Absent'].include?(data[:attendance])
+      raise Osm::ArgumentIsInvalid, ':section is missing' if data[:section].nil?
+      raise Osm::ArgumentIsInvalid, ':evening is missing' if data[:evening].nil?
+      raise Osm::ArgumentIsInvalid, ':members is missing' if data[:members].nil?
+      raise Osm::ArgumentIsInvalid, ':api is missing' if data[:api].nil?
       api = data[:api]
+      Osm::Model.require_ability_to(api, :write, :register, data[:section])
+
       term_id = data[:term].nil? ? Osm::Term.get_current_term_for_section(api, section).id : data[:term].to_i
 
       data[:members] = [*data[:members]].map{ |member| (member.is_a?(Fixnum) ? member : member.id).to_s } # Make sure it's an Array of Strings
@@ -136,7 +145,7 @@ module Osm
 
       # @!method initialize
       #   Initialize a new RegisterField
-      #   @param [Hash] attributes the hash of attributes (see attributes for descriptions, use Symbol of attribute name as the key)
+      #   @param [Hash] attributes The hash of attributes (see attributes for descriptions, use Symbol of attribute name as the key)
 
     end # Class Register::Field
 
@@ -178,7 +187,7 @@ module Osm
 
       # @!method initialize
       #   Initialize a new registerData
-      #   @param [Hash] attributes the hash of attributes (see attributes for descriptions, use Symbol of attribute name as the key)
+      #   @param [Hash] attributes The hash of attributes (see attributes for descriptions, use Symbol of attribute name as the key)
 
     end # Class Register::Data
 

data/lib/osm/section.rb

@@ -12,7 +12,7 @@ module Osm
     # @!attribute [rw] group_name
     #   @return [String] the group name
     # @!attribute [rw] subscription_level
-    #   @return [Symbol] what subscription the section has to OSM (:bronze, :silver or :gold)
+    #   @return [Fixnum] what subscription the section has to OSM (1-bronze, 2-silver, 3-gold)
     # @!attribute [rw] subscription_expires
     #   @return [Date] when the section's subscription to OSM expires
     # @!attribute [rw] type
@@ -66,7 +66,7 @@ module Osm
     attribute :name, :type => String
     attribute :group_id, :type => Integer
     attribute :group_name, :type => String
-    attribute :subscription_level, :default => :unknown
+    attribute :subscription_level, :default => 1
     attribute :subscription_expires, :type => Date
     attribute :type, :default => :unknown
     attribute :column_names, :default => {}
@@ -120,7 +120,7 @@ module Osm
     validates_presence_of :mobile_fields, :unless => Proc.new { |a| a.mobile_fields == {} }
     validates_presence_of :flexi_records, :unless => Proc.new { |a| a.flexi_records == [] }
 
-    validates_inclusion_of :subscription_level, :in => [:bronze, :silver, :gold, :unknown], :message => 'is not a valid level'
+    validates_inclusion_of :subscription_level, :in => (1..3), :message => 'is not a valid subscription level'
     validates_inclusion_of :gocardless, :in => [true, false]
     validates_inclusion_of :myscout_events, :in => [true, false]
     validates_inclusion_of :myscout_badges, :in => [true, false]
@@ -138,34 +138,32 @@ module Osm
 
     # @!method initialize
     #   Initialize a new Section
-    #   @param [Hash] attributes the hash of attributes (see attributes for descriptions, use Symbol of attribute name as the key)
+    #   @param [Hash] attributes The hash of attributes (see attributes for descriptions, use Symbol of attribute name as the key)
 
 
     # Get the user's sections
-    # @param [Osm::Api] The api to use to make the request
+    # @param [Osm::Api] api The api to use to make the request
     # @!macro options_get
     # @return [Array<Osm::Section>]
     def self.get_all(api, options={})
       cache_key = ['sections', api.user_id]
-      subscription_levels = {
-        1 => :bronze,
-        2 => :silver,
-        3 => :gold,
-      }
 
       if !options[:no_cache] && cache_exist?(api, cache_key)
-        return cache_read(api, cache_key)
+        ids = cache_read(api, cache_key)
+        return get_from_ids(api, ids, 'section', options, :get_all)
       end
 
       data = api.perform_query('api.php?action=getUserRoles')
 
       result = Array.new
+      ids = Array.new
       permissions = Hash.new
       data.each do |role_data|
         unless role_data['section'].eql?('discount')  # It's not an actual section
           section_data = role_data['sectionConfig'].is_a?(String) ? ActiveSupport::JSON.decode(role_data['sectionConfig']) : role_data['sectionConfig']
           myscout_data = section_data['portal'] || {}
           section_data['portalExpires'] ||= {}
+          section_id = Osm::to_i_or_nil(role_data['sectionid'])
 
           # Make sense of flexi records
           fr_data = []
@@ -176,16 +174,17 @@ module Osm
             # Expect item to be: {:name=>String, :extraid=>Fixnum}
             # Sometimes get item as: [String, {"name"=>String, "extraid"=>Fixnum}]
             record_data = record_data[1] if record_data.is_a?(Array)
-            flexi_records.push FlexiRecord.new(
+            flexi_records.push Osm::FlexiRecord.new(
               :id => Osm::to_i_or_nil(record_data['extraid']),
               :name => record_data['name'],
+              :section_id => section_id,
             )
           end
 
           section = new(
-            :id => Osm::to_i_or_nil(role_data['sectionid']),
+            :id => section_id,
             :name => role_data['sectionname'],
-            :subscription_level => (subscription_levels[section_data['subscription_level']] || :unknown),
+            :subscription_level => Osm::to_i_or_nil(section_data['subscription_level']),
             :subscription_expires => Osm::parse_date(section_data['subscription_expires']),
             :type => !section_data['sectionType'].nil? ? section_data['sectionType'].to_sym : (!section_data['section'].nil? ? section_data['section'].to_sym : :unknown),
             :num_scouts => section_data['numscouts'],
@@ -216,27 +215,30 @@ module Osm
           )
 
           result.push section
+          ids.push section.id
           cache_write(api, ['section', section.id], section)
-          permissions.merge!(section.id => make_permissions_hash(role_data['permissions']))
+          permissions.merge!(section.id => Osm.make_permissions_hash(role_data['permissions']))
         end
       end
 
-      set_user_permissions(api, get_user_permissions(api).merge(permissions))
-      cache_write(api, cache_key, result)
+      permissions.each do |s_id, perms|
+        api.set_user_permissions(s_id, perms)
+      end
+      cache_write(api, cache_key, ids)
       return result
     end
 
 
     # Get a section
-    # @param [Osm::Api] The api to use to make the request
-    # @param [Fixnum] section_id the section id of the required section
+    # @param [Osm::Api] api The api to use to make the request
+    # @param [Fixnum] section_id The section id of the required section
     # @!macro options_get
     # @return nil if an error occured or the user does not have access to that section
     # @return [Osm::Section]
     def self.get(api, section_id, options={})
       cache_key = ['section', section_id]
 
-      if !options[:no_cache] && cache_exist?(api, cache_key) && get_user_permissions(api).keys.include?(section_id)
+      if !options[:no_cache] && cache_exist?(api, cache_key) && can_access_section?(api, section_id)
         return cache_read(api, cache_key)
       end
 
@@ -250,39 +252,15 @@ module Osm
     end
 
 
-    # Get API user's permissions
-    # @param [Osm::Api] The api to use to make the request
-    # @!macro options_get
-    # @return nil if an error occured or the user does not have access to that section
-    # @return [Hash] {section_id => permissions_hash}
-    def self.fetch_user_permissions(api, options={})
-      cache_key = ['permissions', api.user_id]
-
-      if !options[:no_cache] && cache_exist?(api, cache_key)
-        return cache_read(api, cache_key)
-      end
-
-      data = api.perform_query('api.php?action=getUserRoles')
-
-      all_permissions = Hash.new
-      data.each do |item|
-        unless item['section'].eql?('discount')  # It's not an actual section
-          all_permissions.merge!(Osm::to_i_or_nil(item['sectionid']) => make_permissions_hash(item['permissions']))
-        end
-      end
-      cache_write(api, cache_key, all_permissions)
-      return all_permissions
-    end
-
-
     # Get the section's notepad from OSM
-    # @param [Osm::Api] The api to use to make the request
+    # @param [Osm::Api] api The api to use to make the request
     # @!macro options_get
     # @return [String] the section's notepad
     def get_notepad(api, options={})
+      require_access_to_section(api, self, options)
       cache_key = ['notepad', id]
 
-      if !options[:no_cache] && cache_exist?(api, cache_key) && get_user_permissions(api).keys.include?(id)
+      if !options[:no_cache] && cache_exist?(api, cache_key) && can_access_section?(api, section_id)
         return cache_read(api, cache_key)
       end
 
@@ -303,6 +281,7 @@ module Osm
     # @param [String] content The content of the notepad
     # @return [Boolean] whether the notepad was sucessfully updated
     def set_notepad(api, content)
+      require_access_to_section(api, self)
       data = api.perform_query("users.php?action=updateNotepad&sectionid=#{id}", {'value' => content})
 
       if data.is_a?(Hash) && data['ok'] # Success
@@ -314,15 +293,16 @@ module Osm
 
 
     # Get badge stock levels
-    # @param [Osm::Api] The api to use to make the request
-    # @param [Osm::Term, Fixnum, nil] section the term (or its ID) to get the stock levels for, passing nil causes the current term to be used
+    # @param [Osm::Api] api The api to use to make the request
+    # @param [Osm::Term, Fixnum, #to_i, nil] term The term (or its ID) to get the stock levels for, passing nil causes the current term to be used
     # @!macro options_get
     # @return Hash
     def get_badge_stock(api, term=nil, options={})
+      require_ability_to(api, :read, :badge, self, options)
       term_id = term.nil? ? Osm::Term.get_current_term_for_section(api, self).id : term.to_i
       cache_key = ['badge_stock', id, term_id]
 
-      if !options[:no_cache] && cache_exist?(api, cache_key) && get_user_permission(api, self, :badge).include?(:read)
+      if !options[:no_cache] && cache_exist?(api, cache_key)
         return cache_read(api, cache_key)
       end
 
@@ -366,6 +346,16 @@ module Osm
       end
     end
 
+    # Get the name for the section's subscription level
+    # @return [String, nil] the name of the subscription level (nil if no name exists)
+    def subscription_level_name
+      return {
+        1 => 'Bronze',
+        2 => 'Silver',
+        3 => 'Gold',
+      }[subscription_level]
+    end
+
     def <=>(another)
       begin
         compare_group_name = group_name <=> another.group_name
@@ -389,56 +379,6 @@ module Osm
       end
     end
 
-
-    private
-    def self.make_permissions_hash(permissions)
-      return {} unless permissions.is_a?(Hash)
-
-      permissions_map = {
-        10  => [:read],
-        20  => [:read, :write],
-        100 => [:read, :write, :administer],
-      }
-
-      return permissions.inject({}) do |new_hash, (key, value)|
-        new_hash[key.to_sym] = (permissions_map[value.to_i] || [])
-        new_hash
-      end
-    end
-
-
-    class FlexiRecord
-      include ::ActiveAttr::MassAssignmentSecurity
-      include ::ActiveAttr::Model
-
-      # @!attribute [rw] id
-      #   @return [Fixnum] the aid of the flexi-record
-      # @!attribute [rw] name
-      #   @return [String] the name given to the flexi-record
-
-      attribute :id, :type => Integer
-      attribute :name, :type => String
-
-      attr_accessible :id, :name
-
-      validates_numericality_of :id, :only_integer=>true, :greater_than=>0
-      validates_presence_of :name
-
-
-      # @!method initialize
-      #   Initialize a new FlexiRecord
-      #   @param [Hash] attributes the hash of attributes (see attributes for descriptions, use Symbol of attribute name as the key)
-
-      def <=>(another)
-        begin
-          return self.name <=> another.name
-        rescue NoMethodError
-          return 1
-        end
-      end
-
-    end # Class Section::FlexiRecord
-
   end # Class Section
 
 end # Module