npr 0.0.0 → 0.1.0

data/lib/npr/entity/member_byline.rb

@@ -0,0 +1,17 @@
+##
+# NPR::Entity::MemberByline
+#
+module NPR
+  module Entity
+    class MemberByline < Base
+      attr_accessor :refId, :num
+      
+      #-------------------
+      
+      def initialize(json)
+        @refId = json["refId"].to_i
+        @num   = json["num"].to_i
+      end
+    end # MemberByline
+  end # Entity
+end # NPR

data/lib/npr/entity/member_promo_art.rb

@@ -0,0 +1,17 @@
+##
+# NPR::Entity::MemberPromoArt
+#
+module NPR
+  module Entity
+    class MemberPromoArt < Base
+      attr_accessor :refId, :num
+      
+      #-------------------
+      
+      def initialize(json)
+        @refId = json["refId"].to_i
+        @num   = json["num"].to_i
+      end
+    end # MemberPromoArt
+  end # Entity
+end # NPR

data/lib/npr/entity/mp3.rb

@@ -0,0 +1,23 @@
+##
+# NPR::Entity::MP3
+#
+module NPR
+  module Entity
+    class MP3 < Base
+      attr_accessor :type, :content
+      
+      #-----------------
+      
+      def initialize(json)
+        @type    = json["type"]
+        @content = json["$text"]
+      end
+      
+      #-----------------
+      
+      def to_s
+        @content
+      end
+    end # MP3
+  end # Entity
+end # NPR

data/lib/npr/entity/organization.rb

@@ -0,0 +1,18 @@
+##
+# NPR::Entity::Organization
+#
+module NPR
+  module Entity
+    class Organization < Base
+      attr_accessor :orgId, :orgAbbr
+      shallow_attribute "name", "website"
+      
+      def initialize(json)
+        extract_shallow_attributes(json)
+        
+        @orgId   = json["orgId"].to_i
+        @orgAbbr = json["orgAbbr"]
+      end
+    end # Organization
+  end # Entity
+end # NPR

data/lib/npr/entity/paragraph.rb

@@ -0,0 +1,27 @@
+##
+# NPR::Entity::Paragraph
+#
+# NPR splits every paragraph into separate
+# database entries. This object will represent
+# a single paragraph for a story.
+#
+module NPR
+  module Entity
+    class Paragraph < Base
+      attr_accessor :num, :content
+
+      #---------------------
+    
+      def initialize(json)
+        @content = json["$text"]
+        @num     = json["num"].to_i
+      end
+
+      #---------------------
+    
+      def to_s
+        @content
+      end
+    end # Paragraph
+  end # Entity
+end # NPR

data/lib/npr/entity/permissions.rb

@@ -0,0 +1,18 @@
+##
+# NPR::Entity::Permissions
+#
+# Audio permissions
+#
+module NPR
+  module Entity
+    class Permissions < Base
+      attr_accessor :download, :stream, :embed
+      
+      def initialize(json)
+        @download = json["download"]["allow"] == "true" if json["download"]
+        @stream   = json["stream"]["allow"]   == "true" if json["stream"]
+        @embed    = json["embed"]["allow"]    == "true" if json["embed"]
+      end
+    end
+  end
+end

data/lib/npr/entity/program.rb

@@ -0,0 +1,24 @@
+##
+# NPR::Entity::Program
+#
+module NPR
+  module Entity
+    class Program < Base
+      attr_accessor :id, :code, :content
+
+      #---------------------
+    
+      def initialize(json)
+        @id      = json["id"].to_i
+        @content = json["$text"]
+        @code    = json["code"]
+      end
+
+      #---------------------
+    
+      def to_s
+        @content
+      end
+    end # Program
+  end # Entity
+end # NPR

data/lib/npr/entity/promo_art.rb

@@ -0,0 +1,17 @@
+##
+# NPR::Entity::PromoArt
+#
+module NPR
+  module Entity
+    class PromoArt < Image
+      attr_accessor :bookEditionId
+      
+      #--------------------
+      
+      def initialize(json)
+        @bookEditionId = json["bookEditionId"].to_i
+        super
+      end
+    end # PromoArt
+  end # Entity
+end # NPR

data/lib/npr/entity/promo_art_book_edition.rb

@@ -0,0 +1,18 @@
+##
+# NPR::Entity::PromoArtBookEdition
+#
+module NPR
+  module Entity
+    class PromoArtBookEdition < Base
+      attr_accessor :refId, :num
+      
+      #-------------------
+      
+      def initialize(json)
+        @refId = json["refId"].to_i
+        @num   = json["num"].to_i
+      end
+    end # PromoArtBookEdition
+  end # Entity
+end # NPR
+    

data/lib/npr/entity/provider.rb

@@ -0,0 +1,23 @@
+##
+# NPR::Entity::Provider
+#
+module NPR
+  module Entity
+    class Provider < Base      
+      attr_accessor :content, :url
+
+      #----------------
+      
+      def initialize(json)
+        @content = json["$text"]
+        @url     = json["url"]
+      end
+      
+      #----------------
+      
+      def to_s
+        @content
+      end
+    end # Provider
+  end # Entity
+end # NPR

data/lib/npr/entity/pull_quote.rb

@@ -0,0 +1,16 @@
+##
+# NPR::Entity::PullQuote
+#
+module NPR
+  module Entity
+    class PullQuote < Base
+      attr_accessor :id
+      shallow_attribute "text", "person", "date"
+      
+      def initialize(json)
+        extract_shallow_attributes(json)
+        @id = json["id"].to_i
+      end
+    end # PullQuote
+  end # Entity
+end # NPR

data/lib/npr/entity/related_link.rb

@@ -0,0 +1,21 @@
+##
+# NPR::Entity::RelatedLink
+#
+module NPR
+  module Entity
+    class RelatedLink < Base
+      attr_accessor :id, :type
+      
+      has_many "links", :key => "link", :class_name => NPR::Entity::Link
+      shallow_attribute "caption"
+      
+      def initialize(json)
+        extract_shallow_attributes(json)
+        create_relations(json)
+        
+        @id   = json["id"].to_i
+        @type = json["type"]
+      end
+    end # RelatedLink
+  end # Entity
+end # NPR

data/lib/npr/entity/show.rb

@@ -0,0 +1,19 @@
+##
+# NPR::Entity::Show
+#
+module NPR
+  module Entity
+    class Show < Base
+      attr_accessor :program
+      shallow_attribute "showDate", "segNum"
+      
+      def initialize(json)
+        extract_shallow_attributes(json)
+        
+        if program = json["program"]
+          @program = NPR::Entity::Program.new(program)
+        end        
+      end
+    end # Show
+  end # Entity
+end # NPR

data/lib/npr/entity/story.rb

@@ -0,0 +1,179 @@
+##
+# NPR::Entity::Story
+#
+module NPR
+  module Entity
+    class Story < Base
+      #-------------------------
+    
+      class << self
+        #-------------------------
+        # Find a story based on ID
+        # 
+        # This method is meant to be a quick, easy
+        # way to find a story just by its ID. 
+        #
+        # If you need more control over what gets
+        # fetched and how, use NPR::Client directly,
+        # or the other chainable methods (+where+,
+        # +order+, etc.)
+        #
+        # It is not possible to pass options into this
+        # method. Therefore, you *must* globally 
+        # configure at least the apiKey using 
+        # +NPR.configure+.
+        #
+        # Example:
+        #
+        #   NPR::Entity::Story.find(1000)
+        #
+        def find(id)
+          response = query_by_id(id)
+        
+          if !response.messages.empty?
+            response.messages
+          else
+            response.list.stories.first
+          end
+        end
+        
+        #-------------------------
+        # Same as above, but returns +nil+ if a single story isn't
+        # returned.
+        def find_by_id(id)
+          response = query_by_id(id)
+          
+          if !response.messages.empty?
+            nil
+          else
+            response.list.stories.first
+          end
+        end
+
+        #-------------------------
+        # For each class builder method defined in NPR::API::QueryBuilder,
+        # define a method on this class which initializes a new
+        # QueryBuilder and proxies to its corresponding method on
+        # Query Builder class.
+        #
+        # We could use ActiveSupport's delegation for this, but 
+        # this is simple enough.
+        NPR::API::QueryBuilder::CLASS_BUILDER_METHODS.each do |method|
+          define_method method do |args|
+            NPR::API::QueryBuilder.new(self).send(method, args)
+          end
+        end
+      
+        #-------------------------
+        
+        private
+      
+        def query_by_id(id)
+          client = NPR::API::Client.new(
+            :apiKey => NPR.config.apiKey,
+            :output => "json")
+
+          client.query(:id => id)
+        end
+      end
+
+      #-------------------------
+      # Association accessors
+    
+      # Attributes that we are using as-is
+      # Use strings so that we don't have to
+      # convert between Strings and Symbols.
+      ATTR_AS_IS = [
+        "thumbnail", 
+        "parent", 
+        "container"
+      ]
+      attr_accessor *ATTR_AS_IS
+      attr_accessor :id, :text, :textWithHtml
+    
+      #------------------
+    
+      has_many "images",        :key => "image",        :class_name => NPR::Entity::Image
+      has_many "bylines",       :key => "byline",       :class_name => NPR::Entity::Byline
+      has_many "audio",         :key => "audio",        :class_name => NPR::Entity::Audio
+      has_many "organizations", :key => "organization", :class_name => NPR::Entity::Organization
+      has_many "links",         :key => "link",         :class_name => NPR::Entity::Link
+      has_many "related_links", :key => "relatedLink",  :class_name => NPR::Entity::RelatedLink
+      has_many "pull_quotes",   :key => "pullQuote",    :class_name => NPR::Entity::PullQuote
+      has_many "shows",         :key => "show",         :class_name => NPR::Entity::Show
+      has_many "members",       :key => "member",       :class_name => NPR::Entity::Member
+      has_many "list_texts",    :key => "listText",     :class_name => NPR::Entity::ListText
+      has_many "promo_arts",    :key => "promoArt",     :class_name => NPR::Entity::PromoArt
+      has_many "book_editions", :key => "bookEdition",  :class_name => NPR::Entity::BookEdition
+      
+      has_one "transcript", :class_name => NPR::Entity::Transcript
+
+      #------------------
+    
+      shallow_attribute(
+        "title",
+        "partnerId",
+        "subtitle",
+        "shortTitle",
+        "teaser",
+        "miniTeaser",
+        "slug",
+        "storyDate",
+        "pubDate",
+        "lastModifiedDate",
+        "keywords",
+        "priorityKeywords",
+        "fullText"
+      )
+        
+      #-------------------------
+
+      def initialize(json)
+        @_json = json
+        @id    = @_json["id"].to_i
+        
+        build_text
+        extract_shallow_attributes(@_json)
+        create_relations(@_json)
+      end
+    
+      #-------------------------
+      # The primary image. Looks at the "type" attribute on 
+      # an image and finds any with type "primary". If none
+      # are found, then return the first image of any type.
+      def primary_image
+        @primary_image ||= begin
+          primary = self.images.find { |i| i["type"] == "primary"}
+          primary || self.images.first
+        end
+      end
+
+      #-------------------------
+      
+      private
+      
+      #-------------------------
+      
+      def build_text
+        if @_json["text"]
+          @text = NPR::Entity::Text.new(@_json["text"])
+        end
+        
+        if @_json["textWithHtml"]
+          @textWithHtml = NPR::Entity::Text.new(@_json["textWithHtml"])
+        end
+      end
+    end # Story
+  end # Entity
+
+  #-------------------------
+  # Alias
+  # This is a shorthand so that users of this library
+  # can work with just NPR::Story, but allowing us to
+  # keep everything organized properly.
+  #
+  # The other classes under Entity aren't part of the 
+  # library's public API, so they don't need to be
+  # aliased.
+  Story = NPR::Entity::Story
+end # NPR

data/lib/npr/entity/text.rb

@@ -0,0 +1,22 @@
+##
+# NPR::Entity::Text
+#
+module NPR
+  module Entity
+    class Text < Base
+      has_many "paragraphs", :key => "paragraph", :class_name => NPR::Entity::Paragraph
+
+      #-----------------
+      
+      def initialize(json)
+        create_relations(json)
+      end
+      
+      #-----------------
+      
+      def to_s
+        @paragraphs.map(&:to_s).join("\n")
+      end
+    end # Text
+  end # Entity
+end # NPR

data/lib/npr/entity/title.rb

@@ -0,0 +1,21 @@
+##
+# NPR::Entity::Title
+#
+module NPR
+  module Entity
+    class Title < Base
+      attr_accessor :num, :content
+      
+      def initialize(json)
+        @num     = json["num"].to_i
+        @content = json["$text"] 
+      end
+      
+      #--------------------
+      
+      def to_s
+        @content
+      end
+    end # Title
+  end # Entity
+end # NPR

data/lib/npr/entity/transcript.rb

@@ -0,0 +1,16 @@
+##
+# NPR::Entity::Transcript
+#
+module NPR
+  module Entity
+    class Transcript < Base
+      has_one "link", :class_name => NPR::Entity::Link
+      
+      #-------------------
+      
+      def initialize(json)
+        create_relations(json)
+      end
+    end # Transcript
+  end # Entity
+end # NPR

data/lib/npr/entity.rb

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

data/lib/npr/errors.rb

@@ -0,0 +1,17 @@
+##
+# Errors
+#
+module NPR
+  class ClientError < StandardError
+  end
+  
+  #-------------------
+  
+  class ServerError < StandardError
+  end
+  
+  #-------------------
+  
+  class NotConfiguredError < ClientError
+  end  
+end # NPR

data/lib/npr/version.rb

@@ -1,3 +1,3 @@
 module NPR
-  VERSION = "0.0.0"
+  VERSION = "0.1.0"
 end

data/lib/npr.rb

@@ -1,5 +1,66 @@
-require "npr/version"
-
+##
+# NPR
+#
 module NPR
-  # Your code goes here...
 end
+
+#------------------
+# Dependencies
+require 'faraday'
+require 'faraday_middleware'
+require "npr/core_ext/array/wrap"
+
+#------------------
+# Internal
+require "npr/version"
+require "npr/configuration"
+require "npr/errors"
+require "npr/concern"
+require "npr/concern/attr_typecast"
+require "npr/concern/shallow_attributes"
+require "npr/concern/relation"
+
+#------------------
+# API handlers
+require "npr/api"
+require "npr/api/query_builder"
+require "npr/api/client"
+require "npr/api/message"
+require "npr/api/response"
+
+#------------------
+# NPR Entities
+require "npr/entity"
+require "npr/entity/base"
+require "npr/entity/link"
+require "npr/entity/paragraph"
+require "npr/entity/organization"
+require "npr/entity/transcript"
+require "npr/entity/pull_quote"
+require "npr/entity/related_link"
+require "npr/entity/list_text"
+require "npr/entity/author"
+require "npr/entity/member_promo_art"
+require "npr/entity/title"
+require "npr/entity/intro_text"
+require "npr/entity/member_byline"
+require "npr/entity/promo_art_book_edition"
+require "npr/entity/member"
+require "npr/entity/collection"
+require "npr/entity/provider"
+require "npr/entity/enlargement"
+require "npr/entity/crop"
+require "npr/entity/image"
+require "npr/entity/promo_art"
+require "npr/entity/mp3"
+require "npr/entity/formats"
+require "npr/entity/permissions"
+require "npr/entity/audio"
+require "npr/entity/book"
+require "npr/entity/book_edition"
+require "npr/entity/byline"
+require "npr/entity/program"
+require "npr/entity/show"
+require "npr/entity/text"
+require "npr/entity/story"
+require "npr/entity/list"

data/npr.gemspec

@@ -4,8 +4,8 @@ require File.expand_path('../lib/npr/version', __FILE__)
 Gem::Specification.new do |gem|
   gem.authors       = ["Bryan Ricker"]
   gem.email         = ["bricker@scpr.org"]
-  gem.description   = %q{A Ruby client for the NPR API}
-  gem.summary       = %q{A simple Ruby client for the NPR API}
+  gem.description   = %q{[NPR](http://npr.org) is a news organization. This gem helps you pull its content with a nice Ruby DSL. <http://www.npr.org/api/index>}
+  gem.summary       = %q{A Ruby client for the NPR API}
   gem.homepage      = "http://github.com/bricker88/npr"
 
   gem.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
@@ -14,4 +14,14 @@ Gem::Specification.new do |gem|
   gem.name          = "npr"
   gem.require_paths = ["lib"]
   gem.version       = NPR::VERSION
+  
+  gem.licenses = ['MIT']
+  
+  gem.add_dependency 'faraday', ['>= 0.8.0']
+  gem.add_dependency 'faraday_middleware', ['>= 0.9.0']
+
+  gem.add_development_dependency 'bundler', ['>= 1.0.0']
+  gem.add_development_dependency 'rake', ['>= 0']
+  gem.add_development_dependency 'rspec', ['>= 0']
+  gem.add_development_dependency 'fakeweb', ['>= 0']
 end

data/spec/fixtures/README.md

@@ -0,0 +1,30 @@
+## Fixture Index
+
+* list - 3002 - All Topics
+* 01 - 167019577 - Story with 1 Audio, 1 Image, 1 Byline
+* 02 - 166884441 - Multiple Images
+* 03 - 167016221 - No Results (404-ish)
+* 04 - 00 - Invalid ID
+* 05 - Missing API Key
+* 06 - 167055503,166956822 - More than one ID returned (on purpose)
+
+(awesome story: 166480907)
+
+## Adding more fixtures
+
+`fetch_fixtures.rb` provides an easy way to pull a story 
+from the NPR API in all of the possible formats. This 
+allows us to more easily test edge cases. To use, run 
+from this directory (`spec/fixtures`):
+
+    ruby fetch_formats.rb --key "YOUR_API_KEY" --id 166946294 --filename 04_story_multiple_bylines
+
+The arguments are:
+
+```
+--key      : Your API Key.
+--id       : The ID of the story that you want to pull
+--filename : The filename that the responses will be 
+               written to (in their respective format).
+               (No extension)
+```