levelup 0.9.4 → 0.9.5

data/Gemfile.lock

@@ -15,7 +15,7 @@ GEM
     httparty (0.13.1)
       json (~> 1.8)
       multi_xml (>= 0.5.2)
-    json (1.8.1)
+    json (1.8.2)
     multi_xml (0.5.5)
     parser (2.1.9)
       ast (>= 1.1, < 3.0)

data/README.md

@@ -19,52 +19,98 @@ Or install it yourself as:
 
     $ gem install levelup
 
+## Documentation
+
+[![Documentation](http://img.shields.io/badge/docs-rdoc.info-blue.svg)](http://rubydoc.org/gems/levelup/frames)
+
 ## Usage
 
-1. Create an instance of the LevelUp client and authenticate it.
+### Do once per LevelUp-powered application:
+-  Create an instance of the LevelUp client and authenticate it.
 
 ```ruby
 api = Levelup::Api.new
+
+# While testing:
+Levelup::Configuration.base_api_url = 'https://sandbox.thelevelup.com/'
+
+# For production, these should be ENV variables:
+api_key = '23eef8c2895ce66eb4500bb5e324b200f5339e6fe6d8665f6de0205f43f3b563'
+client_secret = '4d71e958b9fb6a62af624390c4ef394df15d168ea12b3b12735643ff0694520f'
+
 auth_response = api.access_tokens.create_for_app(
-  api_key: 'your_api_key',
-  client_secret: 'your_secret')
+  api_key: api_key,
+  client_secret: client_secret)
+
 api.app_access_token = auth_response.token
+```
+
+### Do once per merchant account
 
-# or if you've saved your access token (recommended) just:
-api = Levelup::Api.new(app_access_token: 'your_access_token')
+- Authenticate merchants using LevelUp email and password
+
+```ruby
+username = 'sandboxdevexample@thelevelup.com'
+password = 'fod2yau4flu6vok6'
+
+merchant_token = api.access_tokens.create_for_merchant(
+  api_key: api_key, username: username, password: password)
 ```
 
-2. Ensure you have permissions to manage orders for your merchant (if you haven't already done so)
+### Do for each merchant location
+
+- Prompt merchant to map LevelUp locations to each of their online ordering locations
 
 ```ruby
-api.apps.permissions_requests.create(
-  email: 'merchant@email.com',
-  permission_keynames: ['manage_merchant_orders'])
-# Approve the request through the merchant email and the LevelUp API
-# will post you a merchant access token.
+locations_response = api.merchants(merchant_id).locations.list(merchant_access_token)
 
-# See http://developer.thelevelup.com/api-reference/v15/user-permissions/
-# for more on receiving access tokens.
+# For testing purposes, we'll use the first location
+
+location = locations_response.locations[0]
+location_id = location.id
 ```
 
-3. Ask a user for permission to make an order for them.
+### Do for each customer
+
+- Ask a user for permission to make an order for them (alternatively you can use our
+[OpenID](http://developer.thelevelup.com/resources-and-guides/web-authentication-flow/) or
+[Oauth2](http://developer.thelevelup.com/resources-and-guides/web-authorization-flow/) flows). 
+For more information on available permissions, see the
+[LevelUp permissions list](http://developer.thelevelup.com/resources-and-guides/permissions-list/)
 
 ```ruby
 api.apps.permissions_requests.create(
   email: 'user@email.com',
-  permission_keynames: ['create_orders'])
+  permission_keynames: ['create_orders', 'read_qr_code'])
 # wait for the user to approve the request. you will receive a user
 # access token in the same manner as above.
 ```
 
-3. Create an order for the specified merchant.
+- Retrieve a user's QR code
+
+```ruby
+qr_code_response = api.qr_codes.get(customer_token)
+
+qr_code = qr_code_response.code
+```
+
+- Create an order for the specified merchant.
 
 ```ruby
-response = api.orders.create(
-  identifier_from_merchant: '0123',
-  location_id: 321,
-  spend_amount: 350, # in cents; 350 = $3.50
-  items: [
+
+# Check for merchant_funded_credit
+
+discount_response = api.locations(location_id).merchant_funded_credit.get(
+  qr_code, merchant_access_token)
+
+# Define the details from the check
+
+check_total_due_including_tax = 110 # Total amount of payment due on the check (in cents)
+exempted_item_total = 0 # Total amount of exempted (milk, cigarettes etc) items (in cents)
+spend_amount_requested = 110 # Total amount of payment requested from LevelUp (in cents)
+tax_amount_due = 10 # Total tax amount due on check (in cents)
+identifier_from_merchant = '01234' # Unique check identifier in your platform (ie, check ID)
+check_items_array = [ # Array of all items on the check
     {
       charged_price: 350,
       description: 'Non-poisonous, supplies vital nutrients',
@@ -75,13 +121,57 @@ response = api.orders.create(
       standard_price: 350
     }
     # more items can go here
-  ],
-  merchant_access_token: 'merchant-token',
-  user_access_token: 'user-token')
+  ]
+
+# Determine the amount of discount to apply to the check
+
+credit_to_apply = Levelup::Utils::PaymentCalculator.levelup_discount_to_apply(
+  check_total_due_including_tax: check_total_due_including_tax,
+  exempted_item_total: exempted_item_total,
+  merchant_funded_credit_available: discount_response.discount_amount,  
+  payment_amount_requested: spend_amount_requested,
+  tax_amount_due: tax_amount_due,
+)
+
+# Apply the discount to the check
+
+# Create a new order request
+order_response = api.orders.create(
+  identifier_from_merchant: identifier_from_merchant,
+  location_id: location_id,
+  spend_amount: spend_amount_requested,
+  items: check_items_array,
+  merchant_access_token: merchant_access_token,
+  user_access_token: qr_code)
+
+calculator = Levelup::Utils::PaymentCalculator.new(
+  discount_applied: credit_to_apply,
+  gift_card_credit_available: discount_response.gift_card_amount,
+  spend_amount_returned_from_levelup: order_response.spend_amount,
+  tip_returned_from_levelup: order_response.tip_amount
+)
+
+# Get relevant amounts to apply to check and apply as necessary
+
+calculator.gift_card_payment_to_apply
+calculator.gift_card_tip_to_apply
+calculator.levelup_payment_to_apply
+calculator.levelup_tip_to_apply
+
+# Additional values are also available (if desired)
+
+calculator.total_gift_card_payment_to_apply_including_tip
+calculator.gift_card_remaining_balance_after_payment
+calculator.total_levelup_payment_to_apply_including_tip
+
+# Apply each payment to the check and close the check (assuming balance due is 0)
 ```
 
-The LevelUp Ruby SDK mirrors the API as closely as possible, so the call for any given endpoint can be inferred from its URL.
+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
@@ -90,10 +180,12 @@ 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.
+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]
@@ -105,8 +197,9 @@ next_page_response = locs_response.next # gets the next page of results
 
 ## Errors
 
-If the LevelUp API returns an error response (Any HTTP code 400 or greater), it will return an object
-containing useful info about the error. It can be handled like so:
+If the LevelUp API returns a 422 error response, it will also return an object containing useful
+info about the error. It can be handled like so:
+
 ```ruby
 error = api.access_tokens.create_for_app(
   api_key: 'bogus_api_key',
@@ -123,18 +216,18 @@ puts error.errors[0].property # => 'api_key'
 
 ## Contributing
 
-1. Fork it ( https://github.com/TheLevelup/pos-ruby-sdk/fork )
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Ensure that Rubocop gives you a clean bill of health
+-  Fork it (https://github.com/TheLevelup/levelup-sdk-ruby/fork)
+-  Create your feature branch (`git checkout -b my-new-feature`)
+-  Ensure that Rubocop gives you a clean bill of health
 ```
 cd path/to/my/ruby-sdk-folder
-rubocop
+bundle exec rubocop
 ```
-4. Ensure that all RSpec tests pass (and write some for your code!)
+-  Ensure that all RSpec tests pass (and write some for your code!)
 ```
 cd path/to/my/ruby-sdk-folder
-rspec
+bundle exec rspec
 ```
-4. Commit your changes (`git commit -am 'Add some feature'`)
-5. Push to the branch (`git push origin my-new-feature`)
-6. Create a new Pull Request
+-  Commit your changes (`git commit -am 'Add some feature'`)
+-  Push to the branch (`git push origin my-new-feature`)
+-  Create a new Pull Request

data/levelup.gemspec

@@ -30,5 +30,5 @@ Gem::Specification.new do |spec|
 
   spec.add_runtime_dependency 'httparty', '~> 0.13.1'
 
-  spec.required_ruby_version = '>= 1.9.3'
+  spec.required_ruby_version = '>= 2.0.0'
 end

data/lib/levelup.rb

@@ -19,6 +19,7 @@ require 'levelup/requests/create_card'
 require 'levelup/requests/create_order'
 require 'levelup/requests/create_user'
 require 'levelup/requests/get_location_credit'
+require 'levelup/requests/get_location_merchant_funded_credit'
 require 'levelup/requests/get_order'
 require 'levelup/requests/get_qr_code'
 require 'levelup/requests/get_user'
@@ -43,6 +44,7 @@ require 'levelup/endpoints/app_users'
 require 'levelup/endpoints/apps'
 require 'levelup/endpoints/credit_cards'
 require 'levelup/endpoints/location_credit'
+require 'levelup/endpoints/location_merchant_funded_credit'
 require 'levelup/endpoints/location_orders'
 require 'levelup/endpoints/merchant_funded_credits'
 require 'levelup/endpoints/merchant_locations'
@@ -59,4 +61,6 @@ require 'levelup/endpoints/user_addresses'
 require 'levelup/endpoints/user_orders'
 require 'levelup/endpoints/users'
 
+require 'levelup/utils/payment_calculator'
+
 require 'levelup/api'

data/lib/levelup/api.rb

@@ -3,8 +3,7 @@
 # of utilizing LevelUp for online ordering and web payments.
 
 module Levelup
-  # This API is the base class that handles all requests made to the LevelUp
-  # API.
+  # This is the base class that handles all requests made to the LevelUp API.
   class Api
     # Token to access app-authenticated endpoints
     attr_writer :app_access_token

data/lib/levelup/configuration.rb

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

data/lib/levelup/endpoints/access_tokens.rb

@@ -1,7 +1,6 @@
 module Levelup
   module Endpoints
-    # The endpoint holding all functions related to the management of access
-    # tokens.
+    # The endpoint holding all functions related to the management of access tokens.
     class AccessTokens < Base
       # The API key assigned to your app. Preconfigured key.
       attr_writer :api_key
@@ -16,18 +15,16 @@ module Levelup
       # Generates a new app access token. If passed no parameters, attempts to
       # pass the preconfigured API key and client secret to the endpoint.
       def create_for_app(app_auth_request = nil)
-        request = build_request(app_auth_request || { api_key: @api_key,
-          client_secret: @secret },
-          Requests::AuthenticateApp)
-
-        request.send_to_api(:post, endpoint_path)
+        build_request(app_auth_request || { api_key: @api_key, client_secret: @secret },
+            Requests::AuthenticateApp).
+          send_to_api(:post, endpoint_path)
       end
 
       # Generates a new merchant access token.
       def create_for_merchant(merchant_auth_request)
-        request = build_request(merchant_auth_request,
-          Requests::AuthenticateMerchant)
-        request.send_to_api(:post, endpoint_path(:v14))
+        build_request(merchant_auth_request,
+            Requests::AuthenticateMerchant).
+          send_to_api(:post, endpoint_path(:v14))
       end
 
       private

data/lib/levelup/endpoints/app_locations.rb

@@ -1,18 +1,16 @@
 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.
+    # 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.
+      # 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))
+        Requests::ListAppLocations.new.
+          send_to_api(:get, endpoint_path(:v14))
       end
 
       private

data/lib/levelup/endpoints/app_users.rb

@@ -1,7 +1,6 @@
 module Levelup
   module Endpoints
-    # The endpoint holding all functions related to managing users under the
-    # current app.
+    # The endpoint holding all functions related to managing users under the current app.
     class AppUsers < Base
       def initialize(app_access_token)
         @app_access_token = app_access_token
@@ -13,11 +12,6 @@ module Levelup
         request.send_to_api(:post, endpoint_path)
       end
 
-      def get(user_access_token)
-        request = Requests::GetUser.new(user_access_token: user_access_token)
-        request.send_to_api(:get, endpoint_path)
-      end
-
       private
 
       attr_reader :app_access_token

data/lib/levelup/endpoints/credit_cards.rb

@@ -1,14 +1,13 @@
 module Levelup
   module Endpoints
-    # The endpoint holding all functions related to managing users' credit
-    # cards.
+    # The endpoint holding all functions related to managing users' credit cards.
     class CreditCards < Base
       # Adds a credit card to a user's account. Requires a user access token
       # with create_first_credit_card permission.
       # This request will fail unless the user account has no credit card on it.
       def create(credit_card_request)
-        request = build_request(credit_card_request, Requests::CreateCard)
-        request.send_to_api(:get, endpoint_path)
+        build_request(credit_card_request, Requests::CreateCard).
+          send_to_api(:get, endpoint_path)
       end
 
       private

data/lib/levelup/endpoints/location_credit.rb

@@ -1,22 +1,20 @@
 module Levelup
   module Endpoints
-    # The endpoint holding all functions relating to available credit at
-    # locations.
+    # The endpoint holding all functions relating to available credit at locations.
     class LocationCredit < Base
-      attr_reader :id
-
       def initialize(location_id)
-        @id = location_id
+        self.id = location_id
       end
 
       def get(user_access_token)
-        request = 
-          Requests::GetLocationCredit.new(user_access_token: user_access_token)
-        request.send_to_api(:get, endpoint_path)
+        Requests::GetLocationCredit.new(user_access_token: user_access_token).
+          send_to_api :get, endpoint_path
       end
 
       private
 
+      attr_accessor :id
+
       def path
         "locations/#{id}/credit"
       end

data/lib/levelup/endpoints/location_merchant_funded_credit.rb

@@ -0,0 +1,23 @@
+module Levelup
+  module Endpoints
+    # The endpoint holding all functions relating to managing merchant-funded credit.
+    class LocationMerchantFundedCredit < Base
+      def initialize(location_id)
+        @id = location_id
+      end
+
+      def get(payment_token_data, merchant_access_token)
+        @payment_token_data = payment_token_data
+        Requests::GetLocationMerchantFundedCredit.new(
+            merchant_access_token: merchant_access_token).
+          send_to_api :get, endpoint_path
+      end
+
+      private
+
+      def path
+        "locations/#{@id}/merchant_funded_credit?payment_token_data=#{@payment_token_data}"
+      end
+    end
+  end
+end

data/lib/levelup/endpoints/location_orders.rb

@@ -1,28 +1,22 @@
 module Levelup
   module Endpoints
-    # The endpoint holding all functions relating to orders for a specific
-    # location.
-    # This is a v14 endpoint and should not be expected to remain functional
-    # indefinitely.
+    # The endpoint holding all functions relating to orders for a specific location.
+    # This is a v14 endpoint and should not be expected to remain functional indefinitely.
     class LocationOrders < Base
       def initialize(location_id)
-        @id = location_id
+        self.id = location_id
       end
 
       # Gets a list of orders made at this location. This list is paginated.
-      #
-      # [merchant_auth_token]
-      #   An access token for the merchant that owns this
-      #   location.
-      def list(merchant_auth_token)
-        request = Requests::ListOrders.new(
-          merchant_access_token: merchant_auth_token)
-        request.send_to_api(:get, endpoint_path(:v14))
+      # @param merchant_access_token [string] An access token for a user that manages this location.
+      def list(merchant_access_token)
+        Requests::ListOrders.new(merchant_access_token: merchant_access_token).
+          send_to_api(:get, endpoint_path(:v14))
       end
 
       private
 
-      attr_reader :id
+      attr_accessor :id
 
       def path
         "locations/#{id}/orders"