osm 1.2.24 → 1.2.25

data/lib/osm/myscout.rb

@@ -0,0 +1,330 @@
+module Osm
+
+  class Myscout
+
+    class ParentLoginHistory < Osm::Model
+      SORT_BY= [:last_name, :first_name, :member_id]
+
+      # @!attribute [rw] member_id
+      #   @return [Fixnum] the id for the member
+      # @!attribute [rw] first_name
+      #   @return [String] the member's first name
+      # @!attribute [rw] last_name
+      #   @return [String] the member's last name
+      # @!attribute [rw] logins
+      #   @return [Fixnum] the total number of logins
+      # @!attribute [rw] last_login
+      #   @return [DateTime] the time and date of the last login
+
+      attribute :member_id, type: Integer
+      attribute :first_name, type: String
+      attribute :last_name, type: String
+      attribute :logins, type: Integer
+      attribute :last_login, type: DateTime
+
+      if ActiveModel::VERSION::MAJOR < 4
+        attr_accessible :member_id, :first_name, :last_name, :logins, :last_login
+      end
+
+      validates_presence_of :first_name
+      validates_presence_of :last_name
+      validates_numericality_of :member_id, only_integer: true, greater_than: 0
+      validates_numericality_of :logins, only_integer: true, greater_than_or_equal_to: 0
+
+
+      # @!method initialize
+      #   Initialize a new Member
+      #   @param [Hash] attributes The hash of attributes (see attributes for descriptions, use Symbol of attribute name as the key)
+
+
+      # Get parent login history
+      # @param [Osm::Api] api The api to use to make the request
+      # @param [Osm::Section, Fixnum, #to_i] section The section (or its ID) to get login history for
+      # @!macro options_get
+      # @return [Array<Osm::Myscout::ParentLoginHistory>]
+      def self.get_for_section(api, section, options={})
+        section_id = section.to_i
+        require_ability_to(api, :read, :member, section, options)
+        cache_key = ['myscout', 'parent_login_history', section_id]
+
+        if !options[:no_cache] && cache_exist?(api, cache_key)
+          return cache_read(api, cache_key)
+        end
+
+        data = api.perform_query("ext/settings/parents/loginhistory/?action=getLoginHistory&sectionid=#{section_id}")
+        return [] unless data.is_a?(Hash)
+        data = data['items']
+        return [] unless data.is_a?(Array)
+
+        data.map! do |item|
+          new(
+            member_id:    Osm::to_i_or_nil(item['scoutid']),
+            first_name:   item['firstname'],
+            last_name:    item['lastname'],
+            logins:       Osm::to_i_or_nil(item['numlogins']),
+            last_login:   get_last_login_date(item['lastlogin'],)
+          )
+        end
+
+        cache_write(api, cache_key, data)
+        return data
+      end
+
+      private
+      def self.get_last_login_date(date_str)
+        return nil if date_str.nil?
+        return nil if date_str.eql?('Invitation not sent')
+        Time.strptime(date_str, '%d/%m/%Y %H:%M')
+      end
+
+    end # class Myscout::ParentLoginHistory
+
+
+    class Template < Osm::Model
+      SORT_BY = [:key]
+
+      TEMPLATES = [
+        {title: "First payment email", id: "email-first", description: "This email is sent to the parents the first time that you request a payment from them. The message should introduce the system to them, explain the benefits that the parents and you get, and provide account details (by using the tags).", tags:[
+          {id: "DIRECT_LINK", required: true, description: "A direct link to the payments page that avoids the need for the parents to login."},
+          {id: "SCHEDULE_NAME", required: true, description: "The name of the first payment schedule that you have asked the parents to pay."},
+          {id: "SCHEDULE_DESCRIPTION", required: false, description: "The description of the first payment schedule that you have asked the parents to pay."},
+          {id: "SCHEDULE_PREAUTH", required: false, description: "The amount you are asking parents to pre-authorise."},
+          {id: "MEMBER_FIRSTNAME", required: false, description: "The member's first name."},
+          {id: "MEMBER_LASTNAME", required: false, description: "The member's last name."},
+        ]},
+        {title: "New schedule", id: "email-subsequent", description: "This email is sent every time you request the parents sign up to a payment schedule.", tags:[
+          {id: "DIRECT_LINK", required: true, description: "A direct link to the payments page that avoids the need for the parents to login."},
+          {id: "MEMBER_FIRSTNAME", required: false, description: "The member's first name."},
+          {id: "MEMBER_LASTNAME", required: false, description: "The member's last name."},
+          {id: "SCHEDULE_NAME", required: true, description: "The name of the payment schedule that you have asked the parents to pay."},
+          {id: "SCHEDULE_DESCRIPTION", required: false, description: "The description of the payment schedule that you have asked the parents to pay."},
+          {id: "SCHEDULE_PREAUTH", required: false, description: "The amount you are asking parents to pre-authorise."},
+        ]},
+        {title: "New payment (direct debit already setup)", id: "email-specificpayment-dd", description: "This email is sent to parents (who have already set up a direct debit) when their child has been set to pay a payment on a schedule that contains optional payments (i.e. events). It should simply notify them of the upcoming payment and give a link to the system.", tags:[
+          {id: "DIRECT_LINK", required: true, description: "A direct link to the payments page that avoids the need for the parents to login."},
+          {id: "MEMBER_FIRSTNAME", required: false, description: "The member's first name."},
+          {id: "MEMBER_LASTNAME", required: false, description: "The member's last name."},
+          {id: "PAYMENT_NAME", required: true, description: "The name of the specific payment (this is different to the schedule name)."},
+          {id: "PAYMENT_DATE", required: true, description: "The date the payment process will be initiated."},
+          {id: "PAYMENT_AMOUNT", required: true, description: "The amount that will be taken (a pound sign is automatically inserted)."},
+          {id: "SCHEDULE_NAME", required: false, description: "The name of the payment schedule that you have asked the parents to pay."},
+          {id: "SCHEDULE_DESCRIPTION", required: false, description: "The description of the payment schedule that you have asked the parents to pay."},
+          {id: "SCHEDULE_PREAUTH", required: false, description: "The amount you are asking parents to pre-authorise."},
+        ]},
+        {title: "Payment notification for overdue payment", id: "email-immediatepayment-dd", description: "This email is sent to parents who have an active direct debit when their child has been marked as requiring a payment in the past to let them know that they are being charged immediately.", tags:[
+          {id: "DIRECT_LINK", required: true, description: "A direct link to the payments page that avoids the need for the parents to login."},
+          {id: "MEMBER_FIRSTNAME", required: false, description: "The member's first name."},
+          {id: "MEMBER_LASTNAME", required: false, description: "The member's last name."},
+          {id: "PAYMENT_NAME", required: true, description: "The name of the specific payment (this is different to the schedule name)."},
+          {id: "PAYMENT_DATE", required: false, description: "The date the payment process will be initiated."},
+          {id: "PAYMENT_AMOUNT", required: true, description: "The amount that will be taken (a pound sign is automatically inserted)."},
+          {id: "SCHEDULE_NAME", required: false, description: "The name of the payment schedule that you have asked the parents to pay."},
+          {id: "SCHEDULE_DESCRIPTION", required: false, description: "The description of the payment schedule that you have asked the parents to pay."},
+          {id: "SCHEDULE_PREAUTH", required: false, description: "The amount you are asking parents to pre-authorise."},
+        ]},
+        {title: "Immediate payment request for overdue payment", id: "email-immediatepayment-nodd", description: "This email is sent to parents who have not got an active direct debit when their child has been marked as requiring a payment in the past to let them know that they need to pay immediately.", tags:[
+          {id: "DIRECT_LINK", required: true, description: "A direct link to the payments page that avoids the need for the parents to login."},
+          {id: "MEMBER_FIRSTNAME", required: false, description: "The member's first name."},
+          {id: "MEMBER_LASTNAME", required: false, description: "The member's last name."},
+          {id: "PAYMENT_NAME", required: true, description: "The name of the specific payment (this is different to the schedule name)."},
+          {id: "PAYMENT_DATE", required: false, description: "The date the payment process will be initiated."},
+          {id: "PAYMENT_AMOUNT", required: true, description: "The amount that will be taken (a pound sign is automatically inserted)."},
+          {id: "SCHEDULE_NAME", required: false, description: "The name of the payment schedule that you have asked the parents to pay."},
+          {id: "SCHEDULE_DESCRIPTION", required: false, description: "The description of the payment schedule that you have asked the parents to pay."},
+          {id: "SCHEDULE_PREAUTH", required: false, description: "The amount you are asking parents to pre-authorise."},
+        ]},
+        {title: "New payment (direct debit not setup)", id: "email-specificpayment-nodd", description: "This email is sent to parents (who have *not* set up a direct debit) when their child has been asked to pay for an individual entry on a schedule. The message should ask the parents to sign up to a direct debit, or optionally, remind them to pay you via cash/cheque etc.", tags:[
+          {id: "DIRECT_LINK", required: true, description: "A direct link to the payments page that avoids the need for the parents to login."},
+          {id: "MEMBER_FIRSTNAME", required: false, description: "The member's first name."},
+          {id: "MEMBER_LASTNAME", required: false, description: "The member's last name."},
+          {id: "PAYMENT_NAME", required: true, description: "The name of the specific payment (this is different to the schedule name)."},
+          {id: "PAYMENT_DATE", required: true, description: "The date the payment is due."},
+          {id: "PAYMENT_AMOUNT", required: true, description: "The amount that will be taken (a pound sign is automatically inserted)."},
+          {id: "SCHEDULE_NAME", required: false, description: "The name of the payment schedule that you have asked the parents to pay."},
+          {id: "SCHEDULE_DESCRIPTION", required: false, description: "The description of the payment schedule that you have asked the parents to pay."},
+          {id: "SCHEDULE_PREAUTH", required: false, description: "The amount you are asking parents to pre-authorise."},
+        ]},
+        {title: "Payment initiated", id: "email-initiated", description: "This email is sent to parents when a payment is initiated by the system.", tags:[
+          {id: "DIRECT_LINK", required: true, description: "A direct link to the payments page that avoids the need for the parents to login."},
+          {id: "MEMBER_FIRSTNAME", required: false, description: "The member's first name."},
+          {id: "MEMBER_LASTNAME", required: false, description: "The member's last name."},
+          {id: "PAYMENT_NAME", required: false, description: "The name of the specific payment (this is different to the schedule name)."},
+          {id: "PAYMENT_DATE", required: false, description: "The date the payment is due."},
+          {id: "PAYMENT_AMOUNT", required: false, description: "The amount that will be taken (a pound sign is automatically inserted)."},
+          {id: "SCHEDULE_NAME", required: false, description: "The name of the payment schedule that you have asked the parents to pay."},
+          {id: "SCHEDULE_DESCRIPTION", required: false, description: "The description of the payment schedule that you have asked the parents to pay."},
+          {id: "SCHEDULE_PREAUTH", required: false, description: "The amount you are asking parents to pre-authorise."},
+        ]},
+        {title: "Payment reminder", id: "email-paymentreminder", description: "This is send periodically after the due date when the payment has not been made. The frequency of the emails is configurable in the My.SCOUT section of the site.", tags:[
+          {id: "DIRECT_LINK", required: true, description: "A direct link to the payments page that avoids the need for the parents to login."},
+          {id: "MEMBER_FIRSTNAME", required: false, description: "The member's first name."},
+          {id: "MEMBER_LASTNAME", required: false, description: "The member's last name."},
+          {id: "PAYMENT_NAME", required: false, description: "The name of the specific payment (this is different to the schedule name)."},
+          {id: "PAYMENT_DATE", required: false, description: "The date the payment is due."},
+          {id: "PAYMENT_AMOUNT", required: false, description: "The amount that will be taken (a pound sign is automatically inserted)."},
+          {id: "SCHEDULE_NAME", required: false, description: "The name of the payment schedule that you have asked the parents to pay."},
+          {id: "SCHEDULE_DESCRIPTION", required: false, description: "The description of the payment schedule that you have asked the parents to pay."},
+          {id: "SCHEDULE_PREAUTH", required: false, description: "The amount you are asking parents to pre-authorise."},
+        ]},
+        {title: "Introduction to payment system", id: "website-payments-index", description: "This text is shown on the parent website under the words \"What is this?\". It should be used to explain about this system and the benefits that the parents and leaders will get, and reassure the parents that it is a safe and secure system.", tags:[]},
+        {title: "Instructions to click Pay Now/Subscribe", id: "website-payments-schedule", description: "This text is shown on the parent website on a payment schedules pages, above the subscribe button. It should direct the parents to click the Subscribe button to set up a direct debit, or Pay falsew buttons to pay for things individually.", tags:[]},
+        {title: "Event invitation", id: "email-event", description: "This email is sent to the parents when you invite children to events in the Your Events area.", tags:[
+          {id: "DIRECT_LINK", required: true, description: "A direct link to the payments page that avoids the need for the parents to login."},
+          {id: "EVENT_NAME", required: false, description: "The name of the event"},
+          {id: "EVENT_LOCATION", required: false, description: "The location of the event"},
+          {id: "EVENT_COST", required: false, description: "The cost of the event"},
+          {id: "EVENT_DATES", required: false, description: "The event dates - this will be formatted properly into \"DATE\", \"DATE at TIME\", \"From DATE to DATE\", \"From DATE at TIME to DATE at TIME\" etc."},
+          {id: "EVENT_DETAILS", required: false, description: "This is the \"Details for My.SCOUT\" section of the event"},
+          {id: "CONFIRMATION_DEADLINE", required: false, description: "The confirmation deadline - beyond which, parents will not be able to sign up through My.SCOUT"},
+          {id: "MEMBER_FIRSTNAME", required: false, description: "The member's first name."},
+          {id: "MEMBER_LASTNAME", required: false, description: "The member's last name."},
+        ]},
+        {title: "Event invitation reminder", id: "email-event-reminder", description: "This is a reminder email to ask the parents to let you know if their child is attending - the frequency and number of reminders is customisable in the My.SCOUT settings page.", tags:[
+          {id: "DIRECT_LINK", required: true, description: "A direct link to the events page that avoids the need for the parents to login."},
+          {id: "EVENT_NAME", required: false, description: "The name of the event"},
+          {id: "EVENT_LOCATION", required: false, description: "The location of the event"},
+          {id: "EVENT_COST", required: false, description: "The cost of the event"},
+          {id: "EVENT_DATES", required: false, description: "The event dates - this will be formatted properly into \"on DATE\", \"on DATE at TIME\", \"from DATE to DATE\", \"from DATE at TIME to DATE at TIME\" etc."},
+          {id: "EVENT_DETAILS", required: false, description: "This is the \"Details for My.SCOUT\" section of the event"},
+          {id: "CONFIRMATION_DEADLINE", required: false, description: "The confirmation deadline - beyond which, parents will not be able to sign up through My.SCOUT"},
+          {id: "MEMBER_FIRSTNAME", required: false, description: "The member's first name."},
+          {id: "MEMBER_LASTNAME", required: false, description: "The member's last name."},
+        ]},
+        {title: "Event attendance reminder", id: "email-event-attendancereminder", description: "This is a reminder email to tell parents that their child is attending the event - the number of days before the event that this email is sent is customisable on a per-event basis on each event page.", tags:[
+          {id: "DIRECT_LINK", required: false, description: "A direct link to the events page that avoids the need for the parents to login."},
+          {id: "EVENT_NAME", required: false, description: "The name of the event"},
+          {id: "EVENT_LOCATION", required: false, description: "The location of the event"},
+          {id: "EVENT_DATES", required: false, description: "The event dates - this will be formatted properly into \"on DATE\", \"on DATE at TIME\", \"from DATE to DATE\", \"from DATE at TIME to DATE at TIME\" etc."},
+          {id: "EVENT_DETAILS", required: false, description: "This is the \"Details for My.SCOUT\" section of the event"},
+          {id: "CONFIRMATION_DEADLINE", required: false, description: "The confirmation deadline - beyond which, parents will not be able to sign up through My.SCOUT"},
+          {id: "MEMBER_FIRSTNAME", required: false, description: "The member's first name."},
+          {id: "MEMBER_LASTNAME", required: false, description: "The member's last name."},
+        ]},
+        {title: "Invitation to system", id: "email-invitation", description: "This email is sent to invite parents into the system - they will receive a private link that avoids the need to login.", tags:[
+          {id: "DIRECT_LINK", required: true, description: "A direct link into the parent system that avoids the need for the parents to login."},
+          {id: "MEMBER_FIRSTNAME", required: false, description: "The member's first name."},
+          {id: "MEMBER_LASTNAME", required: false, description: "The member's last name."},
+        ]},
+        {title: "Parent rota reminder email", id: "email-rota-reminder", description: "This email informs parents that they are signed up to the rota and is sent the day before the meeting", tags:[
+          {id: "PROGRAMME_TITLE", required: false, description: "The title of programme"},
+          {id: "PROGRAMME_falseTES", required: false, description: "falsetes for parents"},
+          {id: "PROGRAMME_WHEN", required: false, description: "Dates and if specified time of the programme meeting."},
+          {id: "DIRECT_LINK", required: false, description: "A direct link to the programme page that avoids the need for the parents to login."},
+          {id: "MEMBER_FIRSTNAME", required: false, description: "The member's first name."},
+          {id: "MEMBER_LASTNAME", required: false, description: "The member's last name."},
+        ]},
+        {title: "Badge awarded email", id: "email-badge-awarded", description: "This email is sent to parents whenever badges have been awarded.", tags:[
+          {id: "BADGE_LIST", required: true, description: "The list of badges that have been awarded."},
+          {id: "DIRECT_LINK", required: false, description: "A direct link to the badges page on My.SCOUT that avoids the need for the parents to login."},
+          {id: "MEMBER_FIRSTNAME", required: false, description: "The member's first name."},
+          {id: "MEMBER_LASTNAME", required: false, description: "The member's last name."},
+        ]},
+        {title: "Request for census information", id: "email-census", description: "This is only sent when a leader clicks the 'Send My.SCOUT email' button in the census aggregator pages.", tags:[
+          {id: "DIRECT_LINK", required: true, description: "A direct link to the census."},
+          {id: "MEMBER_FIRSTNAME", required: true, description: "The member's first name."},
+          {id: "MEMBER_LASTNAME", required: false, description:"The member's last name."},
+        ]},
+        {title: "Gift Aid Declaration", id: "email-giftaid", description: "This email asks parents to update their Gift Aid declaration details on My.SCOUT (this is a free feature for Gold users)", tags:[
+          {id: "DIRECT_LINK", required: false, description: "A direct link to the programme page that avoids the need for the parents to login."},
+          {id: "MEMBER_FIRSTNAME", required: false, description: "The member's first name."},
+          {id: "MEMBER_LASTNAME", required: false, description: "The member's last name."},
+        ]},
+      ]
+
+      VALID_TEMPLATE_IDS = TEMPLATES.map{ |t| t[:id] }
+
+
+      # Get a template
+      # @param [Osm::Api] api The api to use to make the request
+      # @param [Osm::Section, Fixnum, #to_i] section The section (or its ID) to get login history for
+      # @param [String] id The ID of the template to get
+      # @!macro options_get
+      # @return [String, nil]
+      def self.get_template(api, section, id, options={})
+        fail ArgumentError, "Invalid template ID: #{id.inspect}" unless VALID_TEMPLATE_IDS.include?(id)
+
+        section_id = section.to_i
+        require_ability_to(api, :read, :user, section, options)
+        cache_key = ['myscout', 'template', section_id, id]
+
+        if !options[:no_cache] && cache_exist?(api, cache_key)
+          return cache_read(api, cache_key)
+        end
+
+        data = api.perform_query("ext/settings/parents/?action=getTemplate&key=#{id}&section_id=#{section_id}")
+        content = data.is_a?(Hash) ? data['data'] : ''
+        return nil if content.empty?
+
+        cache_write(api, cache_key, content)
+        return content
+      end
+
+      # Update a template in OSM
+      # @param [Osm::Api] api The api to use to make the request
+      # @param [Osm::Section, Fixnum, #to_i] section The section (or its ID) to get login history for
+      # @param [String] id The ID of the template to get
+      # @param [String] content The new content of the template
+      # @return [Boolean] Wheter OSM reported the template as updated 
+      def self.update_template(api, section, id, content)
+        fail ArgumentError, "Invalid template ID: #{id.inspect}" unless VALID_TEMPLATE_IDS.include?(id)
+
+        section_id = section.to_i
+        require_ability_to(api, :write, :user, section)
+
+        # Make sure required tags are present
+        tags = Osm::Myscout::Template::TEMPLATES.find{ |t| t[:id].eql?(id) }[:tags]
+        fail Osm::Error, "Couldn't find tags for template" if tags.nil?
+        tags.select{ |tag| tag[:required] }.each do |tag|
+          unless content.include?("[#{tag[:id]}]")
+            message = "Required tag [#{tag[:id]}] not found in template content."
+            fail ArgumentError, message
+          end
+        end
+
+        data = api.perform_query('ext/settings/parents/?action=updateTemplate', {
+          'section_id' => section_id,
+          'key' =>        id,
+          'value' =>      content
+        })
+
+        if data.is_a?(Hash) && data['status'] && data['data']
+          cache_key = ['myscout', 'template', section_id, id]
+          cache_write(api, cache_key, content)
+          return true
+        end
+
+        return false
+      end
+
+      # Restore a template to OSM's default for it
+      # @param [Osm::Api] api The api to use to make the request
+      # @param [Osm::Section, Fixnum, #to_i] section The section (or its ID) to get login history for
+      # @param [String] id The ID of the template to get
+      # @param [String] content The new content of the template
+      # @return [String, nil] The content of the template (nil if not restored)
+      def self.restore_template(api, section, id)
+        fail ArgumentError, "Invalid template ID: #{id.inspect}" unless VALID_TEMPLATE_IDS.include?(id)
+
+        section_id = section.to_i
+        require_ability_to(api, :write, :user, section)
+
+        data = api.perform_query('ext/settings/parents/?action=restoreTemplate', {
+          'section_id' => section_id,
+          'key' =>        id,
+        })
+
+        if data.is_a?(Hash) && data['status']
+          content = data['data']
+          cache_key = ['myscout', 'template', section_id, id]
+          cache_write(api, cache_key, content)
+          return content
+        end
+
+        return nil
+      end
+
+    end # class Myscout::Template
+
+  end
+   
+end

data/spec/osm/api_spec.rb

@@ -179,6 +179,11 @@ describe "API" do
       expect{ Osm::Api.authorize('email@example.com', 'password') }.to raise_error(Osm::Error, 'Error message')
     end
 
+    it "Raises an error if OSM returns an error (as a hash in a hash)" do
+      HTTParty.stub(:post) { OsmTest::DummyHttpResult.new(:response=>{:code=>'200', :body=>'{"error":{"message":"Error message"}}'}) }
+      expect{ Osm::Api.authorize('email@example.com', 'password') }.to raise_error(Osm::Error, 'Error message')
+    end
+
     it "Raises an error if OSM returns an error (as a plain string)" do
       HTTParty.stub(:post) { OsmTest::DummyHttpResult.new(:response=>{:code=>'200', :body=>'Error message'}) }
       expect{ Osm::Api.authorize('email@example.com', 'password') }.to raise_error(Osm::Error, 'Error message')

data/spec/osm/email_spec.rb

@@ -0,0 +1,539 @@
+# encoding: utf-8
+require 'spec_helper'
+
+describe "Email" do
+
+  describe "Get emails for contacts" do
+
+    it "Single member" do
+      @api.should_receive(:perform_query).with("/ext/members/email/?action=getSelectedEmailsFromContacts&sectionid=1&scouts=2", {"contactGroups" => '["contact_primary_member"]'}){
+        {
+          "emails"=>{
+            "2"=>{
+              "emails"=>["john@example.com"],
+              "firstname"=>"John",
+              "lastname"=>"Smith"
+            }
+          },
+          "count"=>1
+        }
+      }
+
+      result = Osm::Email.get_emails_for_contacts(@api, 1, :member, 2)
+      result.should == {
+        '2' => {
+          'emails' => ['john@example.com'],
+          'firstname' => 'John',
+          'lastname' => 'Smith'
+        }
+      }
+    end
+
+    it "Several members" do
+      @api.should_receive(:perform_query).with("/ext/members/email/?action=getSelectedEmailsFromContacts&sectionid=1&scouts=2,3", {"contactGroups" => '["contact_primary_member"]'}){
+        {
+          "emails"=>{
+            "2"=>{
+              "emails"=>["john@example.com"],
+              "firstname"=>"John",
+              "lastname"=>"Smith"
+            },
+            "3"=>{
+              "emails"=>["jane@example.com","jane2@example.com"],
+              "firstname"=>"Jane",
+              "lastname"=>"Smith"
+            }
+          },
+          "count"=>3
+        }
+      }
+
+      result = Osm::Email.get_emails_for_contacts(@api, 1, :member, [2,3])
+      result.should == {
+        '2' => {
+          'emails' => ['john@example.com'],
+          'firstname' => 'John',
+          'lastname' => 'Smith'
+        },
+        '3' => {
+          'emails' => ['jane@example.com', 'jane2@example.com'],
+          'firstname' => 'Jane',
+          'lastname' => 'Smith'
+        }
+      }
+    end
+
+    it "Requires at least one contact" do
+      @api.should_not_receive(:perform_query)
+      expect{ Osm::Email.get_emails_for_contacts(@api, 1, [], [2]) }.to raise_error ArgumentError, "You must pass at least one contact"
+    end
+
+    it "Checks for invalid contacts" do
+      @api.should_not_receive(:perform_query)
+      expect{ Osm::Email.get_emails_for_contacts(@api, 1, [:invalid_contact], [2]) }.to raise_error ArgumentError, "Invalid contact - :invalid_contact"
+    end
+
+    it "Requires at least one member" do
+      @api.should_not_receive(:perform_query)
+      expect{ Osm::Email.get_emails_for_contacts(@api, 1, [:primary], []) }.to raise_error ArgumentError, "You must pass at least one member"
+    end
+
+  end # describe Get emails for conatcts
+
+  describe "Send email" do
+
+    it "With cc" do
+      @api.should_receive(:perform_query).with("ext/members/email/?action=send", {
+        'sectionid' => 1,
+        'emails' => '{"2":{"firstname":"John","lastname":"Smith","emails":["john@example.com"]}}',
+        'scouts' => '2',
+        'cc' => 'cc@example.com',
+        'from' => 'Sender <from@example.com>',
+        'subject' => 'Subject of email',
+        'body' => 'Body of email',
+      }){ {'ok'=>true} }
+
+      Osm::Email.send_email(
+        @api,
+        1,
+        {'2'=>{'firstname'=>'John', 'lastname'=>'Smith', 'emails'=>['john@example.com']}},
+        'cc@example.com',
+        'Sender <from@example.com>',
+        'Subject of email',
+        'Body of email',
+      ).should == true
+    end
+
+    it "Without cc" do
+      @api.should_receive(:perform_query).with("ext/members/email/?action=send", {
+        'sectionid' => 1,
+        'emails' => '{"2":{"firstname":"John","lastname":"Smith","emails":["john@example.com"]}}',
+        'scouts' => '2',
+        'cc' => '',
+        'from' => 'Sender <from@example.com>',
+        'subject' => 'Subject of email',
+        'body' => 'Body of email',
+      }){ {'ok'=>true} }
+
+      Osm::Email.send_email(
+        @api,
+        1,
+        {'2'=>{'firstname'=>'John', 'lastname'=>'Smith', 'emails'=>['john@example.com']}},
+        'Sender <from@example.com>',
+        'Subject of email',
+        'Body of email',
+      ).should == true
+    end
+
+    it "To several members" do
+      @api.should_receive(:perform_query).with("ext/members/email/?action=send", {
+        'sectionid' => 1,
+        'emails' => '{"2":{"firstname":"John","lastname":"Smith","emails":["john@example.com"]},"3":{"firstname":"Jane","lastname":"Smith","emails":["jane@example.com"]}}',
+        'scouts' => '2,3',
+        'cc' => '',
+        'from' => 'Sender <from@example.com>',
+        'subject' => 'Subject of email',
+        'body' => 'Body of email',
+      }){ {'ok'=>true} }
+
+      Osm::Email.send_email(
+        @api,
+        1,
+        {'2'=>{'firstname'=>'John', 'lastname'=>'Smith', 'emails'=>['john@example.com']},'3'=>{'firstname'=>'Jane', 'lastname'=>'Smith', 'emails'=>['jane@example.com']}},
+        'Sender <from@example.com>',
+        'Subject of email',
+        'Body of email',
+      ).should == true
+    end
+
+  end # describe Send email
+
+
+  describe "DeliveryReport" do
+
+    describe "Attribute validity -" do
+
+      before :each do
+        @report = Osm::Email::DeliveryReport.new(
+          id:             1,
+          section_id:     1,
+          sent_at:        Time.new(2016, 10, 27, 13, 0),
+          subject:        'Subject line of email',
+          recipients:     [],
+        )
+      end
+
+      %w{id section_id}.each do |attribute|
+        it attribute do
+          @report.send("#{attribute}=", 0)
+          @report.valid?.should == false
+          @report.errors.messages[attribute.to_sym].should == ["must be greater than 0"]
+        end
+      end
+
+      %w{sent_at subject}.each do |attribute|
+        it attribute do
+          @report.send("#{attribute}=", nil)
+          @report.valid?.should == false
+          @report.errors.messages[attribute.to_sym].should == ["can't be blank"]
+        end
+      end
+
+      describe "recipients" do
+
+        it "Empty array allowed" do
+          @report.recipients = []
+          @report.valid?.should == true
+          @report.errors.messages[:recipients].should == nil
+        end
+
+        it "Invalid item in array not allowed" do
+          @report.recipients = [Osm::Email::DeliveryReport::Recipient.new()]
+          @report.valid?.should == false
+          @report.errors.messages[:recipients].should == ["contains an invalid item"]
+        end
+
+        it "Something other than a recipient not allowed" do
+          @report.recipients = [Time.now]
+          @report.valid?.should == false
+          @report.errors.messages[:recipients].should == ["items in the Array must be a Osm::Email::DeliveryReport::Recipient"]
+        end
+
+      end # describe Email -> DeliveryReport : Invalid without : Recipients
+
+    end # describe Email -> DeliveryReport : Invalid without
+
+
+    it "Fetch delivery reports from OSM" do
+      response = [
+        {'id'=>"0", 'name'=>"ALL", 'type'=>"all", 'count'=>47},
+        {'id'=>123, 'name'=>'01/02/2003 04:05 - Subject of email - 1', 'type'=>'email', 'parent'=>'0', 'hascontent'=>true, 'errors'=>0, 'opens'=>0, 'warnings'=>0},
+        {'id'=>'123-1', 'name'=>'a@example.com - delivered', 'type'=>'oneEmail', 'status'=>'delivered', 'email'=>'a@example.com', 'email_key'=>'aexamplecom', 'hascontent'=>true, 'member_id'=>'12', 'parent'=>123, 'status_raw'=>'delivered'},
+        {'id'=>'123-2', 'name'=>'b@example.com - processed', 'type'=>'oneEmail', 'status'=>'processed', 'email'=>'b@example.com', 'email_key'=>'bexamplecom', 'hascontent'=>true, 'member_id'=>'23', 'parent'=>123, 'status_raw'=>'processed'},
+        {'id'=>'123-3', 'name'=>'c@example.com - bounced', 'type'=>'oneEmail', 'status'=>'bounced', 'email'=>'c@example.com', 'email_key'=>'cexamplecom', 'hascontent'=>true, 'member_id'=>'34', 'parent'=>123, 'status_raw'=>'bounced'},
+      ]
+
+      HTTParty.should_receive(:post).with('https://www.onlinescoutmanager.co.uk/ext/settings/emails/?action=getDeliveryReport&sectionid=1234', {:body => {
+        'apiid' => @CONFIGURATION[:api][:osm][:id],
+        'token' => @CONFIGURATION[:api][:osm][:token],
+        'userid' => 'user_id',
+        'secret' => 'secret',
+      }}).once { OsmTest::DummyHttpResult.new(:response=>{:code=>'200', :body=>response.to_json}) }
+
+      reports = Osm::Email::DeliveryReport.get_for_section(@api, 1234)
+      reports.count.should == 1
+      report = reports[0]
+      report.id.should == 123
+      report.sent_at.should == Time.new(2003, 2, 1, 4, 5)
+      report.subject.should == 'Subject of email - 1'
+      report.section_id.should == 1234
+
+      report.recipients.count.should == 3
+      recipients = report.recipients.sort{ |a,b| a.id <=> b.id }
+      recipients[0].delivery_report.should == report
+      recipients[0].id.should == 1
+      recipients[0].member_id.should == 12
+      recipients[0].address.should == 'a@example.com'
+      recipients[0].status.should == :delivered
+      recipients[1].delivery_report.should == report
+      recipients[1].id.should == 2
+      recipients[1].member_id.should == 23
+      recipients[1].address.should == 'b@example.com'
+      recipients[1].status.should == :processed
+      recipients[2].delivery_report.should == report
+      recipients[2].id.should == 3
+      recipients[2].member_id.should == 34
+      recipients[2].address.should == 'c@example.com'
+      recipients[2].status.should == :bounced
+    end
+
+    it "Fetch email from OSM" do
+      email = Osm::Email::DeliveryReport::Email.new
+      report = Osm::Email::DeliveryReport.new(id: 3, section_id: 4)
+
+      Osm::Email::DeliveryReport::Email.should_receive(:fetch_from_osm).with(@api, 4, 3).once{ email }
+      report.get_email(@api).should == email
+    end
+
+    describe "Get recipients of a certain status -" do
+
+      before :each do
+        @processed_recipient = Osm::Email::DeliveryReport::Recipient.new(status: :processed)
+        @delivered_recipient = Osm::Email::DeliveryReport::Recipient.new(status: :delivered)
+        @bounced_recipient   = Osm::Email::DeliveryReport::Recipient.new(status: :bounced)
+
+        @reports = Osm::Email::DeliveryReport.new(recipients: [@processed_recipient, @delivered_recipient, @bounced_recipient])
+      end
+
+      %w{processed delivered bounced}.each do |status|
+        it status do
+          returned = @reports.send("#{status}_recipients")
+          returned.should == [instance_variable_get("@#{status}_recipient")]
+        end
+      end
+
+    end
+
+    describe "Check for recipients of a certain status -" do
+
+      before :each do
+        @processed_recipient = Osm::Email::DeliveryReport::Recipient.new(status: :processed)
+        @delivered_recipient = Osm::Email::DeliveryReport::Recipient.new(status: :delivered)
+        @bounced_recipient   = Osm::Email::DeliveryReport::Recipient.new(status: :bounced)
+      end
+
+      %w{processed delivered bounced}.each do |status|
+        it status do
+          reports = Osm::Email::DeliveryReport.new(recipients: [instance_variable_get("@#{status}_recipient")])
+          reports.send("#{status}_recipients?").should == true
+
+          reports.recipients = []
+          reports.send("#{status}_recipients?").should == false
+        end
+      end
+
+    end
+
+    it "Converts to a string" do
+      report = Osm::Email::DeliveryReport.new(sent_at: Time.new(2016, 4, 17, 11, 50, 45), subject: 'Subject line of email')
+      report.to_s.should == '17/04/2016 11:50 - Subject line of email'
+    end
+
+    it "Sorts by sent_at then id" do
+      report1 = Osm::Email::DeliveryReport.new(sent_at: Time.new(2016), id: 1)
+      report2 = Osm::Email::DeliveryReport.new(sent_at: Time.new(2017), id: 1)
+      report3 = Osm::Email::DeliveryReport.new(sent_at: Time.new(2017), id: 2)
+      reports = [report2, report3, report1]
+      reports.sort.should == [report1, report2, report3]
+    end
+
+
+    describe "Recipient" do
+
+      describe "Attribute validity -" do
+
+        before :each do
+          @recipient = Osm::Email::DeliveryReport::Recipient.new(
+            id:             1,
+            member_id:      1,
+            address:        'someone@example.com',
+            delivery_report: Osm::Email::DeliveryReport.new,
+            status:         :processed
+          )
+        end
+
+        %w{id member_id}.each do |attribute|
+          it attribute do
+            @recipient.send("#{attribute}=", 0)
+            @recipient.valid?.should == false
+            @recipient.errors.messages[attribute.to_sym].should == ["must be greater than 0"]
+          end
+        end
+
+        it "address" do
+          @recipient.address = nil
+          @recipient.valid?.should == false
+          @recipient.errors.messages[:address].should == ["can't be blank"]
+        end
+
+        describe "status" do
+          [nil, :invalid].each do |status|
+            it "is #{status.inspect}" do
+              @recipient.status = status
+              @recipient.valid?.should == false
+              @recipient.errors.messages[:status].should == ["is not included in the list"]
+            end
+          end
+        end
+
+      end # describe Email -> DeliveryReport -> Recipient : invalid without
+ 
+      it "Fetch email from OSM" do
+        email = Osm::Email::DeliveryReport::Email.new
+        report = Osm::Email::DeliveryReport.new(id: 3, section_id: 4)
+        recipient = Osm::Email::DeliveryReport::Recipient.new(member_id: 456, address: 'd@example.com', delivery_report: report)
+
+        Osm::Email::DeliveryReport::Email.should_receive(:fetch_from_osm).with(@api, 4, 3, 456, 'd@example.com').once{ email }
+        recipient.get_email(@api).should == email
+      end
+
+
+      describe "Unblock address in OSM" do
+        it "Success" do
+          recipient = Osm::Email::DeliveryReport::Recipient.new(address: 'a@example.com', status: :bounced, delivery_report: Osm::Email::DeliveryReport.new(id: 2, section_id: 1))
+          @api.should_receive(:perform_query).once.with('ext/settings/emails/?action=unBlockEmail', {"section_id"=>1, "email"=>"a@example.com", "email_id"=>2}){ {'status'=>true} }
+          recipient.unblock_address(@api).should == true
+        end
+
+        it "Fails with error message" do
+          recipient = Osm::Email::DeliveryReport::Recipient.new(address: 'a@example.com', status: :bounced, delivery_report: Osm::Email::DeliveryReport.new(id: 2, section_id: 1))
+          @api.should_receive(:perform_query).once.with('ext/settings/emails/?action=unBlockEmail', {"section_id"=>1, "email"=>"a@example.com", "email_id"=>2}){ {'status'=>false, 'error'=>'Error message'} }
+          expect{ recipient.unblock_address(@api) }.to raise_error(Osm::Error, 'Error message')
+        end
+
+        it "Fails without error message" do
+          recipient = Osm::Email::DeliveryReport::Recipient.new(address: 'a@example.com', status: :bounced, delivery_report: Osm::Email::DeliveryReport.new(id: 2, section_id: 1))
+          @api.should_receive(:perform_query).once.with('ext/settings/emails/?action=unBlockEmail', {"section_id"=>1, "email"=>"a@example.com", "email_id"=>2}){ {'status'=>false} }
+          recipient.unblock_address(@api).should == false
+        end
+
+        it "Gets something other than a hash" do
+          recipient = Osm::Email::DeliveryReport::Recipient.new(address: 'a@example.com', status: :bounced, delivery_report: Osm::Email::DeliveryReport.new(id: 2, section_id: 1))
+          @api.should_receive(:perform_query).once.with('ext/settings/emails/?action=unBlockEmail', {"section_id"=>1, "email"=>"a@example.com", "email_id"=>2}){ [] }
+          recipient.unblock_address(@api).should == false
+        end
+
+        describe "Doesn't try to unblock when status is" do
+
+          before :each do
+            @recipient = Osm::Email::DeliveryReport::Recipient.new(address: 'a@example.com', delivery_report: Osm::Email::DeliveryReport.new(id: 2, section_id: 1))
+            @api.should_not_receive(:perform_query)
+          end
+
+          (Osm::Email::DeliveryReport::VALID_STATUSES - [:bounced]).each do |status|
+            it status do
+              @recipient.status = status
+              @recipient.unblock_address(@api).should == true
+            end
+          end # each status
+        end
+
+      end # unlock address in OSM
+
+      describe "Check status helpers -" do
+        before :each do
+          @processed_recipient = Osm::Email::DeliveryReport::Recipient.new(status: :processed)
+          @delivered_recipient = Osm::Email::DeliveryReport::Recipient.new(status: :delivered)
+          @bounced_recipient = Osm::Email::DeliveryReport::Recipient.new(status: :bounced)
+        end
+
+        it "processed?" do
+          @processed_recipient.processed?.should == true
+          @delivered_recipient.processed?.should == false
+          @bounced_recipient.processed?.should == false
+        end
+
+        it "delivered?" do
+          @processed_recipient.delivered?.should == false
+          @delivered_recipient.delivered?.should == true
+          @bounced_recipient.delivered?.should == false
+        end
+
+        it "bounced?" do
+          @processed_recipient.bounced?.should == false
+          @delivered_recipient.bounced?.should == false
+          @bounced_recipient.bounced?.should == true
+        end
+
+      end
+
+      it "Converts to a string" do
+        recipient = Osm::Email::DeliveryReport::Recipient.new(address: 'recipient@example.com', status: :delivered)
+        recipient.to_s.should == 'recipient@example.com - delivered'
+      end
+
+      it "Sorts by delivery_report then id" do
+        report1 = Osm::Email::DeliveryReport.new(id: 1)
+        report2 = Osm::Email::DeliveryReport.new(id: 2)
+
+        recipient1 = Osm::Email::DeliveryReport::Recipient.new(delivery_report: report1, id: 1)
+        recipient2 = Osm::Email::DeliveryReport::Recipient.new(delivery_report: report2, id: 1)
+        recipient3 = Osm::Email::DeliveryReport::Recipient.new(delivery_report: report2, id: 2)
+
+        recipients = [recipient3, recipient1, recipient2]
+        recipients.sort.should == [recipient1, recipient2, recipient3]
+      end
+ 
+    end # describe Email -> DeliveryReport -> Recipient
+
+    describe "Email" do
+
+      describe "Attribute validity -" do
+        before :each do
+          @email = Osm::Email::DeliveryReport::Email.new(
+            to:       'to@example.com',
+            from:     'from@example.com',
+            subject:  'Subject of email',
+            body:     'Body of email message.',
+          )
+        end
+        %w{to from subject body}.each do |attribute|
+          it attribute do
+            @email.send("#{attribute}=", nil)
+            @email.valid?.should == false
+            @email.errors.messages[attribute.to_sym].should == ["can't be blank"]
+          end
+        end
+      end # describe Email -> DeliveryReport -> Email : invalid without
+
+      it "Converts to a string" do
+        email = Osm::Email::DeliveryReport::Email.new(
+          to:       'to@example.com',
+          from:     '"Sender" <from@example.com>',
+          subject:  'What the email is about',
+          body:     '<p>Hello person.</p>'
+        )
+        email.to_s.should == "To: to@example.com\nFrom: \"Sender\" <from@example.com>\n\nWhat the email is about\n\nHello person."
+      end
+
+      it "Sorts by subject then from then to" do
+        email1 = Osm::Email::DeliveryReport::Email.new(subject: 'a', from: 'a', to: 'a')
+        email2 = Osm::Email::DeliveryReport::Email.new(subject: 'b', from: 'a', to: 'a')
+        email3 = Osm::Email::DeliveryReport::Email.new(subject: 'b', from: 'b', to: 'a')
+        email4 = Osm::Email::DeliveryReport::Email.new(subject: 'b', from: 'b', to: 'b')
+
+        emails = [email2, email3, email4, email1]
+        emails.sort.should == [email1, email2, email3, email4]
+      end
+
+      describe "Fetch email from OSM" do
+
+        it "For a delivery report" do
+          @api.should_receive(:perform_query).with('ext/settings/emails/?action=getSentEmail&section_id=1&email_id=2&email=&member_id=').once{ {'data'=>{'to'=>'1 Recipient', 'from'=>'"From" <from@example.com>', 'subject'=>'Subject of email', 'sent'=>'16/04/2016 13:45'}, 'status'=>true, 'error'=>nil, 'meta'=>[]} }
+          @api.should_receive(:perform_query).with('ext/settings/emails/?action=getSentEmailContent&section_id=1&email_id=2&email=&member_id=', {}, true).once{ 'This is the body of the email.' }
+
+          email = Osm::Email::DeliveryReport::Email.fetch_from_osm(@api, 1, 2)
+          email.to.should == '1 Recipient'
+          email.from.should == '"From" <from@example.com>'
+          email.subject.should == 'Subject of email'
+          email.body.should == 'This is the body of the email.'
+        end
+
+        it "For a recipient" do
+          @api.should_receive(:perform_query).with('ext/settings/emails/?action=getSentEmail&section_id=1&email_id=2&email=to@example.com&member_id=3').once{ {'data'=>{'to'=>'to@example.com', 'from'=>'"From" <from@example.com>', 'subject'=>'Subject of email', 'sent'=>'16/04/2016 13:45'}, 'status'=>true, 'error'=>nil, 'meta'=>[]} }
+          @api.should_receive(:perform_query).with('ext/settings/emails/?action=getSentEmailContent&section_id=1&email_id=2&email=to@example.com&member_id=3', {}, true).once{ 'This is the body of the email.' }
+
+          email = Osm::Email::DeliveryReport::Email.fetch_from_osm(@api, 1, 2, 3, 'to@example.com')
+          email.to.should == 'to@example.com'
+          email.from.should == '"From" <from@example.com>'
+          email.subject.should == 'Subject of email'
+          email.body.should == 'This is the body of the email.'
+        end
+
+        describe "Error getting meta data" do
+
+          it "Didn't get a Hash" do
+            @api.should_receive(:perform_query).with('ext/settings/emails/?action=getSentEmail&section_id=1&email_id=2&email=&member_id=').once{ nil }
+            expect{ Osm::Email::DeliveryReport::Email.fetch_from_osm(@api, 1, 2) }.to raise_error Osm::Error, 'Unexpected format for response - got a NilClass'
+          end
+
+          it "Got an error from OSM" do
+            @api.should_receive(:perform_query).with('ext/settings/emails/?action=getSentEmail&section_id=1&email_id=2&email=&member_id=').once{ {'success'=>false, 'error'=>'Error message'} }
+            expect{ Osm::Email::DeliveryReport::Email.fetch_from_osm(@api, 1, 2) }.to raise_error Osm::Error, 'Error message'
+          end
+
+        end
+
+        it "Error getting body" do
+          @api.should_receive(:perform_query).with('ext/settings/emails/?action=getSentEmail&section_id=1&email_id=2&email=&member_id=').once{ {'data'=>{'to'=>'1 Recipient', 'from'=>'"From" <from@example.com>', 'subject'=>'Subject of email', 'sent'=>'16/04/2016 13:45'}, 'status'=>true, 'error'=>nil, 'meta'=>[]} }
+          @api.should_receive(:perform_query).with('ext/settings/emails/?action=getSentEmailContent&section_id=1&email_id=2&email=&member_id=', {}, true).once{ raise Osm::Forbidden, 'Email not found' }
+          expect{ Osm::Email::DeliveryReport::Email.fetch_from_osm(@api, 1, 2) }.to raise_error Osm::Error, 'Email not found'
+        end
+
+      end # describe Email -> DeliveryReport -> Email : fetch email from osm
+
+    end # describe Email -> DeliveryReport -> Email
+
+  end # describe Email -> DeliveryReport
+
+end