guidestar 0.0.1

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+coverage
+InstalledFiles
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+
+# YARD artifacts
+.yardoc
+_yardoc
+doc/

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Kelly Martin
+
+MIT License
+
+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,59 @@
+# Guidestar
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'guidestar'
+
+Or install it yourself as:
+
+    $ gem install guidestar
+
+Then configure it with an initializer like `/config/initializers/guidestar.rb`:
+
+    Guidestar.configure do |config|
+      config.username = 'john@guidestar.org'
+      config.password = 'l3tm31n'
+    end
+
+## Usage
+
+Once you initialize it, you can use it in your code via:
+
+    client  = Guidestar::Client.new
+    results = client.search(:keyword => 'monkeys', :limit => 20)
+
+    results.xml
+    # => raw xml data
+
+    results.search_time
+    # => 0.12
+    results.total_count
+    # => 1292
+
+    results.organizations.each do |org|
+      org.name
+      # => 'Monkey Paradise'
+      org.ein
+      # => '23-5553434'
+      org.ein.to_i # with some magic
+      # => 235553434
+      org.tax_deductible?
+      # true
+    end
+
+For getting the next page of results, it behaves similarly to kaminari or will_paginate:
+
+    results.per(50).page(2).organizations
+
+
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/guidestar.gemspec

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/guidestar/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ['Kelly Martin']
+  gem.email         = ['kellymartinv@gmail.com']
+  gem.description   = "Allows access to the Guidestar API"
+  gem.summary       = "Use this gem to access the Guidestar API"
+  gem.homepage      = 'http://github.com/kellym/guidestar'
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = 'guidestar'
+  gem.require_paths = ['lib']
+  gem.version       = Guidestar::VERSION
+
+  gem.add_dependency 'faraday', '~> 0.8'
+  gem.add_dependency 'faraday_middleware', '~> 0.9'
+  gem.add_dependency 'rash', '~> 0.3'
+  gem.add_dependency 'multi_xml', '~> 0.5'
+  gem.add_dependency 'nokogiri', '~> 1.5'
+end

data/lib/faraday/response/raise_guidestar_error.rb

@@ -0,0 +1,38 @@
+require 'faraday'
+
+# @api private
+module Faraday
+  class Response::RaiseGuidestarError < Response::Middleware
+    def on_complete(response)
+      case response[:status].to_i
+      when 303
+        raise Guidestar::SeeOther, error_message(response)
+      when 400
+        raise Guidestar::BadRequest, error_message(response)
+      when 401
+        raise Guidestar::Unauthorized, error_message(response)
+      when 403
+        raise Guidestar::Forbidden, error_message(response)
+      when 404
+        raise Guidestar::NotFound, error_message(response)
+      when 406
+        raise Guidestar::NotAcceptable, error_message(response)
+      when 422
+        raise Guidestar::UnprocessableEntity, error_message(response)
+      when 500
+        raise Guidestar::InternalServerError, error_message(response)
+      when 501
+        raise Guidestar::NotImplemented, error_message(response)
+      when 502
+        raise Guidestar::BadGateway, error_message(response)
+      when 503
+        raise Guidestar::ServiceUnavailable, error_message(response)
+      end
+    end
+
+    def error_message(response)
+      "#{response[:description]}\n#{response[:body]}"
+    end
+  end
+end
+

data/lib/guidestar.rb

@@ -0,0 +1,23 @@
+require "faraday"
+require "faraday_middleware"
+require "guidestar/version"
+require "guidestar/client"
+require "guidestar/error"
+require "guidestar/result"
+
+module Guidestar
+  class << self
+    attr_accessor :username
+    attr_accessor :password
+    attr_accessor :proxy
+    attr_accessor :default_endpoint
+
+    def configure
+      yield self
+      true
+    end
+  end
+
+  Faraday.register_middleware :response,
+    :raise_guidestar_error => lambda { Faraday::Response::RaiseGuidestarError }
+end

data/lib/guidestar/client.rb

@@ -0,0 +1,75 @@
+require 'forwardable'
+require 'faraday/response/raise_guidestar_error'
+require 'guidestar/request'
+require 'guidestar/connection'
+require 'guidestar/client/search'
+
+module Guidestar
+  class Client
+
+    extend Forwardable
+
+    include Guidestar::Request
+    include Guidestar::Connection
+    include Guidestar::Client::Search
+
+    attr_reader :proxy
+
+    # Public: Sets up the core Client object that can be reused throughout
+    # the request.
+    def initialize(options={})
+      @api_url  = options.delete(:endpoint) || Guidestar.default_endpoint
+      @proxy    = options.delete(:proxy) || Guidestar.proxy
+      @username = options.delete(:username) || Guidestar.username
+      @password = options.delete(:password) || Guidestar.password
+      @options  = options.reverse_merge!(:version => 1.0,
+                                         :limit => 25,
+                                         :page => 1 )
+    end
+
+    # Internal: Provides the URL for accessing the API
+    #
+    # Returns a String to the API root url.
+    def api_url
+      @api_url ||= 'https://gsservices.guidestar.org'
+    end
+
+    # Internal: Allows method chaining of parameters to create template
+    # objects.
+    #
+    # Returns a Guidestar::Chain object that mimics the Client.
+    def method_missing(method_name, *args)
+      chain = Chain.new({
+        :publisher => @publisher,
+        :endpoint => @api_url,
+        :proxy => @proxy
+      }.merge(@options))
+      chain.send(method_name.to_sym, *args)
+      chain
+    end
+    private
+
+    # Internal: Provides the default headers when making a request
+    #
+    # Returns a Hash of request headers.
+    def default_headers
+      headers = {
+        :user_agent => 'Guidestar Ruby Gem',
+        :accept => 'application/xml'
+      }
+    end
+
+  end
+
+  class Chain < Client
+    attr_accessor :options
+    def initialize(*args)
+      @options = {}
+      super
+    end
+    def method_missing(method_name, *args)
+      @options[method_name.to_sym]=args.first
+      self
+    end
+  end
+end

data/lib/guidestar/client/search.rb

@@ -0,0 +1,22 @@
+module Guidestar
+  class Client
+    module Search
+      def search(options={})
+        path = '/GuideStarBasic'
+        get(path, options)
+      end
+      def detailed_search(options={})
+        path = '/GuideStarDetail'
+        get(path, options)
+      end
+      def charity_check(options={})
+        path = '/GuideStarCharityCheck'
+        get(path, options)
+      end
+      def npo_validation(options={})
+        path = '/GuideStarNPOValidation'
+        get(path, options)
+      end
+    end
+  end
+end

data/lib/guidestar/connection.rb

@@ -0,0 +1,20 @@
+module Guidestar
+  module Connection
+    # Raw HTTPS connection with Faraday::Connection
+    #
+    # @return [Faraday::Connection]
+    def connection
+      return @connection if @connection
+      params = {}
+      @connection = Faraday.new(:url => api_url, :params => params, :headers => default_headers) do |conn|
+        conn.response :mashify
+        conn.response :xml, :content_type => /\bxml$/
+        conn.response :raise_guidestar_error
+
+        conn.adapter Faraday.default_adapter
+      end
+      @connection.proxy(self.proxy) if self.proxy
+      @connection
+    end
+  end
+end

data/lib/guidestar/error.rb

@@ -0,0 +1,41 @@
+module Guidestar
+  # Custom error class for rescuing from all Guidestar errors
+  class Error < StandardError; end
+
+  # Raised when Guidestar returns a 303 HTTP status code
+  class SeeOther < Error; end
+
+  # Raised when Guidestar returns a 400 HTTP status code
+  class BadRequest < Error; end
+
+  # Raised when Guidestar returns a 401 HTTP status code
+  class Unauthorized < Error; end
+
+  # Raised when Guidestar returns a 403 HTTP status code
+  class Forbidden < Error; end
+
+  # Raised when Guidestar returns a 404 HTTP status code
+  class NotFound < Error; end
+
+  # Raised when Guidestar returns a 406 HTTP status code
+  class NotAcceptable < Error; end
+
+  # Raised when Guidestar returns a 422 HTTP status code
+  class UnprocessableEntity < Error; end
+
+  # Raised when Guidestar returns a 500 HTTP status code
+  class InternalServerError < Error; end
+
+  # Raised when Guidestar returns a 501 HTTP status code
+  class NotImplemented < Error; end
+
+  # Raised when Guidestar returns a 502 HTTP status code
+  class BadGateway < Error; end
+
+  # Raised when Guidestar returns a 503 HTTP status code
+  class ServiceUnavailable < Error; end
+
+  # Raised when missing information is detected in the wrapper
+  class MissingInformation < Error; end
+end
+

data/lib/guidestar/request.rb

@@ -0,0 +1,53 @@
+module Guidestar
+  module Request
+
+    def get(path, data={})
+      Guidestar::Result.new(get_raw(path, data),path,self)
+    end
+
+    def get_raw(path, data={})
+      response = connection.get do |request|
+       request.url("/GuideStar_SearchService/searchservice.asmx#{path}", set_params(data))
+      end
+      response if response.status == 200
+    end
+
+    private
+
+    def set_params(data={})
+      @options.merge!(data)
+      @options[:page_size]  = @options.delete(:limit)     if @options[:limit]
+      @options[:page_size]  = @options.delete(:per)       if @options[:per]
+      @options[:zip_radius] = @options.delete(:zipradius) if @options[:zipradius]
+      @options[:org_name]   = @options.delete(:name)      if @options[:name]
+      @options[:offset]     = (@options.delete(:page)-1)  if @options[:page]
+      builder = Nokogiri::XML::Builder.new do |xml|
+        xml.query do
+          xml.version @options[:version]
+          xml.login @username
+          xml.password @password
+          xml.pageSize @options[:page_size]
+          xml.offset @options[:offset]
+          xml.keyword @options[:keyword]      if @options[:keyword]
+          xml.city @options[:city]            if @options[:city]
+          xml.state @options[:state]          if @options[:state]
+          xml.zip @options[:zip]              if @options[:zip]
+          zml.zipradius @options[:zip_radius] if @options[:zip_radius]
+          xml.ein @options[:ein]              if @options[:ein]
+          xml.orgName @options[:org_name]     if @options[:org_name]
+          if @options[:categories] && @options[:categories].is_a?(Array)
+            @options[:categories].each {|category| xml.category category }
+          end
+
+          if @options[:sub_categories] && @options[:sub_categories].is_a?(Array)
+            @options[:sub_categories].each {|sub_category| xml.subCategory sub_category }
+          end
+
+          xml.nteeCode @options[:ntee_code]  if @options[:ntee_code]
+        end
+      end
+      {:xmlInput => builder.to_xml}
+    end
+  end
+end
+

data/lib/guidestar/result.rb

@@ -0,0 +1,90 @@
+module Guidestar
+  class Result
+    #
+    # Public: Returns the String xml of the response from Guidestar
+    attr_reader :xml
+
+    # Public: Returns the Integer number of results from the query
+    attr_reader :total_count
+
+    # Public: Returns the Float time in seconds to search
+    attr_reader :search_time
+
+    # Public: Returns an Array of organizations from the search
+    def organizations
+      return @organizations if @organizations
+      parse_xml(@client.get_raw(@path, @options))
+      @organizations
+    end
+
+    def initialize(raw_response, path, client)
+      @path = path
+      @client = client
+      parse_xml(raw_response)
+    end
+
+    private
+
+    def parse_xml(raw_response)
+      @xml = ::MultiXml.parse(raw_response.body.string)['root']
+      @total_count = @xml['totalResults'].to_i
+      @search_time = @xml['searchTime'].to_f
+      @options = {}
+
+      @organizations = []
+      orgs = @xml['organizations']['organization']
+      orgs = [orgs] unless orgs.is_a?(Array)
+      orgs.each do |org|
+        org = Hashie::Mash.new clean_keys(org)
+
+        org.delete(:general_information).each do |k,v|
+          org[k]=v
+        end
+        org.delete(:mission_and_programs).each do |type, content|
+          content = Nokogiri::HTML content
+          content = content.text.encode(*encoding_options).strip
+          org[type] = content unless content == 'No information currently in database.'
+        end
+
+        org[:name] = org.delete :org_name
+        org[:tax_deductible] = org[:deductibility] == 'Contributions are deductible, as provided by law'
+        org[:result_position] = org[:result_position].to_i
+
+        ein = org[:ein]
+        def ein.to_i; self.gsub('-','').to_i; end
+
+        @organizations << org
+      end
+    end
+
+    def clean_keys(value)
+      case value
+      when Array
+        value.map { |v| clean_keys v }
+      when Hash
+        Hash[value.map { |k, v| [k.gsub(/(.)([A-Z])/,'\1_\2').downcase.to_sym, clean_keys(v)] }]
+      else
+        value.nil? ? nil : value.strip
+      end
+    end
+
+    def encoding_options
+      @encoding_options ||= [
+        Encoding.find('ASCII'),
+        {
+          :invalid           => :replace,  # Replace invalid byte sequences
+          :undef             => :replace,  # Replace anything not defined in ASCII
+          :replace           => '',        # Use a blank for those replacements
+          :universal_newline => true       # Always break lines with \n
+        }
+      ]
+    end
+    def method_missing(method_name, *args)
+      @options[method_name.to_sym]=args.first
+      @organizations = nil
+      self
+    end
+  end
+end
+
+

data/lib/guidestar/version.rb

@@ -0,0 +1,3 @@
+module Guidestar
+  VERSION = "0.0.1"
+end

metadata

@@ -0,0 +1,140 @@
+--- !ruby/object:Gem::Specification
+name: guidestar
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Kelly Martin
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-02-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: faraday_middleware
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: rash
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: multi_xml
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.5'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+description: Allows access to the Guidestar API
+email:
+- kellymartinv@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- guidestar.gemspec
+- lib/faraday/response/raise_guidestar_error.rb
+- lib/guidestar.rb
+- lib/guidestar/client.rb
+- lib/guidestar/client/search.rb
+- lib/guidestar/connection.rb
+- lib/guidestar/error.rb
+- lib/guidestar/request.rb
+- lib/guidestar/result.rb
+- lib/guidestar/version.rb
+homepage: http://github.com/kellym/guidestar
+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.25
+signing_key: 
+specification_version: 3
+summary: Use this gem to access the Guidestar API
+test_files: []