levelup 0.9.2 → 0.9.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fffe35cc46fcd692944cc88cceb1685b374cec2f
-  data.tar.gz: fc77b72ad732430eae0d59cc57149293d5139ff4
+  metadata.gz: 238e90b50ace8d0dda415d36dcd75b7d0af2023f
+  data.tar.gz: a6d9b1a494b008804eafece8a06e45a788c61dd3
 SHA512:
-  metadata.gz: 0ea9f4468368ea50a351f85538c6017cb959bf682ea53e64fa5763b18f0945d44907094caf073a4cbf28813f0029e8e177a83856820f57a92e0d01d079586f34
-  data.tar.gz: 76119e8ab76d59bfd30c9069b2886237bc7d83778dd8d469338efe078898bebf25d71c2ca1b80ae2c7f07cccd40d3c0cfb04084436b2081801e461b24010773d
+  metadata.gz: 32ccd34e752ccdd08d5e474a68522bc16259dd4d50341f6550bbdcedc68196a00854bdc2a40928d71b1316073ad637830f3215fd6688e39fab33da17579a3006
+  data.tar.gz: 4779600aa8094b8af4fca1a07d5580feffe665e5fa0b76f8b2a17c5821c36e78107de0219a31450bdf36654c7f34f1a07b2603d2c0bd3349291c8717044bcb34

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    levelup (0.9.2)
+    levelup (0.9.3)
       httparty (~> 0.13.1)
 
 GEM

data/README.md

@@ -73,8 +73,28 @@ response = api.orders.create(
   user_access_token: 'user-token')
 ```
 
-All other functions of the Ruby SDK mirror the v15 LevelUp API described at http://developer.thelevelup.com/
-as well as a very small number of v14 endpoints.
+The LevelUp Ruby SDK mirrors the API as closely as possible, so the call for any given endpoint can be inferred from its URL.
+For instance:
+```ruby
+api.apps.permissions_requests.create # points to /v15/apps/permissions_requests/ POST
+api.user_addresses.list              # points to /v15/user_addresses/ GET
+api.orders(uuid).refund              # points to /v15/orders/:uuid/refund/ POST
+```
+
+## Pagination
+
+Some requests that return large lists are paginated and only return a small number of values per request.
+The LevelUp Ruby SDK handles this by allowing you to request the next page from the paginated response.
+
+For instance:
+```ruby
+locs_response = api.apps(123).locations.list # gets a page of locations associated with an app
+locs_response.locations # => [location 1, location 2...location 10]
+
+locs_response.next_page? # => true if there is another page of results to load
+
+next_page_response = locs_response.next # gets the next page of results
+```
 
 ## Errors
 

data/lib/levelup.rb

@@ -6,6 +6,7 @@ require 'levelup/configuration'
 
 require 'levelup/templates/data_parcel'
 require 'levelup/templates/user_address_data'
+require 'levelup/templates/app_authenticated'
 require 'levelup/templates/merchant_authenticated'
 require 'levelup/templates/merchant_and_user_authenticated'
 require 'levelup/templates/user_authenticated'
@@ -21,6 +22,7 @@ require 'levelup/requests/get_order'
 require 'levelup/requests/get_qr_code'
 require 'levelup/requests/get_user'
 require 'levelup/requests/give_merchant_credit'
+require 'levelup/requests/list_app_locations'
 require 'levelup/requests/list_addresses'
 require 'levelup/requests/list_locations'
 require 'levelup/requests/list_orders'
@@ -30,10 +32,12 @@ require 'levelup/requests/request_permissions'
 require 'levelup/requests/show_permissions_request'
 
 require 'levelup/responses/success'
+require 'levelup/responses/success_paginated'
 require 'levelup/responses/error'
 
 require 'levelup/endpoints/base'
 require 'levelup/endpoints/access_tokens'
+require 'levelup/endpoints/app_locations'
 require 'levelup/endpoints/app_users'
 require 'levelup/endpoints/apps'
 require 'levelup/endpoints/credit_cards'
@@ -44,6 +48,7 @@ require 'levelup/endpoints/merchant_orders'
 require 'levelup/endpoints/orders'
 require 'levelup/endpoints/permissions_requests'
 require 'levelup/endpoints/qr_codes'
+require 'levelup/endpoints/specific_app'
 require 'levelup/endpoints/specific_location'
 require 'levelup/endpoints/specific_merchant'
 require 'levelup/endpoints/specific_order'

data/lib/levelup/api.rb

@@ -30,8 +30,12 @@ module Levelup
     end
 
     # Generates an interface for the +apps+ endpoint.
-    def apps
-      Endpoints::Apps.new(app_access_token)
+    def apps(app_id = nil)
+      if app_id
+        Endpoints::SpecificApp.new(app_id)
+      else
+        Endpoints::Apps.new(app_access_token)
+      end
     end
 
     # Verifies if an access token is present for app-authenticated endpoints

data/lib/levelup/configuration.rb

@@ -1,6 +1,6 @@
 module Levelup
   class Configuration
-    VERSION = '0.9.2'
+    VERSION = '0.9.3'
     DEFAULT_API_VERSION = :v15
 
     class << self

data/lib/levelup/endpoints/app_locations.rb

@@ -0,0 +1,27 @@
+module Levelup
+  module Endpoints
+    # The endpoint holding all functions relating to a specific app's locations.
+    # This endpoint is a v14 endpoint and should not be expected to remain
+    # accessible indefinitely.
+    class AppLocations < Base
+      def initialize(id)
+        self.id = id
+      end
+
+      # Provides a list of locations controlled by this app. This list is
+      # paginated.
+      def list
+        request = Requests::ListAppLocations.new
+        request.send_to_api(:get, endpoint_path(:v14))
+      end
+
+      private
+
+      attr_accessor :id
+
+      def path
+        "apps/#{id}/locations"
+      end
+    end
+  end
+end

data/lib/levelup/endpoints/permissions_requests.rb

@@ -4,7 +4,7 @@ module Levelup
     # requests.
     class PermissionsRequests < Base
       def initialize(app_access_token)
-        @app_access_token = app_access_token
+        self.app_access_token = app_access_token
       end
 
       # Requests a set of permissions from the specified user.
@@ -18,7 +18,7 @@ module Levelup
 
       private
 
-      attr_reader :app_access_token
+      attr_accessor :app_access_token
 
       def path
         'apps/permissions_requests'

data/lib/levelup/endpoints/specific_app.rb

@@ -0,0 +1,23 @@
+module Levelup
+  module Endpoints
+    # The endpoint serving as a bucket for all functions related to a specific
+    # app.
+    class SpecificApp < Base
+      def initialize(id)
+        self.id = id
+      end
+
+      def locations
+        AppLocations.new(id)
+      end
+
+      private
+
+      attr_accessor :id
+
+      def path
+        "apps/#{id}"
+      end
+    end
+  end
+end

data/lib/levelup/endpoints/specific_order.rb

@@ -2,9 +2,8 @@ module Levelup
   module Endpoints
     # Endpoint holding all functions relating to a specified order.
     class SpecificOrder < Base
-      attr_reader :uuid
       def initialize(order_uuid)
-        @uuid = order_uuid
+        self.uuid = order_uuid
       end
 
       # Refunds the order specified by this endpoint.
@@ -20,6 +19,8 @@ module Levelup
 
       private
 
+      attr_accessor :uuid
+
       def path
         "orders/#{uuid}"
       end

data/lib/levelup/endpoints/specific_permissions_request.rb

@@ -8,9 +8,9 @@ module Levelup
         self.request_id = request_id
       end
 
-      def show
+      def show(app_token = nil)
         request = Requests::ShowPermissionsRequest.
-          new(app_access_token: app_access_token)
+          new(app_access_token: app_access_token || app_token)
         request.send_to_api(:get, endpoint_path)
       end
 

data/lib/levelup/requests/base.rb

@@ -40,10 +40,22 @@ module Levelup
         raise NotImplementedError, 'Response generator not defined.'
       end
 
-      # Makes a call by the specified method to the specified endpoint, sending
-      # this request object. If successful, builds a response object according
-      # to response_from_hash. If unsuccessful, simply returns an ErrorResponse.
+      # Calls send_via_httparty, returning either an error response or the
+      # response as generated by this request's response_from_hash function.
+      # This function can be overridden to control how a request builds its
+      # response.
       def send_to_api(method, endpoint)
+        send_via_httparty(method, endpoint) do |response|
+          response_from_hash(response.parsed_response)
+        end
+      end
+
+      private
+
+      # Makes a call by the specified method to the specified endpoint, sending
+      # this request object. If successful, yields the HTTParty response to the
+      # calling method. If unsuccessful, simply returns an ErrorResponse.
+      def send_via_httparty(method, endpoint)
         unless ALLOWED_REQUEST_METHODS.include?(method)
           raise Errors::InvalidRequest, 'Attempted to send a request to'\
           " LevelUp API via invalid method #{method}"
@@ -53,15 +65,13 @@ module Levelup
           body: JSON.generate(body), headers: headers)
 
         if response.success?
-          response_from_hash(response.parsed_response)
+          yield response
         else
           Responses::Error.new(response.headers, response.parsed_response,
             response.code)
         end
       end
 
-      private
-
       DEFAULT_HEADERS = {
         'Accept' => 'application/json',
         'Content-Type' => 'application/json'

data/lib/levelup/requests/create_order.rb

@@ -15,7 +15,11 @@ module Levelup
       attr_accessor :spend_amount
 
       def body
-        items = @items.map do |item|
+        items = (@items || []).map do |item|
+          if item.empty?
+            next
+          end
+
           { item: item }
         end
 

data/lib/levelup/requests/create_user.rb

@@ -3,7 +3,7 @@ module Levelup
     # Represents a request to create a new user with the specified list of
     # permissions.
     class CreateUser < Base
-      attr_accessor :app_access_token
+      include Templates::AppAuthenticated
       # An array of Item objects (or hashes representing them) representing all
       # items purchased by this order.
       attr_accessor :email
@@ -11,10 +11,6 @@ module Levelup
       attr_accessor :last_name
       attr_accessor :permission_keynames
 
-      def auth_type
-        :app
-      end
-
       def body
         user_hash = {
           email: email,

data/lib/levelup/requests/give_merchant_credit.rb

@@ -7,10 +7,6 @@ module Levelup
       include Templates::MerchantAuthenticated
       attr_accessor :email, :value_amount
 
-      def auth_type
-        :merchant
-      end
-
       def body
         { merchant_funded_credit: to_hash }
       end

data/lib/levelup/requests/list_app_locations.rb

@@ -0,0 +1,35 @@
+module Levelup
+  module Requests
+    # Represents a request to list all locations under
+    # a specified app. The list is paginated.
+    class ListAppLocations < Base
+      def auth_type
+        :none
+      end
+
+      def response_from_hash(hash)
+        if hash.nil? # no locations found for this app
+          Responses::SuccessPaginated.new(locations: [])
+        else
+          locations =
+            hash.map { |location| OpenStruct.new(location['location']) }
+          Responses::SuccessPaginated.new(locations: locations)
+        end
+      end
+
+      def send_to_api(method, endpoint)
+        send_via_httparty(method, endpoint) do |response|
+          paginated_response = response_from_hash(response)
+
+          if response.headers['Link']
+            paginated_response.next_page =
+              /\<([^>]+)\>/.match(response.headers['Link'])[1]
+            paginated_response.next_page_request = ListAppLocations.new
+          end
+
+          paginated_response
+        end
+      end
+    end
+  end
+end

data/lib/levelup/requests/request_permissions.rb

@@ -3,7 +3,7 @@ module Levelup
     # Represents a request to request a set of permissions
     # from a specified account (merchant or user).
     class RequestPermissions < Base
-      attr_accessor :app_access_token
+      include Templates::AppAuthenticated
       # The email address of the requested user or merchant.
       attr_accessor :email
       # An array of strings representing desired permissions from the user or
@@ -11,10 +11,6 @@ module Levelup
       # 'manage_merchant_orders'
       attr_accessor :permission_keynames
 
-      def auth_type
-        :app
-      end
-
       def body
         { permissions_request: to_hash }
       end

data/lib/levelup/requests/show_permissions_request.rb

@@ -3,11 +3,7 @@ module Levelup
     # Represents a request to show the status of a specified permissions
     # request.
     class ShowPermissionsRequest < Base
-      attr_accessor :app_access_token
-
-      def auth_type
-        :app
-      end
+      include Templates::AppAuthenticated
 
       def body
         {}

data/lib/levelup/responses/error.rb

@@ -21,7 +21,8 @@ module Levelup
             OpenStruct.new(error['error'])
           end
         else
-          @errors = [{ message: 'Could not parse error body' }]
+          @errors = [OpenStruct.new(message: 'The API returned an unexpected '\
+            'response. This is likely due to an incorrectly defined base URL.')]
         end
 
         @status_code = status_code

data/lib/levelup/responses/success_paginated.rb

@@ -0,0 +1,26 @@
+module Levelup
+  module Responses
+    # Class that encapsulates a successful response from a paginated endpoint
+    # of the LevelUp API.
+    class SuccessPaginated < Success
+      attr_writer :next_page_request, :next_page
+
+      def next_page?
+        !next_page_request.nil? && !next_page.nil?
+      end
+
+      def next
+        unless next_page?
+          raise Errors::InvalidRequest, 'Attempted to fetch next page at '\
+            'final page of list'
+        end
+
+        next_page_request.send_to_api(:get, next_page)
+      end
+
+      private
+
+      attr_reader :next_page_request, :next_page
+    end
+  end
+end

data/lib/levelup/templates/app_authenticated.rb

@@ -0,0 +1,16 @@
+module Levelup
+  module Templates
+    # A template to apply to any requests requiring app authentication.
+    #
+    # Authentication template - only apply one authentication template per
+    # request.
+    module AppAuthenticated
+      # An access token for an app.
+      attr_accessor :app_access_token
+
+      def auth_type
+        :app
+      end
+    end
+  end
+end

data/spec/data_objects/responses/success_paginated_spec.rb

@@ -0,0 +1,51 @@
+require 'spec_helper'
+
+describe 'Levelup::Responses::SuccessPaginated', vcr: true do
+  before do
+    example_paginated_url = "#{Levelup::Configuration.api_url(:v14)}/apps/"\
+      "#{TestConfig.app_id}/locations"
+    @has_next_response = Levelup::Responses::SuccessPaginated.new
+    @has_next_response.next_page = example_paginated_url
+    @has_next_response.next_page_request =
+      Levelup::Requests::ListAppLocations.new
+
+    @no_next_response = Levelup::Responses::SuccessPaginated.new
+  end
+
+  describe '#success?' do
+    it 'returns true' do
+      expect(@has_next_response).to be_success
+    end
+  end
+
+  describe '#next_page?' do
+    context 'with no next page' do
+      it 'returns false' do
+        expect(@no_next_response.next_page?).to be_false
+      end
+    end
+
+    context 'with another page to retrieve' do
+      it 'returns true' do
+        expect(@has_next_response.next_page?).to be_true
+      end
+    end
+  end
+
+  describe '#next' do
+    context 'with no next page' do
+      it 'raises an InvalidRequest error' do
+        expect { @no_next_response.next }.
+          to raise_error(Levelup::Errors::InvalidRequest)
+      end
+    end
+
+    context 'with a next page' do
+      it 'successfully returns the next page' do
+        next_page_response = @has_next_response.next
+
+        expect(next_page_response).to be_success
+      end
+    end
+  end
+end

data/spec/endpoints/app_locations_spec.rb

@@ -0,0 +1,18 @@
+require 'spec_helper'
+
+describe 'Levelup::Endpoints::AppLocations', vcr: true do
+  describe '#list' do
+    it 'fetches a list of locations' do
+      response = @test_client.apps(TestConfig.app_id).locations.list
+
+      expect(response).to be_success
+      expect(response.locations.length).to be > 0
+    end
+
+    it 'fetches a second page of locations' do
+      next_response = @test_client.apps(TestConfig.app_id).locations.list.next
+
+      expect(next_response).to be_success
+    end
+  end
+end

data/spec/fixtures/keys.yml.example

@@ -2,6 +2,7 @@
 api_key_valid: key
 secret_valid: secret
 location_id: 123
+app_id: 456
 merchant_token_with_grant_credit_perms: token
 merchant_token_with_manage_orders_perms: token (can be same as other merchant token)
 merchant_api_key: token_v14

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: levelup
 version: !ruby/object:Gem::Version
-  version: 0.9.2
+  version: 0.9.3
 platform: ruby
 authors:
 - LevelUp POS Team
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-06-19 00:00:00.000000000 Z
+date: 2014-06-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -150,7 +150,6 @@ files:
 - ".rubocop.yml"
 - Gemfile
 - Gemfile.lock
-- LICENSE
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -159,6 +158,7 @@ files:
 - lib/levelup/api.rb
 - lib/levelup/configuration.rb
 - lib/levelup/endpoints/access_tokens.rb
+- lib/levelup/endpoints/app_locations.rb
 - lib/levelup/endpoints/app_users.rb
 - lib/levelup/endpoints/apps.rb
 - lib/levelup/endpoints/base.rb
@@ -170,6 +170,7 @@ files:
 - lib/levelup/endpoints/orders.rb
 - lib/levelup/endpoints/permissions_requests.rb
 - lib/levelup/endpoints/qr_codes.rb
+- lib/levelup/endpoints/specific_app.rb
 - lib/levelup/endpoints/specific_location.rb
 - lib/levelup/endpoints/specific_merchant.rb
 - lib/levelup/endpoints/specific_order.rb
@@ -191,6 +192,7 @@ files:
 - lib/levelup/requests/get_user.rb
 - lib/levelup/requests/give_merchant_credit.rb
 - lib/levelup/requests/list_addresses.rb
+- lib/levelup/requests/list_app_locations.rb
 - lib/levelup/requests/list_locations.rb
 - lib/levelup/requests/list_orders.rb
 - lib/levelup/requests/list_user_orders.rb
@@ -199,6 +201,8 @@ files:
 - lib/levelup/requests/show_permissions_request.rb
 - lib/levelup/responses/error.rb
 - lib/levelup/responses/success.rb
+- lib/levelup/responses/success_paginated.rb
+- lib/levelup/templates/app_authenticated.rb
 - lib/levelup/templates/data_parcel.rb
 - lib/levelup/templates/merchant_and_user_authenticated.rb
 - lib/levelup/templates/merchant_authenticated.rb
@@ -214,7 +218,9 @@ files:
 - spec/data_objects/requests/request_permissions_spec.rb
 - spec/data_objects/responses/error_spec.rb
 - spec/data_objects/responses/response_spec.rb
+- spec/data_objects/responses/success_paginated_spec.rb
 - spec/endpoints/access_tokens_spec.rb
+- spec/endpoints/app_locations_spec.rb
 - spec/endpoints/app_users_spec.rb
 - spec/endpoints/location_orders_spec.rb
 - spec/endpoints/merchant_funded_credits_spec.rb
@@ -264,7 +270,9 @@ test_files:
 - spec/data_objects/requests/request_permissions_spec.rb
 - spec/data_objects/responses/error_spec.rb
 - spec/data_objects/responses/response_spec.rb
+- spec/data_objects/responses/success_paginated_spec.rb
 - spec/endpoints/access_tokens_spec.rb
+- spec/endpoints/app_locations_spec.rb
 - spec/endpoints/app_users_spec.rb
 - spec/endpoints/location_orders_spec.rb
 - spec/endpoints/merchant_funded_credits_spec.rb

data/LICENSE

@@ -1,21 +0,0 @@
-The MIT License (MIT)
-
-Copyright (c) 2014 LevelUp
-
-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.