open-charities 0.0.1

data/.gitignore

@@ -0,0 +1,6 @@
+*.gem
+Gemfile.lock
+.bundle
+.rbenv-version
+vendor
+

data/Gemfile

@@ -0,0 +1,3 @@
+source :rubygems
+
+gemspec

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2012 GoCardless
+
+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.md

@@ -0,0 +1,61 @@
+# Open Charities
+
+A simple library for querying http://opencharities.org/ database.
+
+## Installation
+
+To install as a standalone
+```sh
+$ gem install open-charities
+```
+or as a dependency in a Gemfile
+```ruby
+gem "open-charities", "~> 0.1.0", require: 'open_charities'
+```
+
+## Usage
+
+```ruby
+charity = OpenCharities.lookup("1149855")
+=> #<OpenCharities::Response:0x00000001738d30 @attributes={"address"...>
+
+charity['title']
+=> "VETERAN'S HEADQUARTERS"
+
+charity.title
+=> "VETERAN'S HEADQUARTERS"
+
+charity.charity_number
+=> "1149855"
+
+charity.address
+=> {"region"=>nil, "raw_address"=>nil, "created_at"=>"2012-11-22T05:00:54+00:00"...}
+```
+As can be seen from this example, some of the attributes are exposed as instance
+methods. More specifically, the methods that are exposed correspond to the
+top-level keys in the Hash containing information about the charity.
+As in the above example, the `address` attribute returns another Hash.
+
+## Caching
+
+Requests can be cached by configuring the gem to use an external cache (for example,
+the Rails cache).
+
+```ruby
+# file config/initializers/open_charities.rb
+
+# swap in your own cache here
+OpenCharities.cache = Rails.cache
+
+# Optional
+OpenCharities.cache_args = { expires_in: 10.minutes }
+```
+
+## Testing
+
+To run the tests, issue `rspec spec` on the command-line.
+
+### Available testing data
+
+There is testing data available `spec/data/veteransheadquarters.json`. The same
+data is used by the tests in `spec/`.

data/lib/open_charities/request.rb

@@ -0,0 +1,37 @@
+module OpenCharities
+
+  class Request
+
+    BASE_URI = "http://opencharities.org/charities/%s.json"
+
+    def initialize(reg_number)
+      @reg_number = validate(reg_number)
+    end
+
+    def perform
+      url = BASE_URI % @reg_number
+      response = with_caching { Faraday.get(url) }
+      Response.new(response)
+    end
+
+    private
+
+    def with_caching(&block)
+      args = OpenCharities.cache_args || {}
+      cache = OpenCharities.cache
+      cache ? cache.fetch(@reg_number, args, &block) : yield
+    end
+
+    def validate(reg_number)
+      number = reg_number.to_s.strip
+
+      # match 7-digit numbers *only*
+      charities_regex = Regexp.new("\\A\\d{7}\\z")
+
+      msg = "#{number} is not a valid UK charity registration number"
+      raise InvalidRegistration.new(msg) unless number =~ charities_regex
+
+      number
+    end
+  end
+end

data/lib/open_charities/response.rb

@@ -0,0 +1,49 @@
+module OpenCharities
+
+  class Response
+
+    attr_reader :attributes
+
+    def initialize(response)
+      check_for_errors(response)
+      parse_response(response)
+    end
+
+    def [](key)
+      @attributes[key]
+    end
+
+    private
+
+    def check_for_errors(response)
+      if response.status == 404
+        msg = "Charity (reg. number %s) not found" % @reg_number
+        raise CharityNotFound.new(msg)
+      end
+
+      unless response.status == 200
+        msg = "OpenCharities responded with status #{response.status}"
+        raise ServerError.new(msg)
+      end
+    end
+
+    def parse_response(response)
+      data = JSON.parse(response.body)
+      @attributes = data["charity"]
+
+      generate_convenience_methods
+    end
+
+    # convert the top-level keys in the returned JSON to singleton methods on
+    # the instance
+    # NOTE: this *only* converts keys that are in the top-level.
+    # for example, instance.address returns a hash, but title returns a string
+    def generate_convenience_methods
+      @attributes.each_pair do |k, v|
+        define_singleton_method(k) { v }
+      end
+    end
+
+  end
+
+end

data/lib/open_charities/version.rb

@@ -0,0 +1,3 @@
+module OpenCharities
+  VERSION = '0.0.1'.freeze
+end

data/lib/open_charities.rb

@@ -0,0 +1,27 @@
+require 'faraday'
+require 'json'
+require 'open_charities/request'
+require 'open_charities/response'
+
+module OpenCharities
+
+  class CharityNotFound < StandardError
+  end
+
+  class InvalidRegistration < StandardError
+  end
+
+  class ServerError < StandardError
+  end
+
+  class << self
+
+    def lookup(reg_number)
+      Request.new(reg_number).perform
+    end
+
+    attr_accessor :cache, :cache_args
+
+  end
+
+end

data/open_charities.gemspec

@@ -0,0 +1,20 @@
+require File.expand_path('../lib/open_charities/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.add_development_dependency 'rspec', '~> 2.9.0'
+  gem.add_development_dependency 'mocha', '~> 0.10.5'
+  gem.add_development_dependency 'webmock', '~> 1.8.8'
+
+  gem.add_runtime_dependency "faraday", "~> 0.8.4"
+  gem.add_runtime_dependency "json"
+
+  gem.name = 'open-charities'
+  gem.summary = "A wrapper around Open Charities API"
+  gem.version = OpenCharities::VERSION.dup
+  gem.authors = ['Karl Sutt']
+  gem.email = ['karl@gocardless.com']
+  gem.homepage = 'https://github.com/gocardless/open-charities'
+  gem.require_paths = ['lib']
+  gem.files = `git ls-files`.split("\n")
+  gem.test_files = `git ls-files -- spec/*`.split("\n")
+end

data/spec/data/veteransheadquarters.json

@@ -0,0 +1 @@
+{"charity":{"address":{"region":null,"raw_address":null,"created_at":"2012-11-22T05:00:54+00:00","country":null,"updated_at":"2012-11-22T05:00:58+00:00","postal_code":"NE24 2EY","lng":-1.5115205,"id":373286,"street_address":"14 WINCHESTER AVENUE, BLYTH","former":false,"addressee_id":329375,"locality":"NORTHUMBERLAND","lat":55.1234131,"addressee_type":"Charity"},"facebook_account_name":null,"financial_breakdown":null,"housing_association_number":null,"vat_number":null,"grants":[],"contact_name":"MR ROGER SMITH","corrected_company_number":null,"created_at":"2012-11-22T05:00:53+00:00","date_registered":"2012-11-21","signed_up_for_1010":false,"classifications":[],"annual_reports":[],"twitter_account_name":null,"company_number":null,"governing_document":"MEMORANDUM AND ARTICLES INCORPORATED 12/06/2012 AS AMENDED BY SPECIAL RESOLUTION REGISTERED AT COMPANIES HOUSE ON 15/11/2012","title":"VETERAN'S HEADQUARTERS","volunteers":null,"area_of_benefit":null,"feed_url":null,"updated_at":"2012-11-22T05:00:54Z","id":329375,"other_names":"VHQ (Working Name)","subsidiary_number":null,"trustees":[{"uid":"11334837","full_name":"FRANK SPRATT"},{"uid":"11334838","full_name":"MR ROGER  SMITH"}],"youtube_account_name":null,"accounts":null,"activities":null,"date_removed":null,"spending":null,"charity_number":"1149855","employees":null,"fax":null,"income":null,"website":"http://www.veteransheadquarters.org.uk","last_checked":"2012-11-22T05:00:54+00:00","manually_updated":null,"telephone":"01670 734037","accounts_date":null,"normalised_title":"veterans headquarters"}}

data/spec/open_charities/open_charities_spec.rb

@@ -0,0 +1,22 @@
+require 'spec_helper'
+
+describe OpenCharities do
+
+  let(:subject) { OpenCharities }
+
+  describe ".lookup" do
+    it "initializes a request" do
+      OpenCharities::Request.expects(:new).with("1234567").
+        returns(stub(perform: true))
+      subject.lookup("1234567")
+    end
+
+    it "calls perform on the request and returns the response" do
+      OpenCharities::Request.stubs(:new).with("1234567").
+        returns(mock(perform: true))
+      subject.lookup("1234567")
+    end
+
+  end
+
+end

data/spec/open_charities/request_spec.rb

@@ -0,0 +1,68 @@
+require 'spec_helper'
+
+describe OpenCharities::Request do
+
+  let(:subject) { OpenCharities::Request }
+
+  describe "#new" do
+    context "throws an exception" do
+      it "with a number that's too short" do
+        expect {
+          subject.new "123456"
+        }.to raise_exception OpenCharities::InvalidRegistration
+      end
+
+      it "that's too long" do
+        expect {
+          subject.new "12345678"
+        }.to raise_exception OpenCharities::InvalidRegistration
+      end
+
+      it "that's nil" do
+        expect {
+          subject.new nil
+        }.to raise_exception OpenCharities::InvalidRegistration
+      end
+
+      it "that contains spaces" do
+        expect {
+          subject.new "1234 ABC"
+        }.to raise_exception OpenCharities::InvalidRegistration
+      end
+
+      it "that contains non alphanumeric chars" do
+        expect {
+          subject.new "1234?456"
+        }.to raise_exception OpenCharities::InvalidRegistration
+      end
+    end
+
+  end
+
+
+  describe "perform" do
+
+    before { @request = subject.new("1149855") }
+
+    it "makes an http request" do
+      OpenCharities::Response.stubs(:new)
+      Faraday.expects(:get).with("http://opencharities.org/charities/1149855.json")
+      @request.perform
+    end
+
+    it "passes the response to a Response object" do
+      stub_response = stub
+      OpenCharities::Response.expects(:new).with(stub_response)
+      Faraday.stubs(:get).returns(stub_response)
+      @request.perform
+    end
+
+    it "caches the request (if enabled)" do
+      cached_response = stub
+      cache_stub = stub(fetch: cached_response)
+      OpenCharities.cache = cache_stub # configure
+      OpenCharities::Response.expects(:new).with(cached_response)
+      @request.perform
+    end
+  end
+end

data/spec/open_charities/response_spec.rb

@@ -0,0 +1,66 @@
+require 'spec_helper'
+
+describe OpenCharities::Response do
+
+  let(:subject) { OpenCharities::Response }
+
+  context "with a successful http response" do
+    before do
+      url = "http://opencharities.org/charities/1149855.json"
+      stub_request(:get, url).to_return({
+        body: load_fixture("veteransheadquarters.json"),
+        status: 200
+      })
+      @response = subject.new(Faraday.get(url))
+    end
+
+    it "loads attributes into the object body" do
+      @response["title"].should == "VETERAN'S HEADQUARTERS"
+    end
+
+    it "makes raw attributes available as well" do
+      @response.attributes["title"].should == "VETERAN'S HEADQUARTERS"
+    end
+
+    it "converts top-level hash keys into singleton methods" do
+      @response.title.should == "VETERAN'S HEADQUARTERS"
+      @response.charity_number.should == "1149855"
+    end
+
+    it "leaves nested hashes unconverted" do
+      @response.address.class.should == Hash
+    end
+  end
+
+  context "with a company that doesn't exist" do
+    before do
+      @url = "http://opencharities.org/charities/0000000.json"
+      stub_request(:get, @url).to_return({
+        body: "Not found",
+        status: 404
+      })
+    end
+
+    it "raises an exception" do
+      expect {
+        subject.new(Faraday.get(@url))
+      }.to raise_exception OpenCharities::CharityNotFound
+    end
+  end
+
+  context "when the server is down" do
+    before do
+      @url = "http://data.OpenCharities.gov.uk/doc/company/12345678.json"
+      stub_request(:get, @url).to_return({
+        body: "Oh noes",
+        status: 500
+      })
+    end
+
+    it "raises an exception" do
+      expect {
+        subject.new(Faraday.get(@url))
+      }.to raise_exception OpenCharities::ServerError
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,18 @@
+require 'mocha'
+require 'json'
+require 'webmock/rspec'
+
+require 'open_charities'
+
+RSpec.configure do |config|
+
+  config.before(:suite) do
+    WebMock.disable_net_connect!(allow_localhost: true)
+  end
+
+  config.mock_with :mocha
+end
+
+def load_fixture(*filename)
+  File.open(File.join('spec', 'data', *filename)).read
+end

metadata

@@ -0,0 +1,145 @@
+--- !ruby/object:Gem::Specification
+name: open-charities
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Karl Sutt
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-11-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.9.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.9.0
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.10.5
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.10.5
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.8.8
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.8.8
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.8.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.8.4
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email:
+- karl@gocardless.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/open_charities.rb
+- lib/open_charities/request.rb
+- lib/open_charities/response.rb
+- lib/open_charities/version.rb
+- open_charities.gemspec
+- spec/data/veteransheadquarters.json
+- spec/open_charities/open_charities_spec.rb
+- spec/open_charities/request_spec.rb
+- spec/open_charities/response_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/gocardless/open-charities
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: A wrapper around Open Charities API
+test_files:
+- spec/data/veteransheadquarters.json
+- spec/open_charities/open_charities_spec.rb
+- spec/open_charities/request_spec.rb
+- spec/open_charities/response_spec.rb
+- spec/spec_helper.rb