osm 0.1.17 → 0.2.0

data/CHANGELOG.md

@@ -1,3 +1,48 @@
+## Version 0.2.0
+
+  * Raises Forbidden exception if:
+    * You try to use a feature which requires an OSM subscription above your current one
+    * You try to access a feature which you don't have the correct permissions for
+    * You try to access a Section (or it's Grouping) you shouldn't be accessing
+  * All Model classes:
+    * Addition of changed\_attributes method to get a list of attributes which have changed
+    * Addition of reset\_changed\_attributes method to reset the list of attributes which have changed
+  * Activity
+    * Check user has permission to view before returning from cache
+    * Addition of osm\_link method to get the URL for viewing in OSM
+  * Add updating of Grouping
+  * Evening:
+    * Rename to Meeting
+    * Rename meeting\_date attribute to date
+    * Rename get\_programme method to get\_for\_section
+  * Event:
+    * Removal of add\_field method (use add\_column instead)
+    * Removal of fields attribute (use columns instead)
+  * FlexiRecord:
+    * Addition of id, section\_id and name attributes (these no longer need to be passed to methods)
+    * FlexiRecord::Field renamed to FlexiRecord::Column
+    * The following methods are now instance not class methods:
+      * get\_fields (also renamed to get\_columns)
+      * add\_field (also renamed to add\_column)
+      * get\_data
+    * The following methods have bceome instance methods of a subclasses:
+      * update\_field (moved to column.update)
+      * delete\_field (moved to column.delete)
+      * update\_data (moved to data.update)
+  * Member:
+    * Removal of grouping attribute
+    * Removal of grouping\_label attribute
+    * Addition of myscout\_link method (used to get the link to the member's My.SCOUT page)
+  * Section:
+    * subscription\_level attribute is now a Fixnum not Symbol
+    * Addition of subscription\_level\_name method to get the name of the subscription level for the section
+    * flexi\_records attribute now contains an Array of Osm::FlexiRecord
+  * "Under the hood" changes:
+    * Instead of caching individual items and a list of items the gem now caches a list of IDs. This should reduce the cache size.
+    * When updating items requires multiple OSM requests, now only updates what changed
+    * Updating of cached data when deleting/updating items from OSM
+>>>>>>> dev_v_0.2.0
+
 ## Version 0.1.17
 
   * Add comparison to Evening

data/Guardfile

@@ -0,0 +1,9 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard 'rspec' do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch(%r{^lib/([^/]+)/(.+)\.rb$}) { |m| "spec/#{m[1]}/#{m[2]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end

data/README.md

@@ -80,10 +80,10 @@ however it should be noted that when the OSM API adds a feature it can be diffic
   * Badge requirements for evening
   * Due Badges
   * Evening
-  * Event
-  * Events
-  * Event Columns
-  * Event Attendance
+  * Event (Silver required)
+  * Events (Silver required)
+  * Event Columns (Silver required)
+  * Event Attendance (Silver required)
   * Flexi Record Data
   * Flexi Record Structure
   * Groupings (e.g. Sixes, Patrols)
@@ -102,24 +102,25 @@ however it should be noted that when the OSM API adds a feature it can be diffic
 ### Update
   * Activity
   * Evening
-  * Event
-  * Event Attendance
-  * Event Column
+  * Event (Silver required)
+  * Event Attendance (Silver required)
+  * Event Column (Silver required)
   * Flexi Record Column
   * Flexi Record Data
+  * Grouping
   * Member
   * Register Attendance
 
 ### Create
   * Evening
-  * Event
+  * Event (Silver required)
   * Member
   * Flexi Record Column
 
 ### Delete
   * Evening
-  * Event
-  * Event Column
+  * Event (Silver required)
+  * Event Column (Silver required)
   * Flexi Record Column
 
 ### Actions
@@ -129,15 +130,16 @@ however it should be noted that when the OSM API adds a feature it can be diffic
 
 ## Parts of the OSM API currently NOT supported (may not be an exhaustive list):
 
-  * Badges:
+  * Badges (Silver required for activity, Bronze for core, challenge and staged):
     * Which requirements each member has met:
       * Retreive [issue 21]
       * Update [issue 22]
     * Retrieve details for each badge (stock, short column names etc.) [issue 20]
     * Update badge stock [issue 56]
+  * Event - Create column (Silver required)
   * SMS:
     * Retrieval of delivery reports [issue 54]
     * Sending a message [issue 54]
-  * Gift aid (Everything)
-  * Finances (Everything)
+  * Gift aid (Everything) (Gold required)
+  * Finances (Everything) (Gold required)
   * MyScout (Everything) (Maybe)

data/lib/osm.rb

@@ -122,6 +122,20 @@ module Osm
     hash_out
   end
 
+  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
 
   def self.epoch_date?(date)
     [OSM_EPOCH, OSM_EPOCH_HUMAN].include?(date)

data/lib/osm/activity.rb

@@ -96,15 +96,21 @@ module Osm
 
     # Get activity details
     # @param [Osm::Api] api The api to use to make the request
-    # @param [Fixnum] activity_id the activity ID
-    # @param [Fixnum] version the version of the activity to retreive, if nil the latest version will be assumed
+    # @param [Fixnum] activity_id The activity ID
+    # @param [Fixnum] version The version of the activity to retreive, if nil the latest version will be assumed
     # @!macro options_get
     # @return [Osm::Activity]
     def self.get(api, activity_id, version=nil, options={})
       cache_key = ['activity', activity_id]
 
-      if !options[:no_cache] && cache_exist?(api, [*cache_key, version]) # TODO work out permission check
-        return cache_read(api, [*cache_key, version])
+      if !options[:no_cache] && cache_exist?(api, [*cache_key, version])
+        activity = cache_read(api, [*cache_key, version])
+        if (activity.shared == 2) || (activity.user_id == api.user_id) ||  # Shared or owned by this user
+        Osm::Section.get_all(api).map{ |s| s.group_id }.uniq.include?(activity.group_id)  # user belomngs to the group owning the activity
+          return activity
+        else
+          return nil
+        end
       end
 
       data = nil
@@ -174,16 +180,26 @@ module Osm
 
     # @!method initialize
     #   Initialize a new Term
-    #   @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 link to display this activity in OSM
+    # @return [String] the link for this member's My.SCOUT
+    # @raise [Osm::ObjectIsInvalid] If the Activity is invalid
+    def osm_link
+      raise Osm::ObjectIsInvalid, 'activity is invalid' unless valid?
+      return "https://www.onlinescoutmanager.co.uk/?l=p#{self.id}"
+    end
+
     # Add this activity to the programme in OSM
     # @param [Osm::Api] api The api to use to make the request
-    # @param [Osm::Section, Fixnum] section The Section (or it's ID) to add the Activity to
+    # @param [Osm::Section, Fixnum, #to_i] section The Section (or it's ID) to add the Activity to
     # @param [Date, DateTime] date The date of the Evening to add the Activity to (OSM will create the Evening if it doesn't already exist)
     # @param [String] notes The notes which should appear for this Activity on this Evening
     # @return [Boolean] Whether the activity was successfully added
     def add_to_programme(api, section, date, notes="")
+      require_ability_to(api, :write, :programme, section)
+
       data = api.perform_query("programme.php?action=addActivityToProgramme", {
         'meetingdate' => date.strftime(Osm::OSM_DATE_FORMAT),
         'activityid' => id,
@@ -191,16 +207,25 @@ module Osm
         'notes' => notes,
       })
 
-      return (data == {'result'=>0})
+      if (data == {'result'=>0})
+        # The cached activity will be out of date - remove it
+        cache_delete(api, ['activity', self.id])
+        return true
+      else
+        return false
+      end
     end
 
     # Update this activity in OSM
     # @param [Osm::Api] api The api to use to make the request
-    # @param [Osm::Section, Fixnum] section The Section (or it's ID)
+    # @param [Osm::Section, Fixnum, #to_i] section The Section (or it's ID)
     # @param [Boolean] secret_update Whether this is a secret update
     # @return [Boolean] Whether the activity was successfully added
+    # @raise [Osm::ObjectIsInvalid] If the Activity is invalid
+    # @raise [Osm::Forbidden] If the Activity is not editable
     def update(api, section, secret_update=false)
-      raise ObjectIsInvalid, 'activity is invalid' unless valid?
+      raise Osm::ObjectIsInvalid, 'activity is invalid' unless valid?
+      raise Osm::Forbidden, "You are not allowed to update this activity" unless self.editable
 
       data = api.perform_query("programme.php?action=update", {
         'title' => title,
@@ -219,7 +244,13 @@ module Osm
         'secretEdit' => secret_update,
       })
 
-      return (data == {'result'=>true})
+      if (data == {'result'=>true})
+        # The cached activity will be out of date - remove it
+        cache_delete(api, ['activity', self.id])
+        return true
+      else
+        return false
+      end
     end
 
 
@@ -251,7 +282,7 @@ module Osm
 
       # @!method initialize
       #   Initialize a new Term
-      #   @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 Activity::File
 
@@ -292,7 +323,7 @@ module Osm
 
       # @!method initialize
       #   Initialize a new Badge
-      #   @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 Activity::Badge
 
@@ -323,7 +354,7 @@ module Osm
 
       # @!method initialize
       #   Initialize a new Version
-      #   @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 Activity::Version
 

data/lib/osm/api.rb

@@ -51,9 +51,9 @@ module Osm
     end
 
     # Initialize a new API connection
-    # @param [String] user_id osm userid of the user to act as (get this by using the authorize method)
-    # @param [String] secret osm secret of the user to act as (get this by using the authorize method)
-    # @param [Symbol] site whether to use OSM (:osm) or OGM (:ogm), defaults to the value set for the class
+    # @param [String] user_id OSM userid of the user to act as (get this by using the authorize method)
+    # @param [String] secret OSM secret of the user to act as (get this by using the authorize method)
+    # @param [Symbol] site Whether to use OSM (:osm) or OGM (:ogm), defaults to the value set for the class
     # @return nil
     def initialize(user_id, secret, site=@@site)
       raise ArgumentError, 'You must pass a secret (get this by using the authorize method)' if secret.nil?
@@ -98,8 +98,8 @@ module Osm
 
     # Get the userid and secret to be able to act as a certain user on the OSM/OGM system
     # @param [Symbol] site The site to use either :osm or :ogm (defaults to whatever was set in the configure method)
-    # @param [String] email the login email address of the user on OSM
-    # @param [String] password the login password of the user on OSM
+    # @param [String] email The login email address of the user on OSM
+    # @param [String] password The login password of the user on OSM
     # @return [Hash] a hash containing the following keys:
     #   * :user_id - the userid to use in future requests
     #   * :secret - the secret to use in future requests
@@ -117,8 +117,8 @@ module Osm
 
 
     # Set the OSM user to make future requests as
-    # @param [String] user_id the OSM userid to use (get this using the authorize method)
-    # @param [String] secret the OSM secret to use (get this using the authorize method)
+    # @param [String] user_id The OSM userid to use (get this using the authorize method)
+    # @param [String] secret The OSM secret to use (get this using the authorize method)
     # @return [Osm::Api] self
     def set_user(user_id, secret)
       @user_id = user_id
@@ -128,8 +128,8 @@ module Osm
 
 
     # Make a query to the OSM/OGM API
-    # @param [String] url the script on the remote server to invoke
-    # @param [Hash] api_data a hash containing the values to be sent to the server in the body of the request
+    # @param [String] url The script on the remote server to invoke
+    # @param [Hash] api_data A hash containing the values to be sent to the server in the body of the request
     # @return [Hash, Array, String] the parsed JSON returned by OSM
     def perform_query(url, api_data={})
       self.class.perform_query(@site, url, api_data.merge({
@@ -138,12 +138,48 @@ module Osm
       }))
     end
 
+    # Get API user's permissions
+    # @!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 get_user_permissions(options={})
+      cache_key = ['permissions', user_id]
+
+      if !options[:no_cache] && Osm::Model.cache_exist?(self, cache_key)
+        return Osm::Model.cache_read(self, cache_key)
+      end
+
+      data = 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']) => Osm.make_permissions_hash(item['permissions']))
+        end
+      end
+      Osm::Model.cache_write(self, cache_key, all_permissions)
+
+      return all_permissions
+    end
+
+    # Set access permission for an API user for a given Section
+    # @param [Section, Fixnum] section The Section to set permissions for
+    # @param [Hash] permissions The permissions Hash
+    def set_user_permissions(section, permissions)
+      key = ['permissions', user_id]
+      permissions = get_user_permissions.merge(section.to_i => permissions)
+      Osm::Model.cache_write(self, key, permissions)
+    end
+
+
     private
     # Make a query to the OSM/OGM API
     # @param [Symbol] site The site to use either :osm or :ogm
-    # @param [String] url the script on the remote server to invoke
-    # @param [Hash] api_data a hash containing the values to be sent to the server in the body of the request
+    # @param [String] url The script on the remote server to invoke
+    # @param [Hash] api_data A hash containing the values to be sent to the server in the body of the request
     # @return [Hash, Array, String] the parsed JSON returned by OSM
+    # @raise [Osm::Error] If an error was returned by OSM
+    # @raise [Osm::ConnectionError] If an error occured connecting to OSM
     def self.perform_query(site, url, api_data={})
       raise ArgumentError, 'site is invalid, this should be set to either :osm or :ogm' unless [:osm, :ogm].include?(site)
  
@@ -180,7 +216,7 @@ module Osm
     end
 
     # Check if text looks like it's JSON
-    # @param [String] text what to look at
+    # @param [String] text What to look at
     # @return [Boolean]
     def self.looks_like_json?(text)
       (['[', '{'].include?(text[0]))

data/lib/osm/api_access.rb

@@ -23,7 +23,7 @@ module Osm
 
     # Get API access details for a given section
     # @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 details for
+    # @param [Osm::Section, Fixnum, #to_i] section The section (or its ID) to get the details for
     # @!macro options_get
     # @return [Array<Osm::ApiAccess>]
     def self.get_all(api, section, options={})
@@ -31,7 +31,8 @@ module Osm
       cache_key = ['api_access', api.user_id, section_id]
 
       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, cache_key, section, options, :get_all)
       end
 
       data = api.perform_query("users.php?action=getAPIAccess&sectionid=#{section_id}")
@@ -41,6 +42,7 @@ module Osm
         20  => [:read, :write],
       }
       result = Array.new
+      ids = Array.new
       data['apis'].each do |item|
         attributes = {}
         attributes[:id] = item['apiid'].to_i
@@ -57,9 +59,10 @@ module Osm
 
         this_item = new(attributes)
         result.push this_item
+        ids.push this_item.id
         cache_write(api, [*cache_key, this_item.id], this_item)
       end
-      cache_write(api, cache_key, result)
+      cache_write(api, cache_key, ids)
 
       return result
     end
@@ -67,7 +70,7 @@ module Osm
 
     # Get our API access details for a given section
     # @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 details for
+    # @param [Osm::Section, Fixnum, #to_i] section The section (or its ID) to get the details for
     # @!macro options_get
     # @return [Osm::ApiAccess]
     def self.get_ours(api, section, options={})
@@ -77,7 +80,7 @@ module Osm
 
     # Get API Access for a given API
     # @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 details for
+    # @param [Osm::Section, Fixnum, #to_i] section The section (or its ID) to get the details for
     # @param [Osm::Api] for_api The api (or its ID) to get access for
     # @!macro options_get
     # @return [Osm::ApiAccess]
@@ -101,7 +104,7 @@ module Osm
 
     # @!method initialize
     #   Initialize a new Term
-    #   @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 ApiAccess
 

data/lib/osm/due_badges.rb

@@ -30,16 +30,17 @@ module Osm
 
     # Get due badges
     # @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 due badges for
-    # @param [Osm::Term, Fixnum, nil] term the term (or its ID) to get the due badges 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 due badges for
+    # @param [Osm::Term, Fixnum, #to_i, nil] term The term (or its ID) to get the due badges for, passing nil causes the current term to be used
     # @!macro options_get
     # @return [Osm::DueBadges]
     def self.get(api, section, term=nil, options={})
+      require_ability_to(api, :read, :badge, section, options)
       section = Osm::Section.get(api, section, options) if section.is_a?(Fixnum)
       term_id = (term.nil? ? Osm::Term.get_current_term_for_section(api, section, options) : term).to_i
       cache_key = ['due_badges', section.id, term_id]
 
-      if !options[:no_cache] && cache_exist?(api, cache_key) && get_user_permission(api, section.id, :badge).include?(:read)
+      if !options[:no_cache] && cache_exist?(api, cache_key)
         return cache_read(api, cache_key)
       end
 
@@ -74,7 +75,7 @@ module Osm
 
     # @!method initialize
     #   Initialize a new Term
-    #   @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)
 
 
     # Check if there are no badges due