npr 0.0.0 → 0.1.0

data/.travis.yml

@@ -0,0 +1,13 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 1.9.2
+  - ruby-head
+
+matrix:
+  include:
+    - rvm: 1.8.7
+      gemfile: gemfiles/Gemfile.rb-1.8.7
+
+notifications:
+  email: false

data/{LICENSE → MIT-LICENSE}

@@ -19,4 +19,4 @@ 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.
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,6 +1,40 @@
-# NPR Ruby Client
+# NPR API Ruby Client
+
+[![Build Status](https://travis-ci.org/bricker88/npr.png)](https://travis-ci.org/bricker88/npr)
+ 
+**NOTE** This gem is a WIP
+
+A simple Ruby client for the 
+[NPR API](http://www.npr.org/api/index).
+
+
+## Support
+
+This gem is tested with these versions (but may 
+work with others):
+
+* Ruby 1.8.7, 1.9.2, 1.9.3, ruby-head
+* NPR API version 0.94
+
+
+## Dependencies
+
+* `faraday >= 0.8.0` (HTTP requests)
+* `faraday_middleware >= 0.9.0` (response processing)
+
+**NOTE** If you are running **Ruby < 1.9**, you will have to install 
+the [json gem](http://rubygems.org/gems/json):
+
+In your Gemfile:
+
+    gem 'json', '~> 1.7.5'
+    
+From the command line:
+
+    $ gem install json
+
+Ruby 1.9+ comes with JSON support built-in!
 
-A simple Ruby client for the NPR API
 
 ## Installation
 
@@ -16,9 +50,87 @@ Or install it yourself as:
 
     $ gem install npr
 
+
 ## Usage
 
-TODO: Write usage instructions here
+### API Key
+
+NPR requires that you have an API key in order to use 
+their API. More information about this (including how 
+to register) can be found at
+[NPR's API Documentation](http://www.npr.org/api/index).
+
+### Configuration
+
+API requests can be configured globally. This is recommended 
+for setting the API Key, but you can also set other parameters
+which will be passed in with every request (unless overridden):
+
+```ruby
+NPR.configure do |config|
+  config.apiKey         = "YOUR_API_KEY"
+  config.sort           = "date descending"
+  config.requiredAssets = "text"
+end
+```
+
+For a Rails application, a good place to put the configuration 
+would be in an initializer, such as `config/initializers/npr_config.rb`.
+
+### DSL
+
+The DSL is modeled after Rails' `ActiveRecord::Relation`, so for the 
+most part, if you understand that, then using the NPR gem will come
+naturally to you!
+
+To find a story by ID:
+
+```ruby
+NPR::Story.find(1999) #=> NPR::Story
+```
+
+`NPR::Story#find` will either return a Story object if it was found,
+or an array of Messages from the NPR API.
+
+Building a query:
+
+```
+NPR::Story.where(date: [2.days.ago..Time.now]).order("date ascending").limit(10).offset(50)
+```
+
+That's a contrived example but it shows all the methods available.
+
+You can also query directly on an `NPR::API::Client` object, if you're
+feeling adventurous:
+
+```ruby
+client = NPR::API::Client.new(apiKey: NPR.config.apiKey)
+client.query(sort: "editor assigned", numResults: "12")
+```
+
+The params that get passed into the `#query` method map directly to
+the parameters that NPR's API accepts. See the 
+[NPR API Input Reference](http://www.npr.org/api/inputReference.php) 
+for all of the options.
+
+
+## TODO
+
+* More Documentation
+* Search functionality
+* Add "select" method to QueryBuilder for the "fields" input
+* Abstract attributes so they're not tied directly to the API response.
+Also to make them more Ruby-conventional (i.e. snake_case)
+    * Example: "apiKey" => :api_key
+* Support for "container" node
+* Support for "parent" node
+* Support for "thumbnail" node
+* Support a way to return raw formats of:
+    * HTML / Javascript (for views)
+    * JSON
+    * ATOM
+    * RSS
+
 
 ## Contributing
 

data/Rakefile

@@ -1,2 +1,8 @@
 #!/usr/bin/env rake
 require "bundler/gem_tasks"
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+task :default => "spec"

data/gemfiles/Gemfile.rb-1.8.7

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in npr.gemspec
+gemspec :path => "../"
+
+gem 'json', '~> 1.7.5'

data/lib/npr/api/client.rb

@@ -0,0 +1,87 @@
+##
+# NPR::API::Client
+#
+# Basic client for interacting with the NPR API.
+#
+# Options passed in when initializing the client will
+# go out with every API request. You may also pass in
+# options to +#query+ for a per-request basis.
+#
+# You can also set params via +client.params+
+#
+# Params should be passed in exactly as they will be sent 
+# to the API. Example: "apiKey", not "api_key"
+# See the API documentation for what those params are.
+#
+module NPR
+  module API
+    class Client
+      attr_accessor :params
+
+      #-----------------
+      # Argument is a hash of params to send to the API.
+      # See <http://www.npr.org/api/inputReference.php> for
+      # API documentation.
+      #
+      # Example:
+      #
+      #   NPR::Client.new(apiKey: "YOUR_API_KEY", sort: "date descending")
+      #
+      # Any parameters passed into this method will override the
+      # global configuration.
+      #
+      def initialize(params={})
+        @params = NPR.config.merge(params)
+        @apiKey = @params.delete(:apiKey)
+      end
+
+      #-----------------
+      # Send a query to the NPR API.
+      #
+      # Accepts a hash of options which get passed
+      # directly to the API.
+      #
+      # Any parameters passed directly into this method
+      # will override both the global configuration,
+      # as well as any parameters stored in this object's
+      # @params.
+      #
+      # Example:
+      #
+      #   client.query(sort: "date descending", requiredAssets: "image")
+      #
+      # For now, this forced JSON output.
+      # TODO: Support more formats
+      #
+      def query(params={})
+        if @apiKey.nil?
+          raise NPR::NotConfiguredError, "apiKey must be set to perform a query"
+        end
+      
+        response = connection.get do |request|
+          request.url NPR::Configuration::API_QUERY_PATH
+          request.params = @params.merge(params)
+          request.params['output'] = "json"
+          request.params['apiKey'] = @apiKey
+        end
+        
+        NPR::API::Response.new(response)
+      end
+
+      #-----------------
+    
+      private
+    
+      #-----------------
+    
+      def connection
+        @connection ||= begin
+          Faraday.new NPR::Configuration::API_ROOT do |conn|
+            conn.response :json, :content_type => /\bjson$/
+            conn.adapter Faraday.default_adapter
+          end
+        end
+      end
+    end # Client
+  end # API
+end # NPR

data/lib/npr/api/message.rb

@@ -0,0 +1,38 @@
+##
+# NPR::API::Message
+#
+# If the API returns any messages, use this class
+# to represent it.
+#
+module NPR
+  module API
+    class Message
+      include NPR::Concern::ShallowAttributes
+      
+      attr_accessor :id, :level
+      shallow_attribute "text", "timestamp"
+
+      #------------------
+    
+      def initialize(json)
+        @_json = json
+        @id    = @_json["id"]
+        @level = @_json["level"]
+      
+        extract_shallow_attributes(@_json)
+      end
+
+      #------------------
+    
+      def error?
+        self.level == "error"
+      end
+    
+      #------------------
+
+      def warning?
+        self.level == "warning"
+      end
+    end # Message
+  end # API
+end # NPR

data/lib/npr/api/query_builder.rb

@@ -0,0 +1,222 @@
+##
+# NPR::API::QueryBuilder
+#
+module NPR
+  module API
+    class QueryBuilder
+      CLASS_BUILDER_METHODS = [
+        :where,
+        :order,
+        :limit,
+        :offset
+      ]
+    
+      attr_reader :_klass, :builder
+
+      #-----------------------
+    
+      def initialize(klass)
+        @_klass  = klass
+        @builder = {}
+      end
+    
+      #-----------------------
+      # Build the params hash.
+      # This is automatically called by #to_a, so it probably
+      # doesn't need to be used manually.
+      def to_params
+        if @_klass == NPR::Entity::Story && @builder[:conditions]
+          conditions = parse_conditions(@builder[:conditions])
+        else
+          conditions = @builder[:conditions]
+        end
+      
+        params = conditions || {}
+        params[:sort]       = @builder[:order]  if @builder[:order]
+        params[:numResults] = @builder[:limit]  if @builder[:limit]
+        params[:startNum]   = @builder[:offset] if @builder[:offset]
+        params.merge!(@builder[:extra])         if @builder[:extra]
+        
+        params
+      end
+
+      #-----------------------
+      # Fire the query and return an Array of stories (or empty [])
+      #
+      # Named +to_a+ to keep in line with ActiveRecord::Relation's
+      # naming convention. It is also aliased as +query+, which 
+      # probably makes a little more sense.
+      #
+      # Returns an Array. If the query returned any stories, then
+      # it will be an array of those stories. If no stories were
+      # returned, then it will be an empty array.
+      #
+      # There is no way to access the List or Messages returned
+      # from the response. This method is meant to be a way to
+      # get to the Stories as quickly and easily as possible.
+      # If you want access to the full Response object, use #query.
+      #
+      # Example:
+      #
+      #   query = NPR::API::QueryBuilder.new(NPR::Story)
+      #   query.where(:id => [100, 150]).to_a
+      #   #=> [NPR::Story, NPR::Story]
+      #
+      #   # Assuming there is no story with an ID of 1
+      #   query.where(:id => 1).to_a
+      #   #=> []
+      #
+      # Note that for this method, +NPR.config.apiKey+ must be set.
+      #
+      def to_a
+        response = self.query
+        stories  = []
+      
+        if list = response.list
+          stories = Array.wrap(response.list.stories)
+        end
+      
+        stories
+      end
+      
+      #-----------------------
+      # Fire the query and return the full Response object
+      # 
+      # Example:
+      # 
+      #   query = NPR::API::QueryBuilder.new(NPR::Story)
+      #   query.where(:id => [100, 150]).query
+      #   #=> NPR::API::Response
+      #
+      # See NPR::API::Response for what methods are available
+      # to you.
+      #
+      # Note that for this method, +NPR.config.apiKey+ must be set.
+      def query
+        client.query(self.to_params)
+      end
+
+      #-----------------------
+      # Add in arbitrary parameters.
+      #
+      # These take precedence over anything set via
+      # any of the other builder methods.
+      #
+      # Accepts a hash of key/values that the API
+      # can receive and handle.
+      #
+      # Example:
+      #
+      #   query.set(apiKey: "YOUR_API_KEY")
+      #
+      def set(params)
+        @builder[:extra] = (@builder[:extra] || {}).merge(params)
+        self
+      end
+      
+      #-----------------------
+      # Merge in the passed-in conditions to what
+      # already exists.
+      #
+      # Accepts a Hash.
+      #
+      # Example:
+      #
+      #   query.where(id: 999, requiredAssets: "text")
+      #
+      # Extra convenience:
+      #
+      # * You may pass an array to :id
+      #
+      #     query.where(id: [70, 180])
+      #
+      # * You may pass a date range to :date
+      #
+      #     last_week = Time.new(2012, 10, 21)
+      #     yesterday = Time.new(2012, 10, 25)
+      #     query.where(date: (last_week..yesterday))
+      # 
+      def where(conditions)
+        @builder[:conditions] = (@builder[:conditions] || {}).merge(conditions)
+        self
+      end
+
+      #-----------------------
+      # Set the order.
+      #
+      # Accepts a String.
+      #
+      # Example:
+      #
+      #   query.order("date descending")
+      #
+      def order(order)
+        @builder[:order] = order
+        self
+      end
+
+      #-----------------------
+      # Set the limit.
+      #
+      # Accepts an Integer.
+      #
+      # Example:
+      #
+      #   query.limit(10)
+      #
+      # Note that NPR limits the maximum results to 20,
+      # and will return only 20 results if more than the
+      # maximum is requested.
+      def limit(limit)
+        @builder[:limit] = limit
+        self
+      end
+    
+      #-----------------------
+      # Offset the number of results 
+      # Useful for pagination
+      #
+      # Accepts an Integer.
+      #
+      # Example:
+      #
+      #   query.offset(100)
+      #
+      def offset(offset)
+        @builder[:offset] = offset
+        self
+      end
+    
+      #-----------------------
+    
+      private
+      
+      def client
+        @client ||= NPR::API::Client.new(:apiKey => NPR.config.apiKey)
+      end
+      
+      #-----------------------
+    
+      def parse_conditions(conditions)
+        parse_conditions!(conditions.dup)
+      end
+
+      #-----------------------
+    
+      def parse_conditions!(conditions)
+        
+        if conditions[:id].is_a? Array
+          conditions[:id] = conditions[:id].join(",")
+        end
+      
+        if conditions[:date].is_a? Range
+          conditions[:startDate] = conditions[:date].first
+          conditions[:endDate]   = conditions[:date].last
+          conditions.delete(:date)
+        end
+      
+        conditions
+      end
+    end # QueryBuilder
+  end # API
+end # NPR

data/lib/npr/api/response.rb

@@ -0,0 +1,32 @@
+##
+# NPR::API::Response
+#
+# Wrapper around a Faraday response object
+# Pass in the full response object from Faraday
+#
+module NPR
+  module API
+    class Response
+      include NPR::Concern::Relation
+      
+      has_many "messages", :key => "message", :class_name => NPR::API::Message
+      attr_reader :raw, :version, :messages, :list
+
+      #--------------------------
+      
+      def initialize(response)
+        create_relations(response)
+        @raw      = response
+        @version  = response.body["version"]
+        
+        if response.body["list"]
+          @list = NPR::Entity::List.new(response.body["list"])
+        end
+        
+        Array.wrap(response.body["message"]).each do |message|
+          @messages.push NPR::API::Message.new(message)
+        end
+      end
+    end # Response
+  end # API
+end # NPR

data/lib/npr/api.rb

@@ -0,0 +1,7 @@
+##
+# :D
+#
+module NPR
+  module API
+  end
+end

data/lib/npr/concern/attr_typecast.rb

@@ -0,0 +1,59 @@
+require 'time'
+
+##
+# NPR::Concern::AttrTypecast
+#
+module NPR
+  #------------------
+  # Attributes that are being typecast to Ruby classes
+  ATTR_TYPES = {
+    "id"               => :string_to_i,
+    "partnerId"        => :string_to_i,
+    "storyDate"        => :string_time_parse, 
+    "pubDate"          => :string_time_parse,
+    "lastModifiedDate" => :string_time_parse,
+    "showDate"         => :string_time_parse,
+    "date"             => :string_time_parse,
+    "segNum"           => :string_to_i,
+    "num"              => :string_to_i,
+    "timestamp"        => :string_time_at,
+    "duration"         => :string_to_i
+  }
+  
+  module Concern
+    module AttrTypecast
+      
+      private
+      
+      #------------------
+      # Typecasting methods
+      def string_to_i(value)
+        value.to_i
+      end
+      
+      #------------------
+      
+      def string_time_parse(value)
+        !value.empty? ? Time.parse(value) : nil
+      end
+      
+      #------------------
+      
+      def string_time_at(value)
+        Time.at(value.to_f)
+      end
+      
+      
+      #------------------
+      #------------------
+      
+      def attr_typecast(key, value)
+        if method = NPR::ATTR_TYPES[key]
+          send method, value
+        else
+          value
+        end
+      end   
+    end # AttrTypecast
+  end # Concern
+end # NPR