outside-in 0.1.0 → 1.0.0

data/.gitignore

@@ -1 +1,4 @@
-pkg/
+.yardoc
+*.gem
+config/oi.yml
+doc

data/Gemfile

@@ -0,0 +1,11 @@
+source 'http://rubygems.org'
+
+gem 'activesupport', '3.0.0'
+gem 'httparty'
+gem 'json'
+gem 'simple_uuid'
+
+group 'cli' do
+  gem 'text-reform'
+  gem 'thor'
+end

data/Gemfile.lock

@@ -0,0 +1,24 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activesupport (3.0.0)
+    crack (0.1.8)
+    httparty (0.6.1)
+      crack (= 0.1.8)
+    json (1.4.6)
+    simple_uuid (0.1.1)
+    text-hyphen (1.0.0)
+    text-reform (0.2.0)
+      text-hyphen (~> 1.0.0)
+    thor (0.14.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activesupport (= 3.0.0)
+  httparty
+  json
+  simple_uuid
+  text-reform
+  thor

data/HISTORY

@@ -0,0 +1,2 @@
+1.0.0
+  - Initial release

data/README.md

@@ -0,0 +1,101 @@
+Ruby SDK for the [Outside.in API](http://developers.outside.in/)
+
+## Prerequisites
+
+### Developer account
+
+To make API requests, register for an account at [developers.outside.in](http://developers.outside.in/) to receive a developer key and the shared secret you'll use with the key to sign requests.
+
+### Dependencies
+
+Gem dependencies are managed with [Bundler](http://gembundler.com/). Install them like so:
+
+    $ bundle install
+
+## Usage
+
+    require 'outside_in'
+
+    OutsideIn.key = 'faffledweomercraft'
+    OutsideIn.secret = 'deadbeef'
+    OutsideIn.logger.level = Logger::DEBUG # defaults to WARN
+
+    # find locations by name
+    # returns a hash:
+    #  * total - the total number of matched stories
+    #  * locations - the array of matched locations up to the specified limit (default 10)
+    data = OutsideIn::Location.named("Brooklyn")
+    puts "Total matches: #{data[:total]}"
+    data[:locations].each {|loc| puts "  #{loc.display_name}"}
+
+    # displays:
+    # Total matches: 624
+    #   Brooklyn, NY
+    #   Brooklyn, IL
+    #   Brooklyn, IN
+    # etc.
+
+    # all story finders return a hash:
+    #  * total - the total number of matched stories
+    #  * stories - the array of matched stories up to the specified limit (default 10)
+    #  * location - the identified location -OR-
+    #  * locations - the identified locations (when finding stories for multiple location UUIDs)
+
+    # city, state and neighborhood names are case-insensitive.
+    # states can be identified by name or postal abbreviation.
+
+    # find stories for a zip code
+    data = OutsideIn::Story.for_zip_code("11211")
+    puts "Total stories for #{data[:location].display_name}: #{data[:total]}"
+    data[:stories].each {|story| puts "  #{story.title} - #{story.feed_title}"}
+
+    # displays:
+    # Total stories for 11211: 438
+    #   Fashionistas to Go Higher-End with 11K-Plus Feet at 550 Seventh - The New York Observer Real Estate
+    #   Carlos C.'s Review of East River State Park - Brooklyn (3/5) on Yelp - Yelp Reviews New York
+    #   What's going on Tuesday? - Brooklyn Vegan
+    # etc.
+
+    # find by state
+    data = OutsideIn::Story.for_state("New York")
+
+    # find by city
+    data = OutsideIn::Story.for_city("NY", "New York")
+
+    # find by neighborhood
+    data = OutsideIn::Story.for_nabe("ny", "new york", "williamsburg")
+
+    # find by location UUID
+    data = OutsideIn::Story.for_uuids([
+      "a02aa3e4-2aaa-41d7-b9d7-45642eb1c557", # Brooklyn, NY
+      "98653b8d-fa8f-4d50-93b2-f3977a81f40c", # Brooklyn, Jacksonville, FL
+    ])
+
+See [the class docs](http://rdoc.info/github/outsidein/api-rb/master/frames) for more information.
+
+## CLI
+
+A set of Thor tasks is provided so that you can call API methods from the command line (read more about Thor at [http://github.com/wycats/thor](http://github.com/wycats/thor)).
+
+The following examples assume you have Thor installed system-wide. If it's local to your bundle, then replace `thor` with `bundle exec thor`.
+
+### Configuration
+
+Copy `config/oi.sample.yml` to `config/oi.yml` and replace the placeholder values with your key and secret.
+
+### Tasks
+
+You can see all available tasks with this command:
+
+    $ thor list oi
+
+See which options are defined for a particular task with this command (replacing the task name as necessary):
+
+    $ thor help oi:locations:named
+
+## Help
+
+* Source code: [http://github.com/outsidein/api-rb](http://github.com/outsidein/api-rb)
+* Class docs: [http://rdoc.info/github/outsidein/api-rb/master/frames](http://rdoc.info/github/outsidein/api-rb/master/frames)
+* General API docs: [http://developers.outside.in/docs](http://developers.outside.in/docs)
+* Post questions in the help forum: [http://developers.outside.in/forum](http://developers.outside.in/forum)

data/Rakefile

@@ -2,13 +2,20 @@ begin
   require 'jeweler'
   Jeweler::Tasks.new do |gemspec|
     gemspec.name = "outside-in"
-    gemspec.summary = "Ruby wrapper on the Outside.In API"
-    gemspec.description = "The Outside.IN Radar API provides hyperlocal news, tweets, and commentary based around a given latitude and longitude. This is a ruby wrapper around that API."
-    gemspec.email = "petkanics@gmail.com"
-    gemspec.homepage = "http://github.com/dob/outsidein"
-    gemspec.authors = ["Doug Petkanics"]
+    gemspec.summary = "Ruby SDK for the Outside.in API"
+    gemspec.email = "brian@outside.in"
+    gemspec.homepage = "http://github.com/outsidein/api-rb"
+    gemspec.authors = ["Brian Moseley"]
   end
-  Jeweler::GemcutterTasks.new
 rescue LoadError
   puts "Jeweler not available. Install it with: gem install jeweler"
 end
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new do |t|
+    t.options = ['--hide-void-return', '--title', 'Outside.in Ruby SDK']
+  end
+rescue LoadError
+  puts "YARD is not available. Install it with: gem install yard"
+end

data/VERSION

@@ -1 +1 @@
-0.1.0
+1.0.0

data/config/oi.sample.yml

@@ -0,0 +1,2 @@
+key: your-developer-key
+secret: your-shared-secret

data/lib/outside_in/base.rb

@@ -0,0 +1,79 @@
+module OutsideIn
+  # The base class for API models.
+  #
+  # Models interact with the remote service through the low level {#call_remote} method. Each model class
+  # defines its own high-level finder methods that encapsulate the remote service call. For example:
+  #
+  #  module OutsideIn
+  #    class Thing < Base
+  #      def self.by_name(name)
+  #        new(call_remote("/things/named/#{URI.escape(name)}"))
+  #      end
+  #    end
+  #  end
+  #
+  # Model attributes are declared using {#api_attr}. Only attributes declared this way are recognized by the
+  # initializer when setting the model's initial state.
+  #
+  # @abstract Subclass and declare attributes with {#api_attr} to implement a custom model class.
+  # @since 1.0
+  class Base
+    class << self
+      # Returns the map of defined attributes for this model class. The keys are attribute symbols and the values are
+      # the attribute classes (or +nil+, indicating that the attribute is of a primitive type).
+      #
+      # @return [Hash<Symbol, Class>]
+      # @since 1.0
+      def api_attrs
+        @api_attrs
+      end
+    end
+
+    # Adds one or more defined attributes for this model class.
+    #
+    # If the first argument is a +Hash+, then its entries are added directly to the defined attributes map.
+    # Otherwise, each argument is taken to be the name of a primitive-typed attribute. In either case,
+    # {::Module#attr_accessor} is called for each attribute.
+    #
+    # @return [void]
+    # @since 1.0
+    def self.api_attr(*names)
+      @api_attrs ||= {}
+      if ! names.empty? && names.first.is_a?(Hash)
+        names.first.each_pair do |name, clazz|
+          @api_attrs[name.to_sym] = clazz
+          attr_accessor(name.to_sym)
+        end
+      else
+        names.each do |name|
+          @api_attrs[name.to_sym] = nil
+          attr_accessor(name.to_sym)
+        end
+      end
+    end
+
+    # Returns a new instance.
+    #
+    # Each entry of +attrs+ whose key identifies a defined model attribute is used to set the value of that
+    # attribute. If the attribute's type is a +Class+, then an instance of that class is created with the raw
+    # value passed to its initializer. Otherwise, the raw value is used directly.
+    #
+    # @param [Hash<Symbol, Object>] attrs the data used to initialize the model's attributes
+    # @return [OutsideIn::Base]
+    # @since 1.0
+    def initialize(attrs = {})
+      self.class.api_attrs.each_pair do |name, clazz|
+        str = name.to_s
+        if attrs.include?(str)
+          v = attrs[str]
+          val = if v.is_a?(Array)
+            v.map {|it| clazz.nil?? it : clazz.new(it)}
+          else
+            clazz.nil?? v : clazz.new(v)
+          end
+          instance_variable_set("@#{str}".to_sym, val)
+        end
+      end
+    end
+  end
+end

data/lib/outside_in/category.rb

@@ -0,0 +1,22 @@
+module OutsideIn
+  # Category model class. Each location has a category that describes its places in the location hierachy, e.g
+  # state, city, neighborhood, zip code, etc.
+  #
+  # Categories have the following attributes:
+  #
+  # * display_name
+  # * name
+  #
+  # @since 1.0
+  class Category < Base
+    api_attr :name, :display_name
+
+    # Returns the category's display name.
+    #
+    # @return [String]
+    # @since 1.0
+    def to_s
+      display_name
+    end
+  end
+end

data/lib/outside_in/location.rb

@@ -0,0 +1,61 @@
+require 'simple_uuid'
+
+module OutsideIn
+  # Location model class.
+  #
+  # Locations have the following attributes:
+  #
+  # * category ({OutsideIn::Category})
+  # * city
+  # * display_name
+  # * lat ({::Float})
+  # * lng ({::Float})
+  # * state
+  # * state_abbrev
+  # * url
+  # * url_name
+  # * uuid ({SimpleUUID::UUID})
+  #
+  # Location finders accept query parameter options as described by {OutsideIn::Location#parameterize_url}. They
+  # return data structures as described by {OutsideIn::Location#query_result}.
+  #
+  # @see http://developers.outside.in/docs/locations_query_resource General API documentation for locations
+  # @since 1.0
+  class Location < Base
+    api_attr :city, :display_name, :lat, :lng, :state, :state_abbrev, :url, :url_name
+    api_attr :category => Category
+    api_attr :uuid => SimpleUUID::UUID
+
+    # Returns the locations matching +name+. See the API docs for specifics regarding matching rules.
+    #
+    # @param [String] name the name to match
+    # @param [Hash<String, Object>] inputs the data inputs
+    # @return [Hash<Symbol, Object>] the query result
+    # @since 1.0
+    def self.named(name, inputs)
+      query_result(OutsideIn::Resource::LocationFinder.new("/locations/named/#{URI.escape(name)}").GET(inputs))
+    end
+
+    # Returns the location's display name and uuid.
+    #
+    # @return [String]
+    # @since 1.0
+    def to_s
+      "#{display_name} (#{uuid.to_guid})"
+    end
+
+    # Returns a hash encapsulating the data returned from a successful finder query.
+    #
+    # The hash contains the following data:
+    #
+    # * +:total+ - the total number of matching locations (may be greater than the number of returned stories)
+    # * +:locations+ - the array of best matching {OutsideIn::Location} as per the specified or implied limit
+    #
+    # @param [Hash<String, Object>] data the raw query result
+    # @return [Hash<Symbol, Object>]
+    # @since 1.0
+    def self.query_result(data)
+      {:total => data['total'], :locations => data['locations'].map {|l| new(l)}}
+    end
+  end
+end

data/lib/outside_in/resource/base.rb

@@ -0,0 +1,91 @@
+require 'httparty'
+require 'json'
+require 'md5'
+
+module OutsideIn
+  module Resource
+    # The base class for API resources.
+    #
+    # Resources are exposed by the API service at particular endpoints identified by URLs. Consumers can interact
+    # with resources via the HTTP uniform interface.
+    #
+    # @example
+    #   resource = new MyResource("/an/endpoint")
+    #   data = resource.GET({'publication-id' => 1234, 'limit' => 5})
+    #
+    # @abstract Subclass and override {#scope} and {#params} to implement a custom resource class.
+    # @since 1.0
+    class Base
+      # Returns a version of +url+ that includes publication scoping when +inputs+ contains a non-nil
+      # +publication-id+ entry.
+      #
+      # @param [String] url the URL
+      # @param [Hash<String, Object>] inputs the data inputs
+      # @return [String] the potentially scoped URL
+      # @since 1.0
+      def self.scope(url, inputs)
+        raise NotImplementedError
+      end
+
+      # Returns a version of +url+ with parameters in the query string corresponding to +inputs+.
+      #
+      # @param [String] url the URL
+      # @param [Hash<String, Object>] inputs the data inputs
+      # @return [String] the URL including query parameters
+      # @since 1.0
+      def self.parameterize(url, inputs)
+        raise NotImplementedError
+      end
+
+      # Returns the signed form of +url+. Signing adds the +dev_key+ and +sig+ query parameters to the query string.
+      #
+      # @param [String] url a URL to be signed
+      # @return [String] the signed URL
+      # @raise [OutsideIn::SignatureException] if the key or secret are not set
+      # @since 1.0
+      def self.sign(url)
+        raise SignatureException, "Key not set" unless OutsideIn.key
+        raise SignatureException, "Secret not set" unless OutsideIn.secret
+        sig_params = "dev_key=#{OutsideIn.key}&sig=#{MD5.new(OutsideIn.key + OutsideIn.secret +
+          Time.now.to_i.to_s).hexdigest}"
+        url =~ /\?/ ? "#{url}&#{sig_params}" : "#{url}?#{sig_params}"
+      end
+
+      # Returns a new instance. Stores the absolutized, signed URL.
+      #
+      # @param [String] relative_url a URL relative to the version component of the base service URL
+      # @return [OutsideIn::Resource::Base]
+      def initialize(relative_url)
+        @url = "http://#{HOST}/v#{VERSION}#{relative_url}"
+      end
+
+      # Calls +GET+ on the remote API service and returns the data encapsulated in the response. The URL that is
+      # called is created by scoping and parameterizing the canonical resource URL based on +inputs+.
+      #
+      # @param [Hash<String, Object>] inputs the data inputs
+      # @return [Object] the returned data structure as defined by the API specification (as parsed from the JSON
+      #   envelope)
+      # @raise [OutsideIn::ForbiddenException] for a +403+ response
+      # @raise [OutsideIn::NotFoundException] for a +404+ response
+      # @raise [OutsideIn::ServiceException] for any error response that indicates a service fault of some type
+      # @raise [OutsideIn::QueryException] for any error response that indicates an invalid request or other client
+      #   problem
+      # @since 1.0
+      def GET(inputs)
+        url = self.class.sign(self.class.parameterize(self.class.scope(@url, inputs), inputs))
+        OutsideIn.logger.debug("Requesting #{url}") if OutsideIn.logger
+        response = HTTParty.get(url)
+        unless response.code < 300
+          raise ForbiddenException if response.code == 403
+          raise NotFoundException if response.code == 404
+          if response.headers.include?('x-mashery-error-code')
+            raise ServiceException, response.headers['x-mashery-error-code']
+          else
+            raise QueryException.new(JSON[response.body])
+          end
+        end
+        JSON[response.body]
+      end
+    end
+  end
+end

data/lib/outside_in/resource/location_finder.rb

@@ -0,0 +1,29 @@
+module OutsideIn
+  module Resource
+    # A resource that performs queries for locations.
+    #
+    # @since 1.0
+    class LocationFinder < OutsideIn::Resource::Base
+      QP = QueryParams.new({:limit => :limit}, {:category => :category})
+
+      # Returns a version of +url+ that includes publication scoping when +inputs+ contains a non-nil
+      # +publication-id+ entry.
+      #
+      # @param (see Resource#scope)
+      # @return [String] the potentially scoped URL
+      # @since 1.0
+      def self.scope(url, inputs)
+        inputs['publication-id'].nil?? url : "#{url}/publications/#{inputs['publication-id']}"
+      end
+
+      # Returns a version of +url+ with parameters in the query string corresponding to +inputs+.
+      #
+      # @param (see Resource#scope)
+      # @return [String] the URL including query parameters
+      # @since 1.0
+      def self.parameterize(url, inputs)
+        QP.parameterize(url, inputs)
+      end
+    end
+  end
+end

data/lib/outside_in/resource/query_params.rb

@@ -0,0 +1,60 @@
+module OutsideIn
+  module Resource
+    # A helper class for computing query parameters. These helpers know how to convert input values into query
+    # parameters and to add them to query URLs.
+    #
+    # @since 1.0
+    class QueryParams
+
+      # Creates and returns an instance based on various parameter names.
+      #
+      # For each simple parameter name, a parameter with that name is added when the inputs hash contains a value for
+      # that key.
+      #
+      # Negatable parameters are those which have "include" and "exclude" variants (e.g. category for locations,
+      # keyword for stories). An "include" parameter is added when the inputs hash contains a value for the negatable
+      # parameter's name, just like for a simple parameter. An exclude parameter prefixed with "no-" is added when the
+      # inputs hash contains a value for the parameter's name prefixed with "no-" or the name prefixed with "wo-" (the
+      # form used by the Thor tasks, which reserve the "no-" prefix for a different purpose).
+      #
+      # @param [Hash<Symbol, Symbol>] simple the names of simple input parameters mapped to API parameter names
+      # @param [Hash<Symbol, Symbol>] negatable the names of negatable input parameters mapped to API parameter names
+      # @return [OutsideIn::QueryParams]
+      # @since 1.0
+      def initialize(simple = {}, negatable = {})
+        @simple = simple
+        @negatable = negatable
+      end
+
+      # Returns the provided URL with parameters attached to the query string.
+      #
+      # @param [Hash<String, Object>] inputs the query parameter inputs
+      # @param [String] url the base query resource URL
+      # @return [String] the URL including query parameters
+      # @since 1.0
+      def parameterize(url, inputs)
+        params = []
+
+        @simple.each_pair do |input, api|
+          nk = input.to_s
+          params << "#{api}=#{inputs[nk]}" unless inputs[nk].nil?
+        end
+
+        @negatable.each_pair do |input, api|
+          nk = input.to_s
+          params.concat(inputs[nk].map {|s| "#{api}=#{URI.escape(s)}"}) unless inputs[nk].nil?
+          ["wo-#{input}", "no-#{input}"].each do |nk|
+            params.concat(inputs[nk].map {|s| "no-#{api}=#{URI.escape(s)}"}) unless inputs[nk].nil?
+          end
+        end
+
+        if params.empty?
+          url
+        else
+          sep = url =~ /\?/ ? '&' : '?'
+          "#{url}#{sep}#{params.join('&')}"
+        end
+      end
+    end
+  end
+end

data/lib/outside_in/resource/story_finder.rb

@@ -0,0 +1,31 @@
+module OutsideIn
+  module Resource
+    # A resource that performs queries for stories.
+    #
+    # @since 1.0
+    class StoryFinder < OutsideIn::Resource::Base
+      QP = QueryParams.new({:limit => :limit, :'max-age' => :max_age}, {:keyword => :keyword, :vertical => :vertical,
+        :format => :format, :'author-type' => :'author-type'})
+
+      # Returns a version of +url+ that includes publication scoping when +inputs+ contains a non-nil
+      # +publication-id+ entry.
+      #
+      # @param (see Resource#scope)
+      # @return [String] the potentially scoped URL
+      # @since 1.0
+      def self.scope(url, inputs)
+        inputs['publication-id'].nil?? url : url.gsub(/\/stories$/,
+          "/publications/#{inputs['publication-id']}/stories")
+      end
+
+      # Returns a version of +url+ with parameters in the query string corresponding to +inputs+.
+      #
+      # @param (see Resource#scope)
+      # @return [String] the URL including query parameters
+      # @since 1.0
+      def self.parameterize(url, inputs)
+        QP.parameterize(url, inputs)
+      end
+    end
+  end
+end

data/lib/outside_in/story.rb

@@ -1,34 +1,116 @@
+require 'simple_uuid'
+
 module OutsideIn
-  class Story
-    attr_reader :item_id, :icon_path, :author, :author_url, :published_at, :title, :body, :url, :tags, :places
-
-    def initialize(story_hash)
-      @item_id = story_hash['item_id']
-      @icon_path = story_hash['icon_path']
-      @author = story_hash['author']
-      @author_url = story_hash['author_url']
-      @published_at = story_hash['published_at']
-      @title = story_hash['title']
-      @body = story_hash['body']
-      @url = story_hash['url']
-      @tags = []
-      @places = []
-      populate_tags(story_hash)
-      populate_places(story_hash)
+  # Story model class.
+  #
+  # Stories have the following attributes:
+  #
+  # * feed_title
+  # * feed_url
+  # * story_url
+  # * summary
+  # * tags - (+Array+ of {OutsideIn::Tag})
+  # * title
+  # * uuid ({SimpleUUID::UUID})
+  #
+  # Story finders accept query parameter inputs as described by {OutsideIn::Story#parameterize_url}. They return data
+  # structures as described by {OutsideIn::Story#query_result}.
+  #
+  # @see http://developers.outside.in/docs/stories_query_resource General API documentation for stories
+  # @since 1.0
+  class Story < Base
+    api_attr :feed_title, :feed_url, :story_url, :summary, :title, :uuid
+    api_attr :tags => Tag
+
+    # Returns the stories attached to +state+.
+    #
+    # @param [String] state the state name or postal abbreviation
+    # @param [Hash<String, Object>] inputs the query parameter inputs
+    # @return [Hash<Symbol, Object>] the query result
+    # @since 1.0
+    def self.for_state(state, inputs = {})
+      url = "/states/#{URI.escape(state)}/stories"
+      query_result(OutsideIn::Resource::StoryFinder.new(url).GET(inputs))
     end
 
-    private
-    def populate_tags(story_hash)
-      story_hash["tags"].each do |tag|
-        @tags << OutsideIn::Tag.new(tag)
-      end
+    # Returns the stories attached to +city+ in +state+.
+    #
+    # @param [String] state the state name or postal abbreviation
+    # @param [String] city the city name
+    # @param [Hash<String, Object>] inputs the query parameter inputs
+    # @return [Hash<Symbol, Object>] the query result
+    # @since 1.0
+    def self.for_city(state, city, inputs = {})
+      url = "/states/#{URI.escape(state)}/cities/#{URI.escape(city)}/stories"
+      query_result(OutsideIn::Resource::StoryFinder.new(url).GET(inputs))
+    end
+
+    # Returns the stories attached to +nabe+ in +city+ in +state+.
+    #
+    # @param [String] state the state name or postal abbreviation
+    # @param [String] city the city name
+    # @param [String] nabe the neighborhood name
+    # @param [Hash<String, Object>] inputs the query parameter inputs
+    # @return [Hash<Symbol, Object>] the query result
+    # @since 1.0
+    def self.for_nabe(state, city, nabe, inputs = {})
+      url = "/states/#{URI.escape(state)}/cities/#{URI.escape(city)}/nabes/#{URI.escape(nabe)}/stories"
+      query_result(OutsideIn::Resource::StoryFinder.new(url).GET(inputs))
+    end
+
+    # Returns the stories attached to +zip+.
+    #
+    # @param [String] zip the zip code
+    # @param [Hash<String, Object>] inputs the query parameter inputs
+    # @return [Hash<Symbol, Object>] the query result
+    # @since 1.0
+    def self.for_zip_code(zip, inputs = {})
+      url = "/zipcodes/#{URI.escape(zip)}/stories"
+      query_result(OutsideIn::Resource::StoryFinder.new(url).GET(inputs))
+    end
+
+    # Returns the stories attached to the locations identified by +uuids+.
+    #
+    # @param [Array<SimpleUUID::UUID>] uuids the location uuids
+    # @param [Hash<String, Object>] inputs the query parameter inputs
+    # @return [Hash<Symbol, Object>] the query result
+    # @since 1.0
+    def self.for_uuids(uuids, inputs = {})
+      url = "/locations/#{uuids.map{|u| URI.escape(u.to_guid)}.join(",")}/stories"
+      query_result(OutsideIn::Resource::StoryFinder.new(url).GET(inputs))
     end
-    
-    def populate_places(story_hash)
-      story_hash["places"].each do |place|
-        @places << OutsideIn::Place.new(place)
+
+    # Returns the story's title and uuid.
+    #
+    # @return [String]
+    # @since 1.0
+    def to_s
+      "#{title} (#{uuid.to_guid})"
+    end
+
+    # Returns a hash encapsulating the data returned from a successful finder query.
+    #
+    # The hash contains the following data:
+    #
+    # * +:total+ - the total number of matching stories (may be greater than the number of returned stories)
+    # * +:stories+ - the array of most recent matching {OutsideIn::Story} in reverse chronological order as per the
+    #   specified or implied limit
+    # * +:location+ - the {OutsideIn::Location} to which the finder was scoped (present for all non-UUID finders)
+    # * +:locations+ - the array of {OutsideIn::Location} to which the finder was scoped (present only for the UUID
+    #    finder)
+    #
+    # @param [Hash<String, Object>] data the raw query result
+    # @return [Hash<Symbol, Object>]
+    # @since 1.0
+    def self.query_result(data)
+      rv = {:total => data['total'], :stories => []}
+      if data.include?('locations')
+        rv[:locations] = data['locations'].map {|l| Location.new(l)}
+      else
+        rv[:location] = Location.new(data['location'])
       end
+      rv[:stories] = data['stories'].map {|s| new(s)}
+      rv
     end
-    
   end
 end

data/lib/outside_in/tag.rb

@@ -1,10 +1,21 @@
 module OutsideIn
-  class Tag
-    attr_reader :name, :url
+  # Topic tag model class. Tags are attached to stories to provide hints for content and relevance. Keyword queries
+  # match against tags as well as story title and summary.
+  #
+  # Tags have the following attributes:
+  #
+  # * name
+  #
+  # @since 1.0
+  class Tag < Base
+    api_attr :name
 
-    def initialize(tag_hash)
-      @name = tag_hash['name']
-      @url = tag_hash['url']
+    # Returns the tag's name.
+    #
+    # @return [String]
+    # @since 1.0
+    def to_s
+      name
     end
   end
 end

data/lib/outside_in.rb

@@ -1,19 +1,82 @@
-require 'rubygems'
-require 'json'
-require 'net/http'
+require 'active_support/core_ext/module/attribute_accessors'
+require 'logger'
+
+require 'outside_in/base'
+require 'outside_in/category'
+require 'outside_in/tag'
+require 'outside_in/location'
+require 'outside_in/story'
+require 'outside_in/resource/query_params'
+require 'outside_in/resource/base'
+require 'outside_in/resource/location_finder'
+require 'outside_in/resource/story_finder'
 
 module OutsideIn
-  
-  ENDPOINT = "http://api.outside.in/radar"
-  JSON_ENDPOINT = "#{ENDPOINT}.json"
+  # The API service host
+  # @since 1.0
+  HOST = 'hyperlocal-api.outside.in'
 
-end
+  # The current version of the API (not the version of the SDK!)
+  # @since 1.0
+  VERSION = '1.1'
+
+  mattr_accessor :logger, :instance_writer => false
+  # That which logs. Use +OutsideIn.logger+ and +OutsideIn.logger=+ to access. Defaults to +WARN+.
+  # @since 1.0
+  @@logger = Logger.new(STDOUT)
+  @@logger.level = Logger::WARN
+
+  mattr_accessor :key, :instance_writer => false
+  # The developer key used to identify who is making the API request. Use +OutsideIn.key+ and +OutsideIn.key=+ to
+  # access.
+  # @since 1.0
+  @@key = nil
+
+  mattr_accessor :secret, :instance_writer => false
+  # The shared secret used to sign the API request. Use +OutsideIn.secret+ and +OutsideIn.secret=+ to access.
+  # @since 1.0
+  @@secret = nil
 
-directory = File.expand_path(File.dirname(__FILE__))
+  # The base class for API exceptions.
+  # @since 1.0
+  class ApiException < Exception; end
 
-require File.join(directory, 'outside_in', 'radar')
-require File.join(directory, 'outside_in', 'tweet')
-require File.join(directory, 'outside_in', 'place')
-require File.join(directory, 'outside_in', 'tag')
-require File.join(directory, 'outside_in', 'story')
+  # Indicates that access was denied to the requested API resource. This may mean that the developer key is invalid
+  # or does not provide access to a curated resource.
+  # @since 1.0
+  class ForbiddenException < ApiException; end
 
+  # Indicates that the requested API resource was not found. Usually this means that a data item was not found for
+  # a given UUID or other identifier, but in the case of an SDK bug, it may mean the requested URL was incorrect
+  # somehow.
+  # @since 1.0
+  class NotFoundException < ApiException; end
+
+  # Usually means that something has gone wrong on the service side of the communication.
+  # @since 1.0
+  class ServiceException < ApiException; end
+
+  # Indicates that a request could not be signed for some reason.
+  # @since 1.0
+  class SignatureException < ApiException; end
+
+  # Indicates that a query request returned an error response.
+  # @since 1.0
+  class QueryException < Exception
+
+    # Returns a new instance.
+    #
+    # @param [Hash<String, Object>] data the error hash returned in the query response body
+    # @return [OutsideIn::QueryException]
+    # @since 1.0
+    def initialize(data)
+      if data.include?('error')
+        super(data['error'])
+      elsif data.include?('errors')
+        super(data['errors'].join('; '))
+      else
+        super('unknown query error')
+      end
+    end
+  end
+end

data/outside-in.gemspec

@@ -5,36 +5,42 @@
 
 Gem::Specification.new do |s|
   s.name = %q{outside-in}
-  s.version = "0.1.0"
+  s.version = "1.0.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
-  s.authors = ["Doug Petkanics"]
-  s.date = %q{2010-06-23}
-  s.description = %q{The Outside.IN Radar API provides hyperlocal news, tweets, and commentary based around a given latitude and longitude. This is a ruby wrapper around that API.}
-  s.email = %q{petkanics@gmail.com}
+  s.authors = ["Brian Moseley"]
+  s.date = %q{2010-09-20}
+  s.email = %q{brian@outside.in}
   s.extra_rdoc_files = [
-    "LICENSE",
-     "README"
+    "README.md"
   ]
   s.files = [
     ".gitignore",
-     "LICENSE",
-     "README",
+     "Gemfile",
+     "Gemfile.lock",
+     "HISTORY",
+     "README.md",
      "Rakefile",
      "VERSION",
+     "config/oi.sample.yml",
      "lib/outside_in.rb",
-     "lib/outside_in/place.rb",
-     "lib/outside_in/radar.rb",
+     "lib/outside_in/base.rb",
+     "lib/outside_in/category.rb",
+     "lib/outside_in/location.rb",
+     "lib/outside_in/resource/base.rb",
+     "lib/outside_in/resource/location_finder.rb",
+     "lib/outside_in/resource/query_params.rb",
+     "lib/outside_in/resource/story_finder.rb",
      "lib/outside_in/story.rb",
      "lib/outside_in/tag.rb",
-     "lib/outside_in/tweet.rb",
-     "outside-in.gemspec"
+     "outside-in.gemspec",
+     "tasks/oi.thor"
   ]
-  s.homepage = %q{http://github.com/dob/outsidein}
+  s.homepage = %q{http://github.com/outsidein/api-rb}
   s.rdoc_options = ["--charset=UTF-8"]
   s.require_paths = ["lib"]
   s.rubygems_version = %q{1.3.6}
-  s.summary = %q{Ruby wrapper on the Outside.In API}
+  s.summary = %q{Ruby SDK for the Outside.in API}
 
   if s.respond_to? :specification_version then
     current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION

data/tasks/oi.thor

@@ -0,0 +1,173 @@
+require 'rubygems'
+require 'bundler'
+Bundler.setup
+
+# XXX: only do this when the task has not been installed
+$: << 'lib'
+
+require 'outside_in'
+require 'simple_uuid'
+require 'text/reform'
+require 'yaml'
+
+module OutsideIn
+  class CLI < Thor
+    namespace :oi
+
+  protected
+    def run(&block)
+      configure
+      if ::OutsideIn.key && ::OutsideIn.secret
+        begin
+          yield
+        rescue ::OutsideIn::ForbiddenException => e
+          error("Access denied - doublecheck key and secret in #{cfg_file}")
+        rescue ::OutsideIn::QueryException => e
+          error("Invalid query: #{e.message}")
+        rescue ::OutsideIn::ApiException => e
+          error("API error: #{e.message}")
+        end
+      end
+    end
+
+    def cfg_file
+      File.join('config', 'oi.yml')
+    end
+
+    def configure
+      cfg = YAML.load_file(cfg_file)
+      ::OutsideIn.key = cfg['key'] or error("You must specify your key in #{cfg_file}")
+      ::OutsideIn.secret = cfg['secret'] or error("You must specify your secret in #{cfg_file}")
+      ::OutsideIn.logger.level = Logger::DEBUG
+    end
+
+    def warn(msg)
+      say_status :WARN, msg, :yellow
+    end
+
+    def ok(msg)
+      say_status :OK, msg
+    end
+
+    def error(msg)
+      say_status :ERROR, msg, :red
+    end
+
+    def debug(msg)
+      say_status :DEBUG, msg, :cyan
+    end
+
+    def show_locations(data)
+      if data[:locations].empty?
+        warn("No matching locations found.")
+      else
+        names = data[:locations].map do |l|
+          l.display_name.length > 32 ? "#{l.display_name[0, 27]} ..." : l.display_name
+        end
+        uuids = data[:locations].map {|l| l.uuid.to_guid}
+        r = Text::Reform.new
+        say(r.format(
+          "",
+          "Name                              UUID",
+          "======================================================================",
+          "[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[  [[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[",
+          names, uuids,
+          "",
+          "Best #{data[:locations].size} of #{data[:total]} matching locations"
+        ))
+      end
+    end
+
+    def show_stories(data)
+      if data[:stories].empty?
+        warn("No stories found.")
+      else
+        titles = data[:stories].map {|s| s.title.length > 48 ? "#{s.title[0, 43]} ..." : s.title}
+        feeds = data[:stories].map {|s| s.feed_title.length > 26 ? "#{s.feed_title[0, 21]} ..." : s.feed_title}
+        r = Text::Reform.new
+        say(r.format(
+          "",
+          "Title                                             Feed",
+          "============================================================================",
+          "[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[  [[[[[[[[[[[[[[[[[[[[[[[[[[",
+          titles, feeds,
+          "",
+          "#{data[:stories].size} most recent of #{data[:total]} stories"
+        ))
+      end
+    end
+  end
+
+  class Locations < CLI
+    namespace 'oi:locations'
+
+    desc 'named NAME', 'Find locations matching a name'
+    method_options :limit => :numeric, :category => :array, :'wo-category' => :array, :'publication-id' => :numeric
+    def named(name)
+      run do
+        show_locations(::OutsideIn::Location.named(name, options))
+      end
+    end
+  end
+
+  class Stories < CLI
+    namespace 'oi:stories'
+
+    def self.param_method_options
+      method_options :limit => :numeric, :'max-age' => :string, :keyword => :array, :'wo-keyword' => :array,
+        :vertical => :array, :'wo-vertical' => :array, :format => :array, :'wo-format' => :array,
+        :'author-type' => :array, :'wo-author-type' => :array, :'publication-id' => :numeric
+    end
+
+    desc 'state STATE', 'Find stories for a state'
+    param_method_options
+    def state(state)
+      run do
+        show_stories(::OutsideIn::Story.for_state(state, options))
+      end
+    rescue ::OutsideIn::NotFoundException => e
+      error("State not found")
+    end
+
+    desc 'city STATE CITY', 'Find stories for a city'
+    param_method_options
+    def city(state, city)
+      run do
+        show_stories(::OutsideIn::Story.for_city(state, city, options))
+      end
+    rescue ::OutsideIn::NotFoundException => e
+      error("City not found")
+    end
+
+    desc 'nabe STATE CITY NABE', 'Find stories for a neighborhood'
+    param_method_options
+    def nabe(state, city, nabe)
+      run do
+        show_stories(::OutsideIn::Story.for_nabe(state, city, nabe, options))
+      end
+    rescue ::OutsideIn::NotFoundException => e
+      error("Neighborhood not found")
+    end
+
+    desc 'zip ZIP', 'Find stories for a zip code'
+    param_method_options
+    def zip(zip)
+      run do
+        show_stories(::OutsideIn::Story.for_zip_code(zip, options))
+      end
+    rescue ::OutsideIn::NotFoundException => e
+      error("Zip code not found")
+    end
+
+    desc 'uuid UUID[,UUID[...]]', 'Find stories for one to five location UUIDs'
+    param_method_options
+    def uuid(uuids)
+      run do
+        show_stories(::OutsideIn::Story.for_uuids(uuids.split(',').map {|s| SimpleUUID::UUID.new(s)}, options))
+      end
+    rescue ::OutsideIn::NotFoundException => e
+      error("UUID not found")
+    end
+
+  end
+end

metadata

@@ -3,45 +3,52 @@ name: outside-in
 version: !ruby/object:Gem::Version 
   prerelease: false
   segments: 
-  - 0
   - 1
   - 0
-  version: 0.1.0
+  - 0
+  version: 1.0.0
 platform: ruby
 authors: 
-- Doug Petkanics
+- Brian Moseley
 autorequire: 
 bindir: bin
 cert_chain: []
 
-date: 2010-06-23 00:00:00 -04:00
+date: 2010-09-20 00:00:00 -04:00
 default_executable: 
 dependencies: []
 
-description: The Outside.IN Radar API provides hyperlocal news, tweets, and commentary based around a given latitude and longitude. This is a ruby wrapper around that API.
-email: petkanics@gmail.com
+description: 
+email: brian@outside.in
 executables: []
 
 extensions: []
 
 extra_rdoc_files: 
-- LICENSE
-- README
+- README.md
 files: 
 - .gitignore
-- LICENSE
-- README
+- Gemfile
+- Gemfile.lock
+- HISTORY
+- README.md
 - Rakefile
 - VERSION
+- config/oi.sample.yml
 - lib/outside_in.rb
-- lib/outside_in/place.rb
-- lib/outside_in/radar.rb
+- lib/outside_in/base.rb
+- lib/outside_in/category.rb
+- lib/outside_in/location.rb
+- lib/outside_in/resource/base.rb
+- lib/outside_in/resource/location_finder.rb
+- lib/outside_in/resource/query_params.rb
+- lib/outside_in/resource/story_finder.rb
 - lib/outside_in/story.rb
 - lib/outside_in/tag.rb
-- lib/outside_in/tweet.rb
 - outside-in.gemspec
+- tasks/oi.thor
 has_rdoc: true
-homepage: http://github.com/dob/outsidein
+homepage: http://github.com/outsidein/api-rb
 licenses: []
 
 post_install_message: 
@@ -69,6 +76,6 @@ rubyforge_project:
 rubygems_version: 1.3.6
 signing_key: 
 specification_version: 3
-summary: Ruby wrapper on the Outside.In API
+summary: Ruby SDK for the Outside.in API
 test_files: []
 

data/LICENSE

@@ -1,21 +0,0 @@
-The MIT License
-
-Copyright (c) 2010 Doug Petkanics
-
-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

@@ -1,9 +0,0 @@
-Wrapper for the Outside.in API
-
-Usage:
-require 'outside_in'
-
-radars = OutsideIn::Radar.new(lat, lng)
-radars.stories.each do |story|
-  puts "#{story.title} by #{story.author}"
-end

data/lib/outside_in/place.rb

@@ -1,21 +0,0 @@
-module OutsideIn
-
-  class Point
-    attr_reader :lat, :lng
-    
-    def initialize(point_string)
-      @lat, @lng = point_string.split(' ')
-    end
-  end
-  
-  class Place
-    attr_reader :id, :name, :url, :point
-
-    def initialize(place_hash)
-      @id = place_hash['id']
-      @name = place_hash['name']
-      @url = place_hash['url']
-      @point = Point.new(place_hash['georss:point'])
-    end
-  end
-end

data/lib/outside_in/radar.rb

@@ -1,48 +0,0 @@
-module OutsideIn
-  
-  class Radar
-    attr_accessor :stories, :tweets
-
-    def initialize(lat, lng, radius=nil, only=nil, except=nil)
-      @lat = lat
-      @lng = lng
-      @radius = radius
-      @only = only
-      @except = except
-      @stories = []
-      @tweets = []
-      hit_api
-    end
-
-    def hit_api
-      res = JSON.parse(request)
-      populate_stories_and_tweets(res)
-    end
-
-    def populate_stories_and_tweets(radars)
-      radars.each do |radar|
-        if radar["type"] == "Story"
-          @stories << OutsideIn::Story.new(radar)
-        elsif radar["type"] == "Tweet"
-          @tweets << OutsideIn::Tweet.new(radar)
-        end
-      end
-    end
-
-    def construct_url
-      url = "#{OutsideIn::JSON_ENDPOINT}?lat=#{@lat}&lng=#{@lng}"
-      url += "&radius=#{@radius}" if @radius
-      url += "&only=#{@only}" if @only
-      url += "&except=#{@except}" if @except
-      url
-    end
-    
-    def request
-      url = URI.parse(construct_url)
-      res = Net::HTTP.get(url)
-    end
-    
-  end
-  
-end
-

data/lib/outside_in/tweet.rb

@@ -1,26 +0,0 @@
-module OutsideIn
-  class Tweet
-    attr_reader :item_id, :icon_path, :author, :author_url, :published_at, :body, :url, :image_url, :places
-
-    def initialize(tweet_hash)
-      @item_id = tweet_hash['item_id']
-      @icon_path = tweet_hash['icon_path']
-      @author = tweet_hash['author']
-      @author_url = tweet_hash['author_url']
-      @published_at = tweet_hash['published_at']
-      @body = tweet_hash['body']
-      @url = tweet_hash['url']
-      @image_url = tweet_hash['image_url']
-      @places = []
-      populate_places(tweet_hash)
-    end
-
-    private
-    def populate_places(tweet_hash)
-      tweet_hash["places"].each do |place|
-        @places << OutsideIn::Place.new(place)
-      end
-    end
-    
-  end
-end