singleplatform 0.1.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2cec3922463afab967e8fd8cb232e18b38b03a5b
-  data.tar.gz: 4246d0e5f2c24643433faa462f324be89772c144
+  metadata.gz: c145adab5f968aa717643063bfad1482d70ed11e
+  data.tar.gz: d5311c4cb78d5363440580d00dde210609b578bb
 SHA512:
-  metadata.gz: 28a77401efa0875e85a135be5f7742f90df1a873fe2774028af577a3e658eaae98c017998f358521aaed54351b37f9a4047579a5cb8bb8e08016bf425f557cde
-  data.tar.gz: 8a331be44e7e42b30068d08bddac1c004e71dce901a5d2b3f8ce3b878258cd2c13115ad7efb990665f7a094226d79ea102bddc3712fe4042a15d53b95a72be91
+  metadata.gz: 2717d6cb948eb3732df5f9f1fed81598f83a12019d2d065f60cb8fed4a9293410b617032bab46e4c24f621c6f88aab3ce7f4b5afd99607783fe55d95335b0137
+  data.tar.gz: 919cfa303a3406c364ad532a646012114bb609b1333927502097814a4d9b54b5ae5131dffc7317e400645bcac61cf36ccfd5fc2674e2dab690732ad379543655

data/.gitignore

@@ -1,3 +1,4 @@
 .DS_Store
 .env
-singleplatform-0.1.0.gem
+singleplatform-0.1.0.gem
+singleplatform-0.1.1.gem

data/Gemfile

@@ -2,4 +2,6 @@ source 'https://rubygems.org'
 
 gem 'bundler'
 gem 'httparty'
-gem 'hashie'
+gem 'hashie'
+gem 'rspec'
+gem 'webmock'

data/Gemfile.lock

@@ -1,23 +1,38 @@
 GEM
   remote: https://rubygems.org/
   specs:
-    dotenv (2.1.1)
+    addressable (2.4.0)
+    crack (0.4.3)
+      safe_yaml (~> 1.0.0)
+    diff-lcs (1.2.5)
+    hashdiff (0.3.0)
     hashie (3.4.3)
     httparty (0.14.0)
       multi_xml (>= 0.5.2)
     multi_xml (0.5.5)
+    rspec (2.99.0)
+      rspec-core (~> 2.99.0)
+      rspec-expectations (~> 2.99.0)
+      rspec-mocks (~> 2.99.0)
+    rspec-core (2.99.2)
+    rspec-expectations (2.99.2)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.99.4)
+    safe_yaml (1.0.4)
+    webmock (2.1.0)
+      addressable (>= 2.3.6)
+      crack (>= 0.3.2)
+      hashdiff
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
   bundler
-  dotenv
   hashie
   httparty
-
-RUBY VERSION
-   ruby 2.2.2p95
+  rspec
+  webmock
 
 BUNDLED WITH
    1.12.5

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2016 Jeff Gharakhanian
+
+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

@@ -42,13 +42,13 @@ With an initialized client, you can request information on locations in SinglePl
 client.location('nobu')
 ```
 
-This will return a Hashie::Mash pseudo object, which allows you to access attributes on the response using dot notation. Nested attributes continue to return Hashie::Mash objects until there are no children.
+This will return a ```Singleplatform::Response``` object. Access the response body or code with ```.body``` and ```.code``` respectively. Calling ```.body``` returns a ```Hashie::Mash``` pseudo object which allows you to access all location attributes with dot notation.
 
 ```ruby
-location = client.location('nobu') # => #<Hashie::Mash ... >
-location.name                      # => "Nobu"
-location.attributes                # => #<Hashie::Mash ... >
-location.attributes.drive_thru     # => false
+response = client.location('nobu')   # => #<Singleplatform::Response ... >
+response.body.name                   # => "Nobu"
+response.body.attributes             # => #<Hashie::Mash ... >
+response.body.attributes.drive_thru  # => false
 ```
 
 See SinglePlatform's API documentation for a full list of attributes.
@@ -58,27 +58,42 @@ See SinglePlatform's API documentation for a full list of attributes.
 You can retrieve locations en masse by calling:
 
 ```ruby
-client.locations_updated_since('2016-08-01', limit: 100)
+response = client.locations_updated_since('2016-08-01', limit: 100)
 ```
 
-Results are paginated. The maximum (and default) limit per page is 5000.
+Results are paginated. The maximum (and default) limit per page is 5000. To access the next page of results, call:
+
+```ruby
+response.next
+```
 
 ### Menus
-SinglePlatform locations have menus or lists of products and services that you can access with a configured API client. The following call returns an Array of Hashie::Mash objects.
+SinglePlatform locations have menus or lists of products and services that you can access with a configured API client. The following call returns a ```Singleplatform::Response``` object whose body contains an Array of ```Hashie::Mash``` objects.
 
 ```ruby
-menus = client.menus_for('nobu') # => #<Array ... >
-menus.first.name                 # => "Dinner Menu"
+response = client.menus_for('nobu') # => #<Array ... >
+response.body.first.name            # => "Dinner Menu"
 ```
 
 See SinglePlatform's API documentation for the Menu schema with a full list of attributes.
 
 ### Photos
-Many SinglePlatform locations have photos, both at the business and menu-item level. Returns an Array of Hashie::Mash objects.
+
+#### Fetching photos for a particular location
+
+Many SinglePlatform locations have photos, both at the business and menu-item level. Returns a ```Singleplatform::Response``` object whose body is an Array of menus.
 
 ```ruby
-photos = client.photos_for('no') # => #<Array ... >
-photos.first.type                # => "Product"
-photos.first.url                 # => "http://xyz.cloudfront.net/.../39bf7671bc7d006f4cef72d94eee24aeec7615d2.jpg"
+response = client.photos_for('no')  # => #<Singleplatform::Response ... >
+response.body.first.type            # => "Product"
+response.body.first.url             # => "http://xyz.cloudfront.net/.../39bf7671bc7d006f4cef72d94eee24aeec7615d2.jpg"
 ```
 
+#### Fetching all photos updated since a given date
+
+Similarly to ```locations_updated_since```, calling ```photos_updated_since``` returns a set of paginated results. Get the next page of results by calling ```next``` on the ```Singleplatform:::Response``` object.
+
+````ruby
+response = client.photos_updated_since('2016-09-01')  # => #<Singleplatform::Response ... >
+response
+````

data/Rakefile

@@ -1,9 +0,0 @@
-require 'rake/testtask'
-
-Rake::TestTask.new do |t|
-  t.libs << ['test']
-  t.pattern = 'test/**/test_*.rb'
-end
-
-desc "Run tests"
-task :default => :test

data/lib/singleplatform.rb

@@ -1,15 +1,12 @@
 require 'singleplatform/client'
 
 module Singleplatform
-
   class << self
-
     # Alias for Singleplatform::Client.new
     #
     # @return [Singleplatform::Client]
     def new(args = {})
       Singleplatform::Client.new(args)
     end
-
   end
 end

data/lib/singleplatform/client.rb

@@ -1,4 +1,6 @@
-require 'singleplatform/client/request'
+require 'singleplatform/request'
+require 'singleplatform/response'
+require 'singleplatform/error'
 require 'singleplatform/client/locations'
 require 'singleplatform/client/menus'
 require 'singleplatform/client/photos'
@@ -9,9 +11,7 @@ module Singleplatform
   class Client
     attr_accessor :base_url, :client_id, :client_secret
 
-    BASE_URL      = 'http://publishing-api.singleplatform.com'
-    CLIENT_ID     = ENV['CLIENT_ID'].freeze
-    CLIENT_SECRET = ENV['CLIENT_SECRET'].freeze
+    BASE_URL = 'http://publishing-api.singleplatform.com'
 
     include Singleplatform::Client::Locations
     include Singleplatform::Client::Menus
@@ -24,6 +24,7 @@ module Singleplatform
       @base_url      = BASE_URL
       @client_id     = args[:client_id]
       @client_secret = args[:client_secret]
+      raise Error::MissingCredentialsError if credentials_missing?
     end
 
     # Form the complete URL for a given endpoint
@@ -34,7 +35,7 @@ module Singleplatform
     # @param params [Hash]
     # @return [String]
     def generate_url(path, params = {})
-      params['client'] = client_id
+      params['client'] ||= client_id
       signature_base_string = "#{path}?#{URI.encode_www_form(params)}"
       "#{base_url}#{signature_base_string}&signature=#{generate_signature(signature_base_string)}"
     end
@@ -47,5 +48,33 @@ module Singleplatform
       key = OpenSSL::HMAC.digest('sha1', client_secret, base_string)
       CGI::escape(Base64.encode64(key).chomp)
     end
+
+    # Helper method to determine if credentials are missing and, if
+    #   so, raise Error::MissingCredentials
+    #
+    # @return [Boolean]
+    def credentials_missing?
+      client_id.nil? || client_secret.nil?
+    end
+
+    # Helper method to determine if any number of params are nil,
+    #   empty or just spaces.
+    #
+    # @return [Boolean]
+    def valid_params?(*args)
+      args.map { |a| return false if a.nil? || a.to_s.gsub(/\s/, '').empty? }
+      true
+    end
+
+    # Helper method to determine if a date is valid
+    #
+    # @return [Boolean]
+    def valid_date?(date)
+      d = date.split('-')
+      d.map! { |d| d.to_i }
+      Date.valid_date?(d[0], d[1], d[2])
+    rescue TypeError
+      return false
+    end
   end
 end

data/lib/singleplatform/client/locations.rb

@@ -4,11 +4,20 @@ module Singleplatform
       # Fetch information about a specific location
       #
       # @param id [String]
-      # @param options [Hash]
-      # @option options [String] :format Short menu ('short') available
-      # @return [Hashie::Mash]
-      def location(id, options = {})
-        url = generate_url("/locations/#{id}/", options)
+      # @return [Singleplatform::Response]
+      def location(id)
+        raise Error::InvalidLocationError unless valid_params?(id)
+        url = generate_url("/locations/#{id}/")
+        Request.get(url)
+      end
+
+      # Fetch location, menus and photo data for a specific location
+      #
+      # @param id [String]
+      # @return [Singleplatform::Response]
+      def all_for(id)
+        raise Error::InvalidLocationError unless valid_params?(id)
+        url = generate_url("/locations/#{id}/all")
         Request.get(url)
       end
 
@@ -17,8 +26,9 @@ module Singleplatform
       # @param date [String]
       # @param options [Hash]
       # @option options [Fixnum] :limit Maximum (default) 5000 per page
-      # @return [Hashie::Mash]
+      # @return [Singleplatform::Response]
       def locations_updated_since(date, options = {})
+        raise Error::InvalidDateError unless valid_date?(date)
         url = generate_url(
           '/locations/updated_since/',
           { date: date }.merge(options)

data/lib/singleplatform/client/menus.rb

@@ -8,6 +8,7 @@ module Singleplatform
       # @option options [String] :format Short menu available ('short')
       # @return [Hashie::Mash]
       def menus_for(id, options = {})
+        raise Error::InvalidLocationError unless valid_params?(id)
         url = generate_url("/locations/#{id}/menus", options)
         Request.get(url)
       end    

data/lib/singleplatform/client/photos.rb

@@ -10,6 +10,7 @@ module Singleplatform
       # @option options [String] :type (interior, exterior, item, logo, uncategorized)
       # @return [Hashie::Mash]
       def photos_for(id, options = {})
+        raise Error::InvalidLocationError unless valid_params?(id)
         url = generate_url("/location/#{id}/photos", options)
         Request.get(url)
       end
@@ -17,9 +18,15 @@ module Singleplatform
       # Fetch photos added/updated since a given date
       #
       # @param date [String]
+      # @param options [Hash]
+      # @option options [Fixnum] :limit Maximum (default) 5000 per page
       # @return [Hashie::Mash]
-      def photos_updated_since(date)
-        url = generate_url('/photos/updated_since/', date: date)
+      def photos_updated_since(date, options = {})
+        raise Error::InvalidDateError unless valid_params?(date)
+        url = generate_url(
+          '/photos/updated_since/',
+          { date: date }.merge(options)
+        )
         Request.get(url)
       end
     end

data/lib/singleplatform/error.rb

@@ -0,0 +1,39 @@
+module Singleplatform
+  module Error
+    class Base < StandardError
+      def initialize(msg)
+        super(msg)
+      end
+    end
+
+    class MissingCredentialsError < Base
+      def initialize(msg = "You must initialize a client with ID and Secret.")
+        super
+      end
+    end
+
+    class ApiError < Base
+      def initialize(msg = "Oops! There was an error.")
+        super
+      end
+    end
+
+    class MissingParametersError < Base
+      def initialize(msg = "Your request is missing required parameters.")
+        super
+      end
+    end
+
+    class InvalidLocationError < Base
+      def initialize(msg = "Your request must supply a valid location.")
+        super
+      end
+    end
+
+    class InvalidDateError < Base
+      def initialize(msg = "Your request must supply a valid date.")
+        super
+      end
+    end
+  end
+end

data/lib/singleplatform/request.rb

@@ -0,0 +1,44 @@
+require 'httparty'
+require 'hashie'
+
+module Singleplatform
+  class Request
+    # Make an HTTP get request to given URL
+    #
+    # @param url [String]
+    # @return [Singleplatform::Response]
+    def self.get(url)
+      tries ||= 3
+      response = HTTParty.get(url)
+    rescue
+      sleep 3
+      if tries -= 1 > 0
+        retry
+      end
+      raise(
+        Error::RequestError,
+        "Unable to transmit request to SinglePlatform. Try again later or contact technical support."
+      )
+    else
+      raise(
+        Error::ApiError,
+        "#{response.code}: #{response['errorMessage']}"
+      ) if response.code != 200
+      Response.new(
+        code:   response.code,
+        body:   self.parse_response_body(response.body),
+        # Pass the calling method to the Response object so it knows which
+        # method to call when API results are iterable
+        origin: caller_locations(1,1)[0].label
+      )
+    end
+
+    # Transform API JSON response to Hashie::Mash pseudo object
+    #
+    # @return [Hashie::Mash]
+    def self.parse_response_body(body)
+      return body unless JSON.parse(body)
+      Hashie::Mash.new(JSON.parse(body)).data
+    end
+  end
+end

data/lib/singleplatform/response.rb

@@ -0,0 +1,65 @@
+require 'cgi'
+
+module Singleplatform
+  class Response
+    attr_accessor :code, :body, :next_page, :origin
+
+    def initialize(args)
+      @code      = args[:code]
+      @body      = args[:body]
+      @next_page = args[:body].respond_to?(:next) ? args[:body].next : nil
+      @origin    = args[:origin].to_s
+    end
+
+    # An iterator for retrieving the next page of results from
+    #   API response.
+    #
+    # @note Will only work with Client#locations_updated_since and
+    #   #photos_updated_since at this time.
+    #
+    # @return [Hashie::Mash]
+    def next
+      return nil if next_page.nil? || next_page.empty?
+      params = prepare_params(next_page)
+      client = Singleplatform.new(
+        client_id:     ENV['CLIENT_ID'],
+        client_secret: ENV['CLIENT_SECRET']
+      )
+      new_page = client.public_send(
+                                    origin.to_sym,
+                                    params.delete('date'), params
+                                    )
+      refresh(new_page)
+    end
+
+    private
+
+    # Update Response instance variables
+    #
+    # @param [Singleplatform::Response]
+    # @return [Singleplatform::Response]
+    def refresh(response)
+      @code      = response.code
+      @body      = response.body
+      @next_page = response.next_page
+      response
+    end
+
+    # Take any given URL and parse its query params.
+    #
+    # @param url [String]
+    # @return [Hash]
+    def parse_params(url)
+      CGI::parse(url.split('?')[-1])
+    end
+
+    # Include additional params required for accessing API
+    #
+    # @return [Hash]
+    def prepare_params(url)
+      params = parse_params(url)
+      params['client'] = ENV['CLIENT_ID']
+      params
+    end
+  end
+end