simplificator-ruby-kiva 0.1.0 → 0.2.0

data/README.rdoc

@@ -4,7 +4,23 @@
 This is a ruby wrapper for the kiva.org api.
 See build.kiva.org for details.
 
-== Howtow
+== Status
+
+Still work in progress, some tests are missing, documentation is quite weak.
+Most API calls from Kiva are reflected.
+http://build.kiva.org/api offers a list of API methods, not implemented: Methods, Release, Templates
+
+== Attention
+
+Whenever the unknown elements are encountered in the JSON documents, then an exception is raised.
+Let me know if this happens and i will add the missing attributes. Or set Kiva::Api.friendly = true AND let me know.
+
+
+== History
+0.2.0 Updated API to include more functionality, added some tests
+0.1.0 Initial Release
+
+== Howto
 
 include Kiva
 

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.2.0

data/lib/ruby-kiva/api.rb

@@ -1,15 +1,49 @@
 module Kiva
   module Api
+    # set the API id
     def self.app_id=(value)
       @@app_id = value
     end
+    # retrieve the API id
     def self.app_id
-      @@app_id
+      @@app_id if defined? @@app_id
+    end
+
+    def self.friendly=(value)
+      @@friendly = value
+    end
+    def self.friendly
+      @@friendly if defined? @@friendly
     end
 
 
     module ClassMethods
       private
+      # map options to a new hash
+      # options
+      # mappings, an Array with up to 4 elements: [:source_key, :destination_key, sanitize (true, false), valid items]
+      # if mapping size is 1, then items are just copied over to new hash using same key
+      # if mapping size is 2, then items are copied over using :destination_key as the new key
+      # if mapping size is 3, then value is sanitized if mappind[2]
+      # if mapping size is 4, then value is verified to be included in mapping[3]
+      #
+      # if the value is nil in the options hash, then it is not copied
+      def map_options(options, mappings)
+        result = {}
+        mappings.each do |mapping|
+          if options.has_key?(mapping[0])
+            value = options[mapping[0]]
+            raise "Invalid value for #{mapping[0]}: #{value}" if mapping[3] && !mapping[3].include?(value)
+            result[mapping[1] || mapping[0]] = mapping[2] ? sanitize_id_parameter(value) : value
+          end
+        end
+        result
+      end
+
+      # converts JSON to a PagedArray or a single Instance of a ruby-kiva Api class
+      # data: the JSON Date
+      # data_key, the key under which the date for a item is stored
+      # many if true: create an array / if false: create a single instance
       def json_to_paged_array(data, data_key, many)
         if many
           if data[data_key]
@@ -26,20 +60,23 @@ module Kiva
         end
       end
 
+      # basic options
+      # includes App ID if set and adds pagination options if required
       def base_options(options = {})
-        if Api.app_id
-          {:app_id => Api.app_id}.merge(pagination_options(options))
-        else
-          pagination_options(options)
-        end
+        result = pagination_options(options)
+        result[:app_id] = Api.app_id if Api.app_id
+        result
       end
 
+      # builds a new hash with pagination options
       def pagination_options(options = {})
-        { :page => options[:page] || 1}
+        options[:page] ? {:page => options[:page]} : {}
       end
 
+      # sanitizes ID parameters for use in path of service
+      # pass a String or an Array with IDs, returns a comman separated String of IDs, whitespaces removed
       def sanitize_id_parameter(id)
-        Array(id).join(',').gsub(/\s/, '')
+        Array(id).flatten.join(',').gsub(/\s/, '')
       end
     end
 

data/lib/ruby-kiva/dynamic_initializer.rb

@@ -2,22 +2,26 @@ module Kiva
   module DynamicInitializer
     module ClassMethods
       def typed_attr_accessor(name, klass, factory_method = :new, array = false)
-          define_method("#{name}=") do |value|
-            if array
-              typed = value.map() {|item| klass.send(factory_method, item)}
-            else
-              typed = klass.send(factory_method, value)
-            end
-            instance_variable_set("@#{name}", typed)
+         define_method("#{name}=") do |value|
+          if array
+            typed = value.map() {|item| klass.send(factory_method, item)}
+          else
+            typed = klass.send(factory_method, value)
           end
-          attr_reader name
+          instance_variable_set("@#{name}", typed)
+        end
+        attr_reader name
       end
     end
 
     module InstanceMethods
       def initialize(options = {})
         options.each do |key, value|
-          self.send("#{key}=", value)
+          if respond_to?("#{key}=")
+            self.send("#{key}=", value)
+          elsif !Api.friendly
+            raise "Attribute #{key} is not yet supported. Set Api.friendly = true"
+          end
         end
       end
     end

data/lib/ruby-kiva/journal_entry.rb

@@ -5,6 +5,8 @@ module Kiva
     attr_accessor :id, :body, :subject, :author, :bulk, :comment_count, :recommendation_count
 
     typed_attr_accessor :date, Time, :parse
+    typed_attr_accessor :image, Kiva::Image
+    typed_attr_accessor :video, Kiva::Video
 
     def bulk?
       self.bulk
@@ -13,7 +15,10 @@ module Kiva
     def self.find(params)
       if params[:loan_id]
         json_to_paged_array(get("/loans/#{params[:loan_id]}/journal_entries.json",
-          :query => base_options.merge(find_options(params))), 'journal_entries', true)
+          :query => sanitize_options(params)), 'journal_entries', true)
+      else
+        json_to_paged_array(get("/journal_entries/search.json",
+          :query => sanitize_options(params)), 'journal_entries', true)
       end
     end
 
@@ -23,10 +28,17 @@ module Kiva
 
     private
 
-    def self.find_options(options)
-      result = {}
+    OPTION_MAPPINGS = [
+      [:media, :media, false, ['any', 'video', 'image']],
+      [:sort_by, :sort_by, false, ['newest', 'oldest', 'recommendation_count', 'comment_count']],
+      [:partner_id, :partner, true],
+      [:query, :q]
+      ]
+    def self.sanitize_options(options = {})
+      result = base_options(options).merge(map_options(options, OPTION_MAPPINGS))
       result['include_bulk'] = options[:include_bulk] ? 1 : 0
       result
     end
+
   end
 end

data/lib/ruby-kiva/lender.rb

@@ -24,30 +24,48 @@ module Kiva
       "<Lender #{self.lender_id}>"
     end
 
+    def self.newest(params = {})
+      json_to_paged_array(get('/lenders/newest.json', :query => sanitize_options(params)), 'lenders', true)
+    end
+
     # Find Lenders
     # __either__
     # :id : A single ID or a comma Separated String of IDs or an Array of IDs
     # __or__
     # :loan_id : A single loan ID
     # __or__
-    # :team_id : a single team ID
+    # :team_id : a single team ID, supports :sort_by
     #
     # If searching for a single ID, then this method can return nil (no item with this ID found).
     # Otherwise this method will always return a PagedArray instance (which might be empty though)
     # If querying for multiple items, then :page is supported
-    def self.find(params)
+    def self.find(params = {})
       if params[:id] # find one or many by lender ID
-        data = get("/lenders/#{sanitize_id_parameter(params[:id])}.json", :query => base_options(params))
+        data = get("/lenders/#{sanitize_id_parameter(params[:id])}.json", :query => sanitize_options(params))
         many = sanitize_id_parameter(params[:id]).include?(',')
       elsif params[:loan_id] # find lenders for a loan
-        data = get("/loans/#{params[:loan_id]}/lenders.json", :query => base_options(params))
+        data = get("/loans/#{params[:loan_id]}/lenders.json", :query => sanitize_options(params))
         many = true
       elsif params[:team_id]
-        data = get("/teams/#{params[:team_id]}/lenders.json", :query => base_options(params))
+        data = get("/teams/#{params[:team_id]}/lenders.json", :query => sanitize_options(params))
+        many = true
+      else
+        data = get("/lenders/search.json", :query => sanitize_options(params))
         many = true
       end
       json_to_paged_array(data, 'lenders', many)
     end
+
+    private
+    OPTION_MAPPINGS = [
+      [:sort_by, :sort_by, false, ['oldest', 'newest']],
+      [:occupation],
+      [:query, :q]
+      ]
+    def self.sanitize_options(options = {})
+      base_options(options).merge(map_options(options, OPTION_MAPPINGS))
+    end
+
   end
 end
 

data/lib/ruby-kiva/lending_action.rb

@@ -10,9 +10,13 @@ module Kiva
     typed_attr_accessor :loan, Kiva::Loan
 
 
-    def self.recent(options = {})
+    def self.newest(options = {})
       json_to_paged_array(get('/lending_actions/recent.json'), 'lending_actions', true)
     end
+    # renamed from recent to 'newest' to make it consistent with LendingAction and Lender
+    class <<self
+      alias_method :recent, :newest
+    end
 
   end
 end

data/lib/ruby-kiva/loan.rb

@@ -13,7 +13,9 @@ module Kiva
     typed_attr_accessor :video, Kiva::Video
     typed_attr_accessor :terms, Kiva::Terms
     typed_attr_accessor :posted_date, Date, :parse
+    typed_attr_accessor :paid_date, Date, :parse
     typed_attr_accessor :borrowers, Kiva::Borrower, :new, true
+    typed_attr_accessor :payments, Kiva::Payment, :new, true
 
     # description consists of available languages and texts in different languages
     # texts are only available when doing a find by id
@@ -46,10 +48,14 @@ module Kiva
       @journal_entries ||= JournalEntry.find(params.merge({:loan_id => self.id}))
     end
 
+    def loan_updates
+      @loan_updates ||= find_loan_updates()
+    end
+
 
     # Supported options:
     # * :page: The requested page number
-    def self.recent(options = {})
+    def self.newest(options = {})
       data = get('/loans/newest.json', :query => base_options(options))
       json_to_paged_array(data, 'loans', true)
     end
@@ -73,35 +79,52 @@ module Kiva
     # When searching for multiple Loans, then the :page parameter is supported to specify the desired page.
     def self.find(params)
       if params[:id] # find one or many by ID
-        data = get("/loans/#{sanitize_id_parameter(params[:id])}.json", :query => base_options(params))
+        data = get("/loans/#{sanitize_id_parameter(params[:id])}.json", :query => sanitize_options(params))
         many = sanitize_id_parameter(params[:id]).include?(',')
       elsif params[:lender_id] # find all loans for a lender
-        data = get("/lenders/#{params[:lender_id]}/loans.json", :query => base_options(params))
+        data = get("/lenders/#{params[:lender_id]}/loans.json", :query => sanitize_options(params))
         many = true
       elsif params[:team_id] # find all loans for a team
-        data = get("/teams/#{params[:team_id]}/loans.json", :query => base_options(params))
+        data = get("/teams/#{params[:team_id]}/loans.json", :query => sanitize_options(params))
         many = true
       else # search
-        data = get('/loans/search.json', :query => base_options(params).merge(find_options(params)))
+        puts "Searching with #{base_options(params).merge(find_options(params)).inspect}"
+        data = get('/loans/search.json', :query => sanitize_options(params))
         many = true
       end
       json_to_paged_array(data, 'loans', many)
     end
 
     def to_s()
-      "<Loan '%s' (%s) in %s with status %s, from %s>" % [self.name, self.id, self.location, self.status, self.borrowers]
+      "<Loan '%s' (%s) in %s with status %s, from %s>" % [self.name, self.id, self.location, self.id, self.borrowers]
     end
 
     private
 
-    def self.find_options(options = {})
-      result = {}
-      if options[:partner_id]
-        result[:partner] = sanitize_id_parameter(options[:partner_id])
+    def find_loan_updates
+      data = Loan.get("/loans/#{self.id}/updates.json")
+      data['loan_updates'].map do |entry|
+        type = entry.delete('update_type')
+        case type
+        when 'journal_entry' then JournalEntry.new(entry['journal_entry'])
+        when 'payment' then Payment.new(entry['payment'])
+        else raise "unknown type #{type}"
+        end
       end
-      result[:status] = options[:status] if options[:status]
-      result[:q] = options[:query] if options[:query]
-      result
+    end
+
+    OPTION_MAPPINGS = [
+      [:partner_id, :partner, true],
+      [:sort_by, :sort_by, false, ['oldest', 'newest']],
+      [:status, :status, false, ['fundraising', 'funded', 'in_repayment', 'paid', 'defaulted']],
+      [:query, :q],
+      [:gender, :gender, false, ['male', 'female']],
+      [:region, :region, false, ['na', 'ca', 'sa', 'af', 'as', 'me', 'ee']],
+      [:sector],
+      [:country_code],
+    ]
+    def self.sanitize_options(options = {})
+      base_options(options).merge(map_options(options, OPTION_MAPPINGS))
     end
 
 

data/lib/ruby-kiva/partner.rb

@@ -9,8 +9,9 @@ module Kiva
 
     # Find a partner
     # either by :id or all of them
-    # Since kiva does not offer pagination or search,
+    # Since kiva does not offer search,
     # finding by id is implemented in memory/ruby.
+    # Pagination is not supported, page size is 200 and currently there are 143 partners
     # Items are cached but can be reloaded by passing :reload => true (caching is suggested by kiva...)
     def self.find(params = {})
       if params[:id]

data/lib/ruby-kiva/payment.rb

@@ -1,8 +1,10 @@
 module Kiva
   class Payment
     include DynamicInitializer
-    attr_accessor :amount
+    attr_accessor :amount, :local_amount, :rounded_local_amount, :comment, :payment_id
     typed_attr_accessor :due_date, Time, :parse
+    typed_attr_accessor :settlement_date, Time, :parse
+    typed_attr_accessor :processed_date, Time, :parse
 
     def to_s
       "<Payment due at #{self.due_date} : #{self.amount}>"

data/lib/ruby-kiva/team.rb

@@ -1,5 +1,6 @@
 module Kiva
   class Team
+
     include DynamicInitializer
     include Api
 
@@ -19,10 +20,31 @@ module Kiva
     # find a team by :id or :shortname
     def self.find(params)
       if params[:id]
-        json_to_paged_array(get("/teams/#{params[:id]}.json", :query => base_options(params)), 'teams', false)
+        data = get("/teams/#{sanitize_id_parameter(params[:id])}.json", :query => sanitize_options(params))
+        many = sanitize_id_parameter(params[:id]).include?(',')
       elsif params[:shortname]
-        json_to_paged_array(get("/teams/using_shortname/#{params[:shortname]}.json", :query => base_options(params)), 'teams', false)
+        data = get("/teams/using_shortname/#{sanitize_id_parameter(params[:shortname])}.json", :query => sanitize_options(params))
+        many = sanitize_id_parameter(params[:shortnames]).include?(',')
+      else
+        data = get("/teams/search.json", :query => sanitize_options(params))
+        many = true
       end
+      json_to_paged_array(data, 'teams', many)
     end
+
+    private
+
+    OPTION_MAPPINGS = [
+      [:sort_by, :sort_by, false, ['oldest', 'newest']],
+      [:occupation],
+      [:query, :q],
+      [:country_code],
+      [:membership_type, :membership_type, false, ['open', 'closed']],
+      [:category, :category, false, ['Alumni Groups', 'Businesses', 'Businesses - Internal Groups', 'Clubs', 'Colleges/Universities', 'Common Interest', 'Events', 'Families', 'Field Partner Fans', 'Friends', 'Local Area', 'Memorials', 'Religious Congregations', 'Schools', 'Sports Groups', 'Youth Groups', 'Other']],
+    ]
+    def self.sanitize_options(options = {})
+      base_options(options).merge(map_options(options, OPTION_MAPPINGS))
+    end
+
   end
 end

data/lib/simplificator-ruby-kiva.rb

@@ -4,4 +4,4 @@ require 'httparty'
 %w( dynamic_initializer api payment borrower location country image paged_array video terms loan
    lender partner lending_action journal_entry comment team).each do |name|
   require File.join(File.dirname(__FILE__), 'ruby-kiva', name)
-end
+end

data/simplificator-ruby-kiva.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{simplificator-ruby-kiva}
-  s.version = "0.1.0"
+  s.version = "0.2.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["simplificator"]

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 1
+  - 2
   - 0
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - simplificator