simplificator-ruby-kiva 0.1.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,21 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 pascalbetz
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,59 @@
+= simplificator-ruby-kiva
+
+== What
+This is a ruby wrapper for the kiva.org api.
+See build.kiva.org for details.
+
+== Howtow
+
+include Kiva
+
+Api.app_id = 'your api id here, not required but recommended, see build.kiva.org'
+### Loans
+## finding Loans by ID
+
+#puts Loan.find(:id => 180009).terms
+#puts Loan.find(:id => '180009, 180008').size
+#puts Loan.find(:id => [180009, '180008']).size
+
+## finding Loans by lender_id
+#puts Loan.find(:lender_id => 'matt', :page => 1).inspect
+
+## finding Loans
+#puts Loan.find(:query => 'Chinchilla', :page => 1).inspect
+#puts Loan.find(:partner_id => [150, 156, 188, 190, 120], :query => 'Vegetable', :status => :in_repayment, :page => 2).inspect
+
+### Partners
+
+#puts Partner.find().first.inspect
+#puts Partner.find(:id => 1).inspect
+
+
+### Lending Actions
+#LendingAction.recent.first
+
+
+### Journal Entries
+#puts JournalEntry.find(:loan_id => 180009, :include_bulk => true, :page => 10).inspect
+#puts Loan.find(:id => 180009).journal_entries(:include_bulk => true).first.comments
+#puts Comment.find(:journal_entry_id => 28342).inspect
+
+
+### Team
+#puts Team.find(:id => 2).team_since
+#puts Team.find(:shortname => 'buildkiva')
+#puts Team.find(:id => 6341).lenders(:page => 1).inspect
+
+== Note on Patches/Pull Requests
+
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+== Copyright
+
+Copyright (c) 2010 pascalbetz. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,53 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "simplificator-ruby-kiva"
+    gem.summary = %Q{a ruby wrapper for the kiva.org api}
+    gem.description = %Q{a ruby wrapper for the kiva.org api}
+    gem.email = "info@simplificator.com"
+    gem.homepage = "http://github.com/simplificator/simplificator-ruby-kiva"
+    gem.authors = ["simplificator"]
+    gem.add_development_dependency "shoulda", ">= 0"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/test_*.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "simplificator-ruby-kiva #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/ruby-kiva/api.rb

@@ -0,0 +1,55 @@
+module Kiva
+  module Api
+    def self.app_id=(value)
+      @@app_id = value
+    end
+    def self.app_id
+      @@app_id
+    end
+
+
+    module ClassMethods
+      private
+      def json_to_paged_array(data, data_key, many)
+        if many
+          if data[data_key]
+            PagedArray.new(data[data_key].map { |item| self.new(item)}, data['paging'] || {})
+          else
+            PagedArray.new([], {})
+          end
+        else
+          if data[data_key]
+            self.new(data[data_key].first)
+          else
+            nil
+          end
+        end
+      end
+
+      def base_options(options = {})
+        if Api.app_id
+          {:app_id => Api.app_id}.merge(pagination_options(options))
+        else
+          pagination_options(options)
+        end
+      end
+
+      def pagination_options(options = {})
+        { :page => options[:page] || 1}
+      end
+
+      def sanitize_id_parameter(id)
+        Array(id).join(',').gsub(/\s/, '')
+      end
+    end
+
+
+    def self.included(receiver)
+      receiver.instance_eval do
+        extend ClassMethods
+        include HTTParty
+        base_uri 'http://api.kivaws.org/v1'
+      end
+    end
+  end
+end

data/lib/ruby-kiva/borrower.rb

@@ -0,0 +1,21 @@
+module Kiva
+  class Borrower
+    include DynamicInitializer
+    attr_accessor :gender, :pictured, :first_name, :last_name
+
+    def male?
+      self.gender == 'M'
+    end
+    def female?
+      self.gender == 'F'
+    end
+
+    def pictured?
+      self.pictured
+    end
+
+    def to_s
+      "<#{self.first_name} #{self.last_name} #{self.gender} #{self.pictured?}>"
+    end
+  end
+end

data/lib/ruby-kiva/comment.rb

@@ -0,0 +1,14 @@
+module Kiva
+  class Comment
+    include DynamicInitializer
+    include Api
+    attr_accessor :id, :author, :whereabouts, :body, :date
+    typed_attr_accessor :date, Time, :parse
+
+    def self.find(params)
+      if params[:journal_entry_id]
+        json_to_paged_array(get("/journal_entries/#{params[:journal_entry_id]}/comments.json", :query => base_options(params)), 'comments', true)
+      end
+    end
+  end
+end

data/lib/ruby-kiva/country.rb

@@ -0,0 +1,8 @@
+module Kiva
+  class Country
+    include DynamicInitializer
+    attr_accessor :country_code, :name, :region, :iso_code
+
+    typed_attr_accessor :location, Kiva::Location
+  end
+end

data/lib/ruby-kiva/dynamic_initializer.rb

@@ -0,0 +1,30 @@
+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)
+          end
+          attr_reader name
+      end
+    end
+
+    module InstanceMethods
+      def initialize(options = {})
+        options.each do |key, value|
+          self.send("#{key}=", value)
+        end
+      end
+    end
+
+    def self.included(receiver)
+      receiver.extend         ClassMethods
+      receiver.send :include, InstanceMethods
+    end
+  end
+end

data/lib/ruby-kiva/image.rb

@@ -0,0 +1,20 @@
+module Kiva
+  class Image
+    include DynamicInitializer
+    attr_accessor :template_id, :id
+
+    SIZES = %w(w80h80 w200h200 w325h250 w450h360 fullsize)
+
+    def to_s
+      "<Image #{self.template_id} / #{self.id}>"
+    end
+
+    # Build the URL for this Image.
+    # See SIZES for valid sizes, defaults to w80h80
+    def url(size = 'w80h80')
+      raise 'Must have a template id and an id' unless self.template_id && self.id
+      raise "Unknown size #{size}" unless SIZES.include?(size.to_s)
+      "http://www.kiva.org/img/#{size}/#{self.id}.jpg"
+    end
+  end
+end

data/lib/ruby-kiva/journal_entry.rb

@@ -0,0 +1,32 @@
+module Kiva
+  class JournalEntry
+    include DynamicInitializer
+    include Api
+    attr_accessor :id, :body, :subject, :author, :bulk, :comment_count, :recommendation_count
+
+    typed_attr_accessor :date, Time, :parse
+
+    def bulk?
+      self.bulk
+    end
+
+    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)
+      end
+    end
+
+    def comments(params = {})
+      @comments ||= Comment.find(params.merge({:journal_entry_id => self.id}))
+    end
+
+    private
+
+    def self.find_options(options)
+      result = {}
+      result['include_bulk'] = options[:include_bulk] ? 1 : 0
+      result
+    end
+  end
+end

data/lib/ruby-kiva/lender.rb

@@ -0,0 +1,66 @@
+module Kiva
+  class Lender
+    include Api
+    include DynamicInitializer
+    attr_accessor :loan_count, :occupation, :country_code, :name, :loan_because,
+                  :lender_id, :uid, :whereabouts, :invitee_count,
+                  :occupational_info, :personal_url
+
+    typed_attr_accessor :member_since, Time, :parse
+    typed_attr_accessor :team_join_date, Time, :parse
+    typed_attr_accessor :image, Kiva::Image
+
+    def lender_page_url
+      "http://www.kiva.org/lender/#{self.lender_id}"
+    end
+
+    # find the loans for this lender
+    # loans are cached to avoid roundtrips, refetch the lender if you need to refresh loans
+    def loans(params = {})
+      @loans ||= Loan.find(params.merge({:lender_id => self.lender_id}))
+    end
+
+    def to_s()
+      "<Lender #{self.lender_id}>"
+    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
+    #
+    # 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)
+      if params[:id] # find one or many by lender ID
+        data = get("/lenders/#{sanitize_id_parameter(params[:id])}.json", :query => base_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))
+        many = true
+      elsif params[:team_id]
+        data = get("/teams/#{params[:team_id]}/lenders.json", :query => base_options(params))
+        many = true
+      end
+      json_to_paged_array(data, 'lenders', many)
+    end
+  end
+end
+
+# {"loan_count"=>93,
+# "occupation"=>"Entrepreneur",
+# "country_code"=>"US",
+# "name"=>"Matt",
+# "loan_because"=>"I love the stories. ",
+# "lender_id"=>"matt",
+# "invitee_count"=>23,
+# "occupational_info"=>"I co-founded a startup nonprofit (this one!) and I work with an amazing group of people dreaming up ways to alleviate poverty through personal lending. ",
+# "personal_url"=>"www.socialedge.org/blogs/kiva-chronicles",
+# "uid"=>"matt",
+# "whereabouts"=>"San Francisco CA",
+# "image"=>{"template_id"=>1, "id"=>12829},
+# "member_since"=>"2006-01-01T09:01:01Z"}

data/lib/ruby-kiva/lending_action.rb

@@ -0,0 +1,25 @@
+module Kiva
+  class LendingAction
+    include Api
+    include DynamicInitializer
+
+    attr_accessor :id, :sector, :basket_amount
+
+    typed_attr_accessor :date, Time, :parse
+    typed_attr_accessor :lender, Kiva::Lender
+    typed_attr_accessor :loan, Kiva::Loan
+
+
+    def self.recent(options = {})
+      json_to_paged_array(get('/lending_actions/recent.json'), 'lending_actions', true)
+    end
+
+  end
+end
+
+#{"date"=>"2010-04-09T22:00:27Z",
+#{}"id"=>33614166,
+#{}"lender"=>{"country_code"=>"US", "name"=>"Eisakouo Partnership", "lender_id"=>"eisakouopartnership3932", "uid"=>"eisakouopartnership3932", "whereabouts"=>"Columbia PA", "image"=>{"template_id"=>1, "id"=>482823}},
+#{}"loan"=>{"borrower_count"=>1, "status"=>"fundraising", "name"=>"Laoy Lok", "posted_date"=>"2010-04-07T06:40:02Z", "activity"=>"Cattle", "id"=>191433, "description"=>{"languages"=>["en"]}, "partner_id"=>109, "use"=>"To buy a cow for breeding", "loan_amount"=>300, "funded_amount"=>0, "image"=>{"template_id"=>1, "id"=>520519}, "location"=>{"country_code"=>"KH", "country"=>"Cambodia", "geo"=>{"type"=>"point", "level"=>"country", "pairs"=>"13 105"}, "town"=>"Rung Village"},
+#{}"sector"=>"Agriculture",
+#{}"basket_amount"=>0}}

data/lib/ruby-kiva/loan.rb

@@ -0,0 +1,109 @@
+module Kiva
+  class Loan
+    include Api
+    include DynamicInitializer
+
+    attr_accessor :name, :activity, :use, :borrower_count,
+                  :status, :id, :partner_id, :description,
+                  :loan_amount, :funded_amount, :paid_amount, :basket_amount, :sector,
+                  :delinquent, :journal_totals, :terms, :funded_date
+
+    typed_attr_accessor :location, Kiva::Location
+    typed_attr_accessor :image, Kiva::Image
+    typed_attr_accessor :video, Kiva::Video
+    typed_attr_accessor :terms, Kiva::Terms
+    typed_attr_accessor :posted_date, Date, :parse
+    typed_attr_accessor :borrowers, Kiva::Borrower, :new, true
+
+    # description consists of available languages and texts in different languages
+    # texts are only available when doing a find by id
+    def description=(value)
+      @description = value
+      @description_languages = value['languages']
+      @description_texts = value['texts']
+    end
+
+    def description_languages
+      @description_languages
+    end
+
+    def description_texts
+      @description_texts
+    end
+
+    def description_text(language)
+      description_texts[language]
+    end
+
+    # Get the lenders for this loan
+    # Caches the lenders, reload loan if you need to refresh the lenders
+    def lenders(params = {})
+      @lenders ||= Lender.find(params.merge({:loan_id => self.id}))
+    end
+
+
+    def journal_entries(params = {})
+      @journal_entries ||= JournalEntry.find(params.merge({:loan_id => self.id}))
+    end
+
+
+    # Supported options:
+    # * :page: The requested page number
+    def self.recent(options = {})
+      data = get('/loans/newest.json', :query => base_options(options))
+      json_to_paged_array(data, 'loans', true)
+    end
+
+    # Search for Loans.
+    # Different searches are possible
+    # __either:__
+    # :id: An ID, a comma delimited String of IDs or an Array of IDs
+    # __or__
+    # :lender_id: A single ID of a lender
+    # __or__
+    # :team_id : a single ID of a team
+    # __or a combination of__
+    # * :partner_id: A (comma delimited) String of Partner IDs or an Array of partner IDs
+    # * :status: A String or symbol with the Loan status
+    # * :query: A String
+    #
+    # 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)
+    #
+    # 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))
+        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))
+        many = true
+      elsif params[:team_id] # find all loans for a team
+        data = get("/teams/#{params[:team_id]}/loans.json", :query => base_options(params))
+        many = true
+      else # search
+        data = get('/loans/search.json', :query => base_options(params).merge(find_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]
+    end
+
+    private
+
+    def self.find_options(options = {})
+      result = {}
+      if options[:partner_id]
+        result[:partner] = sanitize_id_parameter(options[:partner_id])
+      end
+      result[:status] = options[:status] if options[:status]
+      result[:q] = options[:query] if options[:query]
+      result
+    end
+
+
+  end
+end

data/lib/ruby-kiva/location.rb

@@ -0,0 +1,67 @@
+module Kiva
+  class Location
+    include DynamicInitializer
+    attr_accessor :country, :geo, :town, :type, :level
+    attr_accessor :country_code
+
+    def geo=(value)
+      self.type = value['type']
+      self.level = value['level']
+      self.pairs = value['pairs']
+    end
+
+    def pairs=(value)
+      @pairs = value.split(' ').map() {|item| item.to_f}
+    end
+
+    def pairs
+      @pairs.join(' ')
+    end
+
+
+    # if this is a point?, then returns lat else nil
+    def lat
+      @pairs[0] if self.point?
+    end
+
+    # if this is a point?, then returns lat else nil
+    def lng
+      @pairs[1] if self.point?
+    end
+
+    # true if level is 'town'
+    def town?
+      'town' == self.level
+    end
+    # true if level is 'country'
+    def country?
+      'country' == self.level
+    end
+    # true if level 'exact'
+    def exact?
+      'exact' == self.level
+    end
+
+    # true if type 'point'
+    def point?
+      'point' == self.type
+    end
+    # true if type 'line'
+    def line?
+      'line' == self.type
+    end
+    # true if type 'box'
+    def box?
+      'box' == self.type
+    end
+    # true if type 'polygon'
+    def polygon?
+      'polygon' == self.type
+    end
+
+    def to_s
+      "<Location '%s' '%s' %f/%f>" % [self.country, self.town, self.lat || 0, self.lng || 0]
+    end
+
+  end
+end

data/lib/ruby-kiva/paged_array.rb

@@ -0,0 +1,66 @@
+module Kiva
+  # Adds pagination information to array
+  # Pagination attributes/methods have the same names as the wonderful will_paginate
+  class PagedArray < Array
+    attr_reader :current_page, :per_page, :total_entries, :total_pages
+
+    def initialize(data, options = {})
+      super data
+      @current_page = options['page'] || 1
+      @per_page = options['page_size'] || data.size
+      @total_pages = options['pages'] || 1
+      @total_entries = options['total'] || data.size
+    end
+
+    def offset
+      (self.current_page - 1) * self.per_page
+    end
+
+    def next_page?()
+      self.current_page < self.total_pages
+    end
+
+    def next_page
+      self.current_page + 1 if next_page?
+    end
+
+    def previous_page
+      self.current_page - 1 if previous_page?
+    end
+
+    def previous_page?()
+      self.current_page > 1
+    end
+
+    def from_entry
+      self.offset + 1 unless self.out_of_bounds?
+    end
+
+    def out_of_bounds?
+      self.current_page < 1 || self.current_page > self.total_pages
+    end
+
+    def to_entry
+      [self.offset + self.per_page, self.total_entries].min unless self.out_of_bounds?
+    end
+
+    def inspect
+      "#{pagination_info}\n#{super}"
+    end
+
+    def to_s
+      self.inspect
+    end
+
+    private
+
+
+    def pagination_info
+      if out_of_bounds?
+        "<Page is out of bounds>"
+      else
+        "<Page #{self.current_page} of #{self.total_pages} (entries #{self.from_entry} - #{self.to_entry} of #{self.total_entries}). Previous? #{self.previous_page?}, Next? #{self.next_page?}>"
+      end
+    end
+  end
+end