tangocard 0.1.0 → 0.2.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    NDYyMGMwNGRhZmQ4ZjlhOGFjZjcwZDNlOTRhZjBkOWNiYjQ5M2IyMA==
+    OGYwODkzOWEyZGFkNjZkZTliNzQyZWJhNDU4NGE0NDY4NTJlMWZjNA==
   data.tar.gz: !binary |-
-    YjZiYTE0ZTNkZGNiNzVlY2NkZTk4YTMxZWJjNzgwNzM5MTI5NjE0MA==
+    NTRkNDVlOGFlM2E4NTJjZTgyNGE2ZjMzMzA0YTQ2Y2IwNDdmZTliNQ==
 SHA512:
   metadata.gz: !binary |-
-    OGVjODkzNWM1NWMwZTNkYzI2ZWY4ZjZiNzMzOWI4Zjc5YzFjMjNiOGJkNzFl
-    MmQyOWRmNDJlNjgyODcyZjNhNzFmM2M2ZTY0YjcwODJhNzM2ZmE3MTJhMjBi
-    NmVhMTE3MzUwODI3OWY2NzQyNDI5NTRhNmFiNTVjYTMxNmNkODA=
+    OWJhMDlkMTBiNzllZWM3YmI3YWRjZGNkMjBiN2YxMWQwZmI0YTdjYjVkNzU0
+    YTRjNjNmNWJlZDZjY2NlZmNlYjFhMGJlYmQ4NWMwNGM5MGFiZmYyNTVjZDgz
+    YTgwMmUwZTkyMTEwZmM5ZDcyYzdiZWM3Yjc3MDA3ODgyZWYxMzQ=
   data.tar.gz: !binary |-
-    Y2Q1N2QzNTI1M2EyNWY5N2UyYzU4NWZlZGI0NmY4YTllMDM4YmY5ZGYxZjNk
-    NTNjMjIzMjNhMjE0ZTkyZTY4NTg4OTUwMWE5Yzk0NzRiNmIzZjA0ZTczYzE0
-    MDE0MWE2YmIyYjY5NTAzZDdjYmFiYzFhOGZhYThjMzhkYzYxNWI=
+    NGNiYThjYTE2NzNlODhhMDYxNTE0YjI1OTFjMTk3OWFiNjdkZmEwNDcxOTFk
+    NTdlMjgzZmM2ZjdhYzhmZjVlNWEwYzRjZGE2ZDk2NTYwYjc1ZTIyYTkxNTA1
+    YzdkNDNhZTE3Yjg0ZTRkNGYzZTk3OTRhMGM3YzE5OTRiNzhkZWQ=

data/README.md

@@ -0,0 +1,60 @@
+# Tangocard
+
+Ruby Wrapper for Tango Card RaaS API.
+
+Tango Card provides a RaaS API for developers (https://github.com/tangocarddev/RaaS). This gem provides commonsense Ruby
+objects to wrap the JSON endpoints of the RaaS API.
+
+## Information
+
+* RDoc documentation [available on RubyDoc.info](http://rubydoc.info/github/bonusly/tangocard/master/frames)
+* Source code [available on GitHub](https://github.com/bonusly/tangocard)
+
+## Getting Help
+
+* Please report bugs on the [issue tracker](https://github.com/bonusly/tangocard/issues)
+
+## Installation
+
+### Rails 3
+
+Add the `tangocard` gem to your `Gemfile`:
+
+```
+gem 'tangocard'
+```
+
+Create an initializer, e.g. `config/initializers/tangocard.rb`:
+
+```
+Tangocard.configure do |c|
+  c.name = "BonuslyXYZ"
+  c.key = "Dnv9ehvff29"
+  c.base_uri = "https://sandbox.tangocard.com"
+end
+```
+
+There are three required configuration parameters:
+
+ * `name` - The API account name you receive from Tango Card
+ * `key` - The API account key you receive from Tango Card
+ * `base_uri` - This defaults to the Tango Card sandbox.  For production, you must specify the base URI for the produciton RaaS API
+
+There are also three optional configuration parameters:
+
+ * `default_brands` - An array of strings for the brands you want to retrieve with Tangocard::Brand.default_brands.  The strings should match the unique brand `description` fields exactly.
+ * `local_images` - An array of local image names/URIs that you want to display instead of the default Tango Card-provided `image_url`.  `image_url is sometimes blank, so this can be handy in those cases.
+ * `sku_blacklist` - Reward SKUs that are blacklisted, ie. should never be returned as a purchasable reward.
+
+## Getting Started
+
+This gem provides two tools:
+
+1. A simple wrapper for the Tango Card RaaS API, consisting of two classes: `Tangocard::Raas` and `Tangocard::Response`.
+2. Models for each of the Tango Card objects: Accounts, Brands, Rewards, and Orders.  These provide a greater level of abstraction and ease of use.
+
+## Notes and Credits
+
+This project is developed and maintained by Smartly, Inc. - makers of http://bonus.ly.
+
+This project uses the MIT-LICENSE.

data/lib/tangocard/account.rb

@@ -1,29 +1,57 @@
-# Wrapper for Tangocard RaaS Account
-# https://github.com/tangocarddev/RaaS#account-resources
 class Tangocard::Account
   attr_reader :customer, :identifier, :email, :available_balance
 
   private_class_method :new
 
-  # parsed_response={"success"=>true, "account"=>{"identifier"=>"test1", "email"=>"test@test.com", "customer"=>"bonusly", "available_balance"=>0}}
+  # Find account given customer and identifier. Raises Tangocard::AccountNotFoundException on failure.
+  #
+  # Example:
+  #   >> Tangocard::Account.find('bonusly', 'test')
+  #    => #<Tangocard::Account:0x007f9a6fec0138 @customer="bonusly", @email="dev@bonus.ly", @identifier="test", @available_balance=1200>
+  #
+  # Arguments:
+  #   customer: (String)
+  #   identifier: (String)
   def self.find(customer, identifier)
     response = Tangocard::Raas.show_account({'customer' => customer, 'identifier' => identifier})
     if response.success?
       new(response.parsed_response['account'])
     else
-      raise Tangocard::AccountNotFoundException, "Tangocard - Error finding account: #{response.error_message}"
+      raise Tangocard::AccountNotFoundException, "#{response.error_message}"
     end
   end
 
+  # Create account given customer, identifier, and email.
+  # Raises Tangocard::AccountCreateFailedException on failure.
+  #
+  # Example:
+  #   >> Tangocard::Account.create('bonusly', 'test', 'dev@bonus.ly')
+  #    => #<Tangocard::Account:0x007f9a6fec0138 @customer="bonusly", @email="dev@bonus.ly", @identifier="test", @available_balance=0>
+  #
+  # Arguments:
+  #   customer: (String)
+  #   identifier: (String)
+  #   email: (String)
   def self.create(customer, identifier, email)
     response = Tangocard::Raas.create_account({'customer' => customer, 'identifier' => identifier, 'email' => email})
     if response.success?
       new(response.parsed_response['account'])
     else
-      raise Tangocard::AccountCreateFailedException, "Tangocard - Error finding account: #{response.error_message}"
+      raise Tangocard::AccountCreateFailedException, "#{response.error_message}"
     end
   end
 
+  # Find account, or create if account not found.
+  # Raises Tangocard::AccountCreateFailedException on failure.
+  #
+  # Example:
+  #   >> Tangocard::Account.find_or_create('bonusly', 'test', 'dev@bonus.ly')
+  #    => #<Tangocard::Account:0x007f9a6fec0138 @customer="bonusly", @email="dev@bonus.ly", @identifier="test", @available_balance=0>
+  #
+  # Arguments:
+  #   customer: (String)
+  #   identifier: (String)
+  #   email: (String)
   def self.find_or_create(customer, identifier, email)
     begin
       find(customer, identifier)
@@ -32,7 +60,6 @@ class Tangocard::Account
     end
   end
 
-  # {"identifier"=>"test1", "email"=>"test@test.com", "customer"=>"bonusly", "available_balance"=>0}
   def initialize(params)
     @customer = params['customer']
     @email = params['email']
@@ -44,6 +71,34 @@ class Tangocard::Account
     @available_balance
   end
 
+  # Add funds to the account.
+  #
+  # Example:
+  #   >> account.fund(10000, '128.128.128.128', Hash (see example below))
+  #    => #<Tangocard::Account:0x007f9a6fec0138 @customer="bonusly", @email="dev@bonus.ly", @identifier="test", @available_balance=0>
+  #
+  # Arguments:
+  #   amount: (Integer)
+  #   client_ip: (String)
+  #   credit_card: (Hash) - see https://github.com/tangocarddev/RaaS/blob/master/fund_create.schema.json for details
+  #
+  # Credit Card Hash Example:
+  #
+  #   {
+  #       'number' => '4111111111111111',
+  #       'expiration' => '01/17',
+  #       'security_code' => '123',
+  #       'billing_address' => {
+  #           'f_name' => 'Jane',
+  #           'l_name' => 'User',
+  #           'address' => '123 Main Street',
+  #           'city' => 'Anytown',
+  #           'state' => 'NY',
+  #           'zip' => '11222',
+  #           'country' => 'USA',
+  #           'email' => 'jane@company.com'
+  #       }
+  #   }
   def fund!(amount, client_ip, credit_card)
     params = {
         'amount' => amount,

data/lib/tangocard/brand.rb

@@ -1,16 +1,43 @@
-# Documentation: https://github.com/tangocarddev/RaaS
 class Tangocard::Brand
   attr_reader :description, :rewards
 
+  # Return an array of all brands.
+  #
+  # Example:
+  #   >> Tangocard::Brand.all
+  #    => [#<Tangocard::Brand:0x007f9a6f9d3030 ...>, #<Tangocard::Brand:0x007f9a6f9d3030 ...>, ...]
+  #
+  # Arguments:
+  #   none
   def self.all
     result = Tangocard::Raas.rewards_index.parsed_response
     result['brands'].map{|p| Tangocard::Brand.new(p)}
   end
 
+  # Return an array of default brands.  Must set default_brands in your Tangocard initializer (see README).
+  #
+  # Example:
+  #   >> Tangocard::Brand.default_brands
+  #    => [#<Tangocard::Brand:0x007f9a6f9d3030 ...>, #<Tangocard::Brand:0x007f9a6f9d3030 ...>, ...]
+  #
+  # Arguments:
+  #   none
   def self.default_brands
     self.all.select{|b| Tangocard.configuration.default_brands.include?(b.description)}
   end
 
+  # Find a brand by its :description field.
+  #
+  # Example:
+  #   >> Tangocard::Brand.find("Amazon.com")
+  #    => #<Tangocard::Brand:0x007f9a6fb076e0 @description="Amazon.com",
+  #       @image_url="http://static-integration.tangocard.com/graphics/item-images/amazon-gift-card.png",
+  #       @rewards=[#<Tangocard::Reward:0x007f9a6fb07618 @description="Amazon.com Gift Card (Custom)",
+  #       @sku="AMZN-E-V-STD", @currency_type="USD", @unit_price=-1, @available=true, @min_price=100,
+  #       @max_price=100000>]>
+  #
+  # Arguments:
+  #   brand_name: (String)
   def self.find(brand_name)
     self.all.select{|b| b.description == brand_name}.first
   end
@@ -21,19 +48,54 @@ class Tangocard::Brand
     @rewards = params['rewards'].map{|p| Tangocard::Reward.new(p)}
   end
 
-  # Some brands don't have logo images provided by the API, so we do this.
+  # Return the image_url for the brand.  For some brands, there is no image_url. You can set :local_images in your
+  # Tangocard initializer to provide a local image for a specified brand.  See the README for details.
+  #
+  # Example:
+  #   >> amazon_brand.image_url
+  #    => "http://static-integration.tangocard.com/graphics/item-images/amazon-gift-card.png"
+  #
+  # Arguments:
+  #   none
   def image_url
     Tangocard.configuration.local_images[description] || @image_url
   end
 
+  # Return the rewards that are purchasable given a balance (in cents).
+  #
+  # Example:
+  #   >> itunes_brand.purchasable_rewards(1000)
+  #    => [#<Tangocard::Reward:0x007f9a6fd29810 @description="iTunes Gift Card $10", @sku="APPL-E-1000-STD",
+  #        @currency_type="USD", @unit_price=1000, @available=true, @min_price=0, @max_price=0>]
+  #
+  # Arguments:
+  #   balance_in_cents: (Integer)
   def purchasable_rewards(balance_in_cents)
     rewards.select{|r| r.purchasable?(balance_in_cents) && !Tangocard.configuration.sku_blacklist.include?(r.sku)}
   end
 
+  # True if there are any purchasable rewards given a balance in cents, false otherwise.
+  #
+  # Example:
+  #   >> itunes_brand.has_purchasable_rewards?(1000)
+  #    => true
+  #
+  # Arguments:
+  #   balance_in_cents: (Integer)
   def has_purchasable_rewards?(balance_in_cents)
     purchasable_rewards(balance_in_cents).any?
   end
 
+  # True if this is a brand with variable-price rewards.
+  #
+  # Example:
+  #   >> itunes_brand.variable_price?
+  #    => false
+  #   >> amazon_brand.variable_price?
+  #    => true
+  #
+  # Arguments:
+  #   none
   def variable_price?
     rewards.select{|r| r.variable_price? }.any?
   end

data/lib/tangocard/order.rb

@@ -1,5 +1,3 @@
-# Wrapper for Tangocard RaaS Order
-# https://github.com/tangocarddev/RaaS#order-resources
 class Tangocard::Order
   attr_reader :order_id,
               :account_identifier,
@@ -13,29 +11,14 @@ class Tangocard::Order
 
   private_class_method :new
 
-  #{
-  #    "success"=>true,
-  #    "order"=> {
-  #        "order_id"=>"113-08258652-15",
-  #        "account_identifier"=>"ElliottTest",
-  #        "customer"=>"ElliottTest",
-  #        "sku"=>"APPL-E-1500-STD",
-  #        "amount"=>1500,
-  #        "reward_message"=>"testing",
-  #        "reward_subject"=>"RaaS Sandbox Test",
-  #        "reward_from"=>"Elliott",
-  #        "delivered_at"=>"2013-08-15T17:42:18+00:00",
-  #        "recipient"=> {
-  #            "name"=>"Elliott",
-  #            "email"=>"elliott@tangocard.com"
-  #        },
-  #        "reward"=> {
-  #            "token"=>"520d12fa655b54.34581245",
-  #            "number"=>"1111111111111256"
-  #        }
-  #    }
-  #}
-
+  # Return an array of all orders.
+  #
+  # Example:
+  #   >> Tangocard::Order.all
+  #    => [#<Tangocard::Order:0x007f9a6c4bca68 ...>, #<Tangocard::Order:0x007f9a6c4bca68 ...>, ...]
+  #
+  # Arguments:
+  #   params: (Hash - optional, see https://github.com/tangocarddev/RaaS#retrieve-a-list-of-historical-orders for details)
   def self.all(params = {})
     response = Tangocard::Raas.orders_index(params)
     if response.success?
@@ -45,15 +28,31 @@ class Tangocard::Order
     end
   end
 
+  # Find an order by order_id. Raises Tangocard::OrderNotFoundException on failure.
+  #
+  # Example:
+  #   >> Tangocard::Order.find("113-08258652-15")
+  #    => #<Tangocard::Order:0x007f9a6e3a90c0 @order_id="113-08258652-15", @account_identifier="ElliottTest", @customer="ElliottTest", @sku="APPL-E-1500-STD", @amount=1500, @reward_message="testing", @reward_subject="RaaS Sandbox Test", @reward_from="Elliott", @delivered_at="2013-08-15T17:42:18+00:00", @recipient={"name"=>"Elliott", "email"=>"elliott@tangocard.com"}, @reward={"token"=>"520d12fa655b54.34581245", "number"=>"1111111111111256"}>
+  #
+  # Arguments:
+  #   order_id: (String)
   def self.find(order_id)
     response = Tangocard::Raas.show_order({'order_id' => order_id})
     if response.success?
       new(response.parsed_response['order'])
     else
-      raise Tangocard::OrderNotFoundException, "Order (#{order_id}) not found. Error message: #{response.error_message}"
+      raise Tangocard::OrderNotFoundException, "#{response.error_message}"
     end
   end
 
+  # Create a new order. Raises Tangocard::OrderCreateFailedException on failure.
+  #
+  # Example:
+  #   >> Tangocard::Order.create(params)
+  #    => #<Tangocard::Order:0x007f9a6c4bca68 ...>
+  #
+  # Arguments:
+  #   params: (Hash - see https://github.com/tangocarddev/RaaS#place-an-order for details)
   def self.create(params)
     response = Tangocard::Raas.create_order(params)
     if response.success?

data/lib/tangocard/raas.rb

@@ -1,35 +1,87 @@
-# Documentation: https://github.com/tangocarddev/RaaS
 class Tangocard::Raas
   include HTTParty
   base_uri Tangocard.configuration.base_uri
 
-  # https://github.com/tangocarddev/RaaS/blob/master/account_create.schema.json
+  # Create a new account. Returns Tangocard::Response object.
+  #
+  # Example:
+  #   >> Tangocard::Raas.create_account(params)
+  #    => #<Tangocard::Response:0x007f9a6c4bca68 ...>
+  #
+  # Arguments:
+  #   params: (Hash - see https://github.com/tangocarddev/RaaS#create-a-new-platform-account for details)
   def self.create_account(params)
     Tangocard::Response.new(post('/raas/v1/accounts', {:body => params.to_json}.merge(basic_auth_param)))
   end
 
+  # Gets account details. Returns Tangocard::Response object.
+  #
+  # Example:
+  #   >> Tangocard::Raas.show_account(params)
+  #    => #<Tangocard::Response:0x007f9a6c4bca68 ...>
+  #
+  # Arguments:
+  #   params: (Hash - see https://github.com/tangocarddev/RaaS#get-the-information-for-a-specific-platform-account for details)
   def self.show_account(params)
     Tangocard::Response.new(get("/raas/v1/accounts/#{params['customer']}/#{params['identifier']}", basic_auth_param))
   end
 
-  # https://github.com/tangocarddev/RaaS/blob/master/fund_create.schema.json
+  # Funds an account. Returns Tangocard::Response object.
+  #
+  # Example:
+  #   >> Tangocard::Raas.fund_account(params)
+  #    => #<Tangocard::Response:0x007f9a6c4bca68 ...>
+  #
+  # Arguments:
+  #   params: (Hash - see https://github.com/tangocarddev/RaaS#fund-a-platforms-account for details)
   def self.fund_account(params)
     Tangocard::Response.new(post('/raas/v1/funds', {:body => params.to_json}.merge(basic_auth_param)))
   end
 
+  # Retrieve all rewards. Returns Tangocard::Response object.
+  #
+  # Example:
+  #   >> Tangocard::Raas.rewards_index
+  #    => #<Tangocard::Response:0x007f9a6c4bca68 ...>
+  #
+  # Arguments:
+  #   none
   def self.rewards_index
     Tangocard::Response.new(get('/raas/v1/rewards', basic_auth_param))
   end
 
-  # https://github.com/tangocarddev/RaaS/blob/master/order_create.schema.json
+  # Create an order. Returns Tangocard::Response object.
+  #
+  # Example:
+  #   >> Tangocard::Raas.create_order(params)
+  #    => #<Tangocard::Response:0x007f9a6c4bca68 ...>
+  #
+  # Arguments:
+  #   params: (Hash - see https://github.com/tangocarddev/RaaS#place-an-order for details)
   def self.create_order(params)
     Tangocard::Response.new(post('/raas/v1/orders', {:body => params.to_json}.merge(basic_auth_param)))
   end
 
+  # Get order details. Returns Tangocard::Response object.
+  #
+  # Example:
+  #   >> Tangocard::Raas.show_order(params)
+  #    => #<Tangocard::Response:0x007f9a6c4bca68 ...>
+  #
+  # Arguments:
+  #   params: (Hash - see https://github.com/tangocarddev/RaaS#retrieve-a-historical-order for details)
   def self.show_order(params)
     Tangocard::Response.new(get("/raas/v1/orders/#{params['order_id']}", basic_auth_param))
   end
 
+  # Retrieve a list of historical orders. Returns Tangocard::Response object.
+  #
+  # Example:
+  #   >> Tangocard::Raas.orders_index
+  #    => #<Tangocard::Response:0x007f9a6c4bca68 ...>
+  #
+  # Arguments:
+  #   params: (Hash - see https://github.com/tangocarddev/RaaS#retrieve-a-list-of-historical-orders for details)
   def self.orders_index(params = {})
     query_string = ""
     if params.any?

data/lib/tangocard/response.rb

@@ -1,5 +1,3 @@
-# Tangocard RaaS Response Wrapper
-# https://github.com/tangocarddev/RaaS#responses
 class Tangocard::Response
   attr_reader :raw_response
 

data/lib/tangocard/reward.rb

@@ -1,4 +1,3 @@
-# Documentation: https://github.com/tangocarddev/RaaS
 class Tangocard::Reward
   attr_reader :description, :sku, :currency_type, :unit_price, :available, :min_price, :max_price
 
@@ -12,10 +11,28 @@ class Tangocard::Reward
     @max_price = params['max_price'].to_i
   end
 
+  # Is this a variable-priced reward?
+  #
+  # Example:
+  #   >> reward.variable_price?
+  #    => true # reward is variable-priced
+  #
+  # Arguments:
+  #   none
   def variable_price?
     self.unit_price == -1
   end
 
+  # Is this reward purchasable given a certain number of cents available to purchase it?
+  # True if reward is available and user has enough cents
+  # False if reward is unavailable OR user doesn't have enough cents
+  #
+  # Example:
+  #   >> reward.purchasable?(500)
+  #    => true # reward is available and costs <= 500 cents
+  #
+  # Arguments:
+  #   balance_in_cents: (Integer)
   def purchasable?(balance_in_cents)
     return false unless available
 
@@ -26,9 +43,17 @@ class Tangocard::Reward
     end
   end
 
-  def price_in_usd(field_name)
+  # Converts price in cents for given field to Money object using currency_type
+  #
+  # Example:
+  #   >> reward.to_money(:unit_price)
+  #    => #<Money fractional:5000 currency:USD>
+  #
+  # Arguments:
+  #   field_name: (Symbol - must be :min_price, :max_price, or :unit_price)
+  def to_money(field_name)
     return nil unless [:min_price, :max_price, :unit_price].include?(field_name)
 
-    Money.new(self.send(field_name), "USD")
+    Money.new(self.send(field_name), currency_type)
   end
 end

data/lib/tangocard/version.rb

@@ -1,3 +1,3 @@
 module Tangocard
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tangocard
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Raphael Crawford-Marks
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-09-17 00:00:00.000000000 Z
+date: 2013-09-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -89,7 +89,7 @@ files:
 - lib/tangocard.rb
 - MIT-LICENSE
 - Rakefile
-- README.rdoc
+- README.md
 homepage: http://bonus.ly
 licenses: []
 metadata: {}

data/README.rdoc

@@ -1,10 +0,0 @@
-= Tangocard
-
-Ruby Wrapper for Tango Card RaaS API.
-
-Tango Card provides a RaaS API for developers (https://github.com/tangocarddev/RaaS). This gem provides commonsense Ruby
-objects to wrap the JSON endpoints of the RaaS API.
-
-This project is developed and maintained by Smartly, Inc. - makers of http://bonus.ly.
-
-This project uses the MIT-LICENSE.