fellowshipone-api 0.6.0

data/lib/api/person.rb

@@ -0,0 +1,169 @@
+module FellowshipOne
+
+  include Enumerable
+
+  PersonAddress = Struct.new(:is_primary?, :street, :street2, :city, :state, :postal_code)
+  PersonCommunication = Struct.new(:is_phone?, :is_mobile?, :is_email?, :type, :value, :preferred?)
+
+  class Person < ApiObject
+    attr_accessor :addresses,
+                  :communications
+
+    f1_attr_accessor :id,
+                     :uri,
+                     :image_uri,
+                     :old_id,
+                     :i_code,
+                     :household_id,
+                     :old_household_id,
+                     :title,
+                     :salutation,
+                     :prefix,
+                     :first_name,
+                     :last_name,
+                     :suffix,
+                     :middle_name,
+                     :goes_by_name,
+                     :former_name,
+                     :gender,
+                     :date_of_birth,
+                     :marital_status,
+                     :household_member_type,
+                     :is_authorized,
+                     :status,
+                     :occupation,
+                     :employer,
+                     :school,
+                     :denomination,
+                     :former_church,
+                     :bar_code,
+                     :member_envelope_code,
+                     :default_tag_comment,
+                     :weblink,
+                     :solicit,
+                     :thank,
+                     :first_record,
+                     :last_match_date,
+                     :created_date,
+                     :last_updated_date
+
+    # Loads the user by the specified ID.
+    #
+    # @param person_id The ID of the person to load.
+    #
+    # Returns a new Person object.
+    def self.load_by_id(person_id)
+      reader = PersonReader.new(person_id)
+      self.new(reader)
+    rescue
+      nil      
+    end
+
+
+    # Constructor.
+    #
+    # @param reader (optional) The object that has the data.  This can be a PersonReader or Hash object.
+    # @param options (optional) Options for including more information.
+    def initialize(reader = nil, options = {})    
+      @writer_object = PersonWriter
+      if reader.is_a?(PersonReader)
+        initialize_from_json_object(reader.load_feed['person'])
+      elsif reader.is_a?(Hash)
+        initialize_from_json_object(reader)
+      else # new empty
+        reader = PersonReader.new
+        initialize_from_json_object(reader.load_new['person'])
+      end         
+    end
+
+
+    def is_head_of_household?
+      (!self.household_member_type.nil? and self.household_member_type['name'].downcase == 'head')
+    end
+
+
+    def family_role
+      begin
+        self.household_member_type['name']
+      rescue
+        'Other'
+      end
+    end
+
+
+    def is_child?
+      begin
+        self.household_member_type['name'].downcase == 'child'
+      rescue
+        false
+      end
+    end
+
+
+    def addresses
+      return nil if @addresses.nil?
+      return @addresses_cache unless @addresses_cache.nil?
+
+      @addresses_cache = []
+      @addresses['address'].each do |addr|
+        @addresses_cache << PersonAddress.new(
+          addr['addressType']['name'].downcase == 'primary', 
+          addr['address1'], 
+          addr['address2'], 
+          addr['city'], 
+          addr['stProvince'], 
+          addr['postalCode']
+        )
+      end    
+      @addresses_cache
+    end
+
+    def email_addresses
+      self.communications.collect { |c| c[:is_email?] ? c[:value] : nil }.compact
+    end
+
+    def all_numbers
+      self.communications.collect { |c| (c[:is_phone?] or c[:is_mobile?]) ? c[:value] : nil }.compact
+    end  
+
+    def phone_numbers
+      self.communications.collect { |c| c[:is_phone?] ? c[:value] : nil }.compact
+    end  
+
+    def mobile_numbers
+      self.communications.collect { |c| c[:is_mobile?] ? c[:value] : nil }.compact
+    end  
+
+    def communications
+      return nil if @communications.nil?
+      return @communications_cache unless @communications_cache.nil?
+
+      @communications_cache = []
+      @communications['communication'].each do |comm|
+        @communications_cache << PersonCommunication.new(
+          comm['communicationType']['name'].to_s.downcase.include?('phone'), 
+          comm['communicationType']['name'].to_s.downcase.include?('mobile'), 
+          comm['communicationType']['name'].to_s.downcase.include?('email'), 
+          comm['communicationType']['name'], 
+          comm['communicationValue'],
+          comm['preferred'].to_s.downcase == 'true'
+        )
+      end    
+      @communications_cache      
+    end
+
+
+    def _field_map
+      {:id => '@id',
+       :uri => '@uri',
+       :imageUri => '@imageURI',
+       :oldId => '@oldID',
+       :iCode => '@iCode',
+       :householdId => '@householdID',
+       :oldHouseholdId => '@oldHouseholdID'}
+    end
+    
+
+  end
+
+end

data/lib/api/person_list.rb

@@ -0,0 +1,85 @@
+module FellowshipOne
+
+  class PersonList
+
+    include Enumerable
+
+    attr_reader :count, :page_number, :total_records, :additional_pages
+
+
+    # Constructor.
+    #
+    # @param options A hash of options for loading the list.
+    #
+    # Options:
+    # :page - (optional) The page number to get.
+    # :reader - (optional) The Reader to use to load the data.
+    def initialize(options)
+      #options[:page] ||= 1
+      reader = options[:reader] || FellowshipOne::PersonListReader.new(options)
+      @json_data = reader.load_feed
+
+      @count = @json_data['@count'].to_i
+      @page_number = @json_data['@pageNumber'].to_i
+      @total_records = @json_data['@totalRecords'].to_i
+      @additional_pages = @json_data['@additionalPages'].to_i
+    end
+
+
+    # All the people in the list.
+    #
+    # @return array of names (first last).
+    def all_names
+      return [] unless @json_data['person']
+      @json_data['person'].collect { |person| [person['firstName'], person['lastName']].join(' ') }
+    end
+
+    alias_method :names, :all_names
+
+
+    # Get the specified person.
+    #
+    # @param index The index of the person to get.
+    #
+    # @return [Person]
+    def [](index)
+      Person.new( @json_data['person'][index] ) if @json_data['person'] and @json_data['person'][index]
+    end
+
+
+    # This method is needed for Enumerable.
+    def each &block
+      @json_data['person'].each{ |person| yield( Person.new(person) )}
+    end
+  
+    # Alias the count method
+    alias :size :count
+
+    # Checks if the list is empty.
+    #
+    # @return True on empty, false otherwise.
+    def empty?
+      #@json_data['person'].empty?
+      self.count == 0 ? true : false
+    end
+
+
+    # Get all the people ids in the list.
+    #
+    # @return An array of people ids.
+    def ids
+      (@json_data['person'].collect { |person| person['@id'] }).uniq
+    end
+
+
+    # Access to the raw JSON data.  This method is needed for merging lists.
+    #
+    # @returns Raw JSON data.
+    def raw_data
+      @json_data
+    end
+
+  end
+    
+  
+end

data/lib/api/search.rb

@@ -0,0 +1,55 @@
+module FellowshipOne
+
+	class Search
+
+    def self.search_for_contributions_by_date(start_date, end_date, page=1, per_page=500)
+      options = {:start_date => start_date, :end_date => end_date, :page => page, :per_page => per_page}
+      reader = FellowshipOne::ContributionListReader.new(options)
+      ContributionList.new({:reader => reader})
+    end
+
+    def self.search_for_contributions_by_household_id(household_id, page=1, per_page=500)
+      options = {:household_id => household_id, :page => page, :per_page => per_page}
+      reader = FellowshipOne::ContributionListReader.new(options)
+      ContributionList.new({:reader => reader})
+    end    
+
+    def self.search_for_contributions_by_individual_id(individual_id, page=1, per_page=500)
+      options = {:individual_id => individual_id, :page => page, :per_page => per_page}
+      reader = FellowshipOne::ContributionListReader.new(options)
+      ContributionList.new({:reader => reader})
+    end        
+
+    def self.search_for_person_by_name(query, page=1)
+      options = {:page => page, :search_for => query}
+      reader = FellowshipOne::PersonListReader.new(options)
+      PersonList.new({:reader => reader})
+    end
+
+    def self.search_for_person_by_household_id(query, page=1)
+      options = {:page => page, :hsdid => query}
+      reader = FellowshipOne::PersonListReader.new(options)
+      PersonList.new({:reader => reader})
+    end        
+
+    def self.search_for_person_by_communication(query, page=1)
+      options = {:page => page, :communication => query}
+      reader = FellowshipOne::PersonListReader.new(options)
+      PersonList.new({:reader => reader})
+    end    
+
+    def self.search_for_person_created_on_or_after(created_date, page=1)
+      options = {:page => page, :created_date => created_date}
+      reader = FellowshipOne::PersonListReader.new(options)
+      PersonList.new({:reader => reader})
+    end    
+
+    def self.search_for_household_by_name(name, page=1)
+      options = {:page => page, :search_for => name}
+      reader = FellowshipOne::HouseholdListReader.new(options)
+      HouseholdList.new({:reader => reader})
+    end
+
+	end
+
+end

data/lib/auto_load.rb

@@ -0,0 +1,17 @@
+module FellowshipOne
+
+  require FELLOWSHIPONE_LIB_DIR + '/exceptions.rb'
+
+  api_path = FELLOWSHIPONE_LIB_DIR + '/api/'
+  require api_path + 'api_object.rb'
+  Dir["#{api_path}/*.rb"].each { |f| require(f) }
+
+  readers_path = FELLOWSHIPONE_LIB_DIR + '/readers/'
+  require readers_path + 'api_reader.rb'
+  Dir["#{readers_path}/*.rb"].each { |f| require(f) }
+
+  writers_path = FELLOWSHIPONE_LIB_DIR + '/writers/'
+  require writers_path + 'api_writer.rb'
+  Dir["#{writers_path}/*.rb"].each { |f| require(f) }
+
+end

data/lib/common.rb

@@ -0,0 +1,76 @@
+module FellowshipOne
+  require 'json'
+  require 'time'
+
+  def self.api_request(method, path, params = {}, body = '')
+    # response = case method
+    # when :post
+    #   Typhoeus::Request.post(url, {:headers => self._build_api_headers, :body => body})
+    # when :get
+    #   Typhoeus::Request.get(url, {:headers => self._build_api_headers, :params => params})
+    # when :put
+    #   Typhoeus::Request.put(url, {:headers => self._build_api_headers, :body => body})
+    # when :delete
+    #   Typhoeus::Request.delete(url, {:headers => self._build_api_headers, :params => params})
+    # end   
+    
+    response = self._oauth_request_get(method, path, params, body)
+
+    unless response.success?
+      puts response.inspect
+      if response.code > 0
+        raise FellowshipOneExceptions::UnableToConnectToFellowshipOne.new(response.body)
+      else
+        begin
+          error_messages = JSON.parse(response.body)['error_message']
+        rescue
+          response_code_desc = response.headers.partition("\r\n")[0].sub(/^\S+/, '') rescue nil
+          raise FellowshipOneExceptions::UnknownErrorConnectingToFellowshipOne.new("Unknown error when connecting to FellowshipOne API. #{response_code_desc}")
+        else
+          raise FellowshipOneExceptions::FellowshipOneResponseError.new(error_messages)
+        end
+      end
+    end    
+    
+    response
+  end
+
+
+  def self._oauth_request_get(method, path, params, body)
+    consumer_env = FellowshipOne::Api.is_production ? '' : '.staging'
+    base_url = "https://#{FellowshipOne::Api.church_code}#{consumer_env}.fellowshiponeapi.com"
+    url = base_url + path
+    if method == :get
+      url_params = params.collect { |k, v| "#{k}=#{CGI::escape(v.to_s)}" }.join('&')
+      url_params = nil if url_params.empty?
+      url = [url, url_params].compact.join('?')
+      params = {}
+    end 
+
+    consumer = OAuth::Consumer.new(FellowshipOne::Api.consumer_key, 
+                                   FellowshipOne::Api.consumer_secret, 
+                                   :site => base_url, 
+                                   :http_method => method)
+    access_token = OAuth::AccessToken.new(consumer, FellowshipOne::Api.api_token, FellowshipOne::Api.api_secret)
+    
+    options = {:params => params, :method => method, :body => body}
+    oauth_params = {:consumer => consumer, :token => access_token}
+    hydra = Typhoeus::Hydra.new
+    req = Typhoeus::Request.new(url, options)
+
+    # {'Content-Type' => 'application/vnd.fellowshiponeapi.com.people.people.v2+json'}
+    # req.headers.merge!({'Content-Type' => 'application/json'})
+    req.options[:headers].merge!({'Content-Type' => 'application/json'})
+    oauth_helper = OAuth::Client::Helper.new(req, oauth_params.merge(:request_uri => url))
+    
+    #req.headers.merge!({"Authorization" => oauth_helper.header})
+    req.options[:headers].merge!({"Authorization" => oauth_helper.header}) # Signs the request
+    
+    hydra.queue(req)
+    hydra.run
+
+    req.response
+  end  
+
+end
+

data/lib/exceptions.rb

@@ -0,0 +1,5 @@
+module FellowshipOneExceptions
+  class UnableToConnectToFellowshipOne < StandardError; end
+  class UnknownErrorConnectingToFellowshipOne < StandardError; end
+  class FellowshipOneResponseError < StandardError; end
+end

data/lib/fellowship_one.rb

@@ -0,0 +1,54 @@
+require 'oauth'
+require 'yaml'
+require 'typhoeus'
+require 'oauth/request_proxy/typhoeus_request'
+require 'json'
+
+# The path to the lib directory.
+FELLOWSHIPONE_LIB_DIR = File.dirname(__FILE__)
+
+require File.dirname(__FILE__) + '/auto_load.rb'
+
+require File.dirname(__FILE__) + '/common.rb'
+
+require File.dirname(__FILE__) + '/oauth_monkey_patch'
+
+module FellowshipOne
+
+  class Api
+
+    class << self
+      attr_reader :church_code, :consumer_key, :consumer_secret, :api_token, :api_secret, :is_production
+    end    
+
+    def self.establish_connection(church_code, consumer_key, consumer_secret, callback_url, production = true)
+      if church_code.nil? or consumer_key.nil? or consumer_secret.nil?
+        raise FellowshipOneExceptions::UnableToConnectToFellowshipOne.new('Church code, Consumer Key and Consumer Secret cannot be nil.') 
+      end
+
+      consumer_env = production ? '' : '.staging' # Yes, blank is production
+
+      puts "F1 URL: https://#{church_code}#{consumer_env}.fellowshiponeapi.com"
+
+      consumer = OAuth::Consumer.new(consumer_key, consumer_secret, 
+                                     :site => "https://#{church_code}#{consumer_env}.fellowshiponeapi.com",
+                                     :request_token_path => '/v1/Tokens/RequestToken', 
+                                     :authorize_path     => '/v1/PortalUser/Login',
+                                     :access_token_path  => '/v1/Tokens/AccessToken')
+
+      consumer.get_request_token(:oauth_callback => callback_url)
+    end
+
+    def self.connect(church_code, consumer_key, consumer_secret, oauth_token, oauth_secret, production = true)
+      raise FellowshipOneExceptions::UnableToConnectToFellowshipOne.new('Church Code, Token and Secret cannot be nil.') if oauth_token.nil? or oauth_secret.nil?
+      @church_code = church_code
+      @consumer_key = consumer_key
+      @consumer_secret = consumer_secret      
+      @api_token = oauth_token
+      @api_secret = oauth_secret
+      @is_production = production
+    end    
+
+  end
+
+end