pin_up 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,15 @@
 ---
-SHA1:
-  metadata.gz: e23144942115aaf7f8c623b9c475189fe58cf374
-  data.tar.gz: a3508a238afd927a970a92c3ba9bdc89aace64bd
-SHA512:
-  metadata.gz: f66ec5b5437b7c3c69a3c772acb7ddb873f5d944aa9451957b455a984d739c1d08785fc9dc87179f8ab013644692cc181759e53fa874c5d0c34c6087e9692d85
-  data.tar.gz: 6f4f7a090b63d00af62bb83d838a13153b916bcea92a704b38ffc0d42c8799d3c9860deaa793baa4cef2ab54deb7f7dfc51102ff4ed6c2d450bb69bb21bad2bb
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    MzFmZTFlNTIxOWExMjAyNjFlN2RhZmFjMDU1ZTFjYjQzMmU4YTgyMQ==
+  data.tar.gz: !binary |-
+    OTYzYTQwYzZhZWE5MDljNTg4OGU0ZDljOTVkZWZlOWUyYjUxMzcyNA==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    OWYwMTZjNmRjNjhlYjA4NTY2ZTY5MTkzMDNjYzlhNjk3ZWNlM2Q3MzZlMzFh
+    NWJkZmQxYTkyMmZiYzkzNzM1YzhhNzk4NTBhOWY3NTQzYWMyYmY3MWMxNzA4
+    ZDhlZmIwMzU2ZTVkYWI2ZDRmZDM3MzNhM2E0MGU3MWI5MjIzMWI=
+  data.tar.gz: !binary |-
+    NzYyNzk2YjIxMjMwODFhMDM4NTczOGU5NDFjYzYzM2NiZjVkZjg5OTU5ZDAz
+    MjE5YzkyMmMxZDkwMjZiMzY5MzI3NDMxMjc3NzY1ODJjNzAyYmVmZjEwMjRl
+    Yzc0ZDgxMTZhNTAxYTViMDhlYzMzYzExMWM2ZTVlMzYwNGI2ZjI=

data/README.md

@@ -1,8 +1,117 @@
-= pin_up
+## pin_up
 
-Description goes here.
+A Ruby gem wrapper for the pin-payments (pin.net.au) API, all of it.
 
-== Contributing to pin_up
+Support for Ruby 1.9.x & Ruby 2.0.0
+
+## Installation
+
+    gem install pin_up
+
+or add:
+
+    gem 'pin_up'
+
+to your Gemfile.
+
+## Usage
+
+If using rails add an initializer to your app:
+
+    Pin::Base.new("your key")
+
+An option second paramater can be passed in to set the environment (:live or :test). The default is :live.
+
+### Charges
+##### List All Charges
+    Pin::Charges.all
+##### Find A Charge
+    Pin::Charges.find("token")
+##### Search For A Charge
+    Pin::Charges.search({query: "foo", end_date: "Mar 25, 2013"})
+
+See https://pin.net.au/docs/api/charges#search-charges for a full list of options.
+
+##### Create A Charge
+    charge = {email: "email@example.com", description: "Description", amount: "400", currency: "AUD", ip_address: "127.0.0.1", customer_token: "cus_token"   }
+
+    Pin::Charges.create(charge)
+
+### Customers
+##### List All Customers
+    Pin::Customer.all
+##### Find A Customer
+    Pin::Customer.find('token')
+##### List Charges For A Customer
+    Pin::Customer.charges('cus_token')
+##### Create A Customer
+    Pin::Customer.create(email, hash_of_customer_details)
+
+    customer_details = {number: '5520000000000000', expiry_month: "12", expiry_year: "2014", cvc: "123", name: 'Roland Robot', address_line1: '123 fake street', address_city: 'Melbourne', address_postcode: '1234', address_state: 'Vic', address_country: 'Australia'}
+
+    Pin::Customer.create('email@example.com', customer_details)
+
+##### Update A Customer
+###### Update Card details
+---
+    Pin::Customer.update('cus_token', hash_of_details)
+
+If passing a hash of details, it must be the full list of details of the credit card to be stored. (https://pin.net.au/docs/api/customers#put-customer)
+
+###### Update only an email
+---
+
+    hash_of_details = {email: 'new_email@example.com'}
+    Pin::Customer.update('cus_token', hash_of_details)
+
+###### Update card by token
+---
+
+    hash_of_details = {card_token: 'new_card_token'}
+    Pin::Customer.update('cus_token', hash_of_details)
+
+##### Creat A Customer Given a Card Token and Email
+
+    card_details = {number: "5520000000000000", expiry_month: "12", expiry_year: "2018", cvc: "123", name: "Roland TestRobot", address_line1: "123 Fake Road", address_line2: "", address_city: "Melbourne", address_postcode: "1223", address_state: "Vic", address_country: "AU"}
+
+    card = Pin::Card.create(card_details)
+    Pin::Customer.create('email@example.com',card['token'])
+
+## Refunds
+
+##### Find A Refund
+
+    Pin::Refund.find('charge_token')
+
+This will list all refunds for a particular charge (will return an empty hash if nothing is found)
+
+##### Create A Refund Specifying An Amount
+
+    Pin::Refund.create('charge_token', '400')
+
+##### Create A Refund For Entire Charge Amount
+
+    Pin::Refund.create('charge_token')
+
+## Cards
+
+##### Create A Card Without Pins Form
+
+    card_details = {number: "5520000000000000", expiry_month: "12", expiry_year: "2018", cvc: "123", name: "Roland Robot", address_line1: "123 Fake Road", address_line2: "", address_city: "Melbourne", address_postcode: "1223", address_state: "Vic", address_country: "AU"}
+
+    Pin::Card.create(card_details)
+
+Will return a card_token that can be stored against a customer.
+
+Only use this method if you're comfortable sending card details to your server - otherwise you can use a form that Pin provides (https://pin.net.au/docs/guides/payment-forms) and get the card_token that way.
+
+## Todo
+
+  * Validate a response before it gets sent to Pin (eg. Update customer)
+  * Pagination
+  # Better error handling (for 4** responses)
+
+## Contributing to pin_up
 
 * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
 * Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
@@ -12,8 +121,7 @@ Description goes here.
 * Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
 * Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
 
-== Copyright
+## Copyright
 
 Copyright (c) 2013 Daniel Nitsikopoulos. See LICENSE.txt for
-further details.
-
+further details.

data/Rakefile

@@ -23,8 +23,6 @@ Jeweler::Tasks.new do |gem|
   gem.authors = ["Daniel Nitsikopoulos"]
   # dependencies defined in Gemfile
   gem.add_dependency "httparty"
-  gem.add_development_dependency "webmock"
-  gem.add_development_dependency "vcr"
 end
 Jeweler::RubygemsDotOrgTasks.new
 

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.2.0

data/lib/pin_up/base.rb

@@ -1,8 +1,16 @@
 module Pin
+  ##
+  # This class sets up a few things like the base URL and provides a few utility methods to be shared between classes.
   class Base
     include HTTParty
 
-    def initialize(key: "", env: :live)
+    ##
+    # Create a new Pin instance
+    # Args:
+    #  key: Your Pin secret key
+    #  env: The environment you want to use. Leave blank for live and pass in :test for test
+    # An error is raised if an invalid env is passed in.
+    def initialize(key = "", env = :live)
       @key = key
       env = env.to_sym
       @@auth = {username: key, password: ''}
@@ -15,32 +23,47 @@ module Pin
       end
     end
 
+    ##
+    # Provides access to your key if needed
     def key
       @key
     end
 
+    ##
+    # Provides access to the base URL if needed
     def uri
       @@base_url
     end
 
     protected
 
-    def self.auth_get(url, token: nil)
+    ##
+    # Sends an authorised GET request to pins server
+    # args: url (eg: 'charges' or 'charges/token')
+    def self.auth_get(url, token = nil)
       HTTParty.get("#{@@base_url}#{url}", basic_auth: @@auth)
     end
 
+    ##
+    # Sends an authorised POST request to pins server
     def self.auth_post(url, options = {})
       HTTParty.post("#{@@base_url}#{url}", body: options, basic_auth: @@auth)
     end
 
+    ##
+    # Sends an authorised PUT request to pins server
     def self.auth_put(url, options = {})
       HTTParty.put("#{@@base_url}#{url}", body: options, basic_auth: @@auth)
     end
 
+    ##
+    # Builds a response of a single object
     def self.build_response(response)
       response.parsed_response['response']
     end
 
+    ##
+    # Builds a response of a collection if the response code is 200 otherwise an empty array is returned
     def self.build_collection_response(response)
       models = []
       if response.code == 200

data/lib/pin_up/card.rb

@@ -1,6 +1,16 @@
 module Pin
+  ##
+  # This class models Pin's Cards API
   class Card < Base
 
+    ##
+    # creates a card given a hash of options
+    # https://pin.net.au/docs/api/cards
+    # Only use if you have a secure server connection, if in doubt use
+    # the form example provided by Pin to create a card_token
+    # https://pin.net.au/docs/guides/payment-forms
+    # args: card_details (Hash)
+    # returns: card object
     def self.create(options)
       build_response(auth_post('cards', options))
     end

data/lib/pin_up/charge.rb

@@ -1,13 +1,28 @@
 module Pin
+  ##
+  # This class models Pin's Charges API
   class Charges < Base
+    ##
+    # Lists all of the charges for your account
+    # returns: a collection of charge objects
+    # https://pin.net.au/docs/api/charges#get-charges
     def self.all
       build_response(auth_get('charges'))
     end
 
+    ##
+    # Find a charge for your account given a token
+    # args: token (String)
+    # returns: a charge object
+    # https://pin.net.au/docs/api/charges#get-charge
     def self.find(token)
       build_response(auth_get("charges/#{token}"))
     end
 
+    # Find a charge(s) for your account given a search term or set of terms
+    # args: options (Hash)
+    # returns: a collection of charge objects
+    # https://pin.net.au/docs/api/charges#search-charges
     def self.search(options = {})
       term = ""
       options.each do |key, option|
@@ -16,6 +31,10 @@ module Pin
       build_response(auth_get("charges/search?#{term}"))
     end
 
+    # Create a charge given charge details and a card, a card_token or acustomer_token
+    # args: options (Hash)
+    # returns: a charge object
+    # https://pin.net.au/docs/api/charges#post-charges
     def self.create(options = {})
       build_response(auth_post("charges", options))
     end

data/lib/pin_up/customer.rb

@@ -1,10 +1,21 @@
 module Pin
+  ##
+  # This class models Pins Customers API
   class Customer < Base
 
+    ##
+    # Lists all customers for your account
+    # returns: a collection of customer objects
+    # https://pin.net.au/docs/api/customers#get-customers
     def self.all
       build_collection_response(auth_get('customers'))
     end
 
+    ##
+    # Create a customer given customer details and a card OR a card_token
+    # args: email(String), card (Hash)
+    # returns: a customer object
+    # https://pin.net.au/docs/api/customers#post-customers
     def self.create(email, card)
       options = if card.respond_to?(:to_hash)
         {card: card.to_hash}
@@ -15,14 +26,30 @@ module Pin
       build_response(auth_post('customers', options))
     end
 
+    ##
+    # Find a customer for your account given a token
+    # args: token (String)
+    # returns: a customer object
+    # https://pin.net.au/docs/api/customers#get-customers
     def self.find(token)
       build_response(auth_get("customers/#{token}"))
     end
 
+    ##
+    # Update a customer for your account given a token and any of: email, card (hash),card_token
+    # args: token (String), options (Hash)
+    # returns: a customer object
+    # https://pin.net.au/docs/api/customers#put-customer
+    # NB: When providing a card (hash), you need to specify the full list of details.
     def self.update(token, options = {})
       build_response(auth_put("customers/#{token}", options))
     end
 
+    ##
+    # Get a list of charges for a customer
+    # args: token (String)
+    # returns: a collection of charge objects
+    # https://pin.net.au/docs/api/customers#get-customers-charges
     def self.charges(token)
       build_collection_response(auth_get("customers/#{token}/charges"))
     end

data/lib/pin_up/refund.rb

@@ -1,10 +1,23 @@
 module Pin
+  ##
+  # This class models Pin's Charges API
   class Refund < Base
 
+    ##
+    # Find a refund by charge token
+    # returns: a collection of refund objects
+    # args: token (String)
+    # https://pin.net.au/docs/api/refunds#get-refunds
     def self.find(token)
       build_collection_response(auth_get("charges/#{token}/refunds"))
     end
 
+    ##
+    # Create a refund for a charge
+    # args: token (String), amount (String - optional)
+    # returns: a refund object
+    # if no amount is passed in, the full amount of the charge will be refunded
+    # https://pin.net.au/docs/api/refunds#post-refunds
     def self.create(token, amount = nil)
       options = {amount: amount}
       build_response(auth_post("charges/#{token}/refunds", options))

data/pin_up.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "pin_up"
-  s.version = "0.1.0"
+  s.version = "0.2.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Daniel Nitsikopoulos"]
-  s.date = "2013-07-05"
+  s.date = "2013-07-06"
   s.description = "A Ruby gem wrapper for the pin-payments (pin.net.au) API"
   s.email = "dnitza@gmail.com"
   s.extra_rdoc_files = [
@@ -61,7 +61,7 @@ Gem::Specification.new do |s|
   s.homepage = "http://github.com/dNitza/pin_up"
   s.licenses = ["MIT"]
   s.require_paths = ["lib"]
-  s.rubygems_version = "2.0.3"
+  s.rubygems_version = "2.0.2"
   s.summary = "A Ruby gem wrapper for the pin-payments (pin.net.au) API"
 
   if s.respond_to? :specification_version then
@@ -77,8 +77,6 @@ Gem::Specification.new do |s|
       s.add_development_dependency(%q<webmock>, [">= 0"])
       s.add_development_dependency(%q<vcr>, [">= 0"])
       s.add_runtime_dependency(%q<httparty>, [">= 0"])
-      s.add_development_dependency(%q<webmock>, [">= 0"])
-      s.add_development_dependency(%q<vcr>, [">= 0"])
     else
       s.add_dependency(%q<shoulda>, [">= 0"])
       s.add_dependency(%q<rdoc>, ["~> 3.12"])
@@ -89,8 +87,6 @@ Gem::Specification.new do |s|
       s.add_dependency(%q<webmock>, [">= 0"])
       s.add_dependency(%q<vcr>, [">= 0"])
       s.add_dependency(%q<httparty>, [">= 0"])
-      s.add_dependency(%q<webmock>, [">= 0"])
-      s.add_dependency(%q<vcr>, [">= 0"])
     end
   else
     s.add_dependency(%q<shoulda>, [">= 0"])
@@ -102,8 +98,6 @@ Gem::Specification.new do |s|
     s.add_dependency(%q<webmock>, [">= 0"])
     s.add_dependency(%q<vcr>, [">= 0"])
     s.add_dependency(%q<httparty>, [">= 0"])
-    s.add_dependency(%q<webmock>, [">= 0"])
-    s.add_dependency(%q<vcr>, [">= 0"])
   end
 end
 

data/spec/base_spec.rb

@@ -2,16 +2,16 @@ require 'spec_helper'
 
 describe "Base", :vcr, class: Pin::Base do
   before(:each) do
-    @test_pin = Pin::Base.new(key: "W_VrFld7oc9BnC4pOdQxmw", env: :test)
+    @test_pin = Pin::Base.new("W_VrFld7oc9BnC4pOdQxmw", :test)
   end
 
   it "should set key correctly"  do
-    @pin = Pin::Base.new(key: "KEY", env: :live)
+    @pin = Pin::Base.new("KEY", :live)
     expect(@pin.key).to eq "KEY"
   end
 
   it "should set environment to live if no env set" do
-    @pin = Pin::Base.new(key: "KEY", env: :live)
+    @pin = Pin::Base.new("KEY", :live)
     expect(@pin.uri).to eq "https://api.pin.net.au/1/"
   end
 
@@ -20,7 +20,7 @@ describe "Base", :vcr, class: Pin::Base do
   end
 
   it "should raise an error if anything other than '' :live or :test is passed to a new instance" do
-    expect{Pin::Base.new(key: "KEY", env: :foo)}.to raise_error(RuntimeError, "'env' option must be :live or :test. Leave blank for live payments")
+    expect{Pin::Base.new("KEY", :foo)}.to raise_error(RuntimeError, "'env' option must be :live or :test. Leave blank for live payments")
   end
 
   it "should list succesfully connect to Pin" do

data/spec/cards_spec.rb

@@ -2,7 +2,7 @@ require 'spec_helper'
 
 describe "Card", :vcr, class: Pin::Card do
   before(:each) do
-    Pin::Base.new(key: "W_VrFld7oc9BnC4pOdQxmw", env: :test)
+    Pin::Base.new("W_VrFld7oc9BnC4pOdQxmw", :test)
   end
 
   it "should create a card and respond with the card detail from pin" do

data/spec/charges_spec.rb

@@ -2,7 +2,7 @@ require 'spec_helper'
 
 describe "Charge", :vcr, class: Pin::Charges do
   before(:each) do
-    Pin::Base.new(key: "W_VrFld7oc9BnC4pOdQxmw", env: :test)
+    Pin::Base.new("W_VrFld7oc9BnC4pOdQxmw", :test)
   end
 
   it "should list charges in Pin" do

data/spec/customers_spec.rb

@@ -3,7 +3,7 @@ require 'spec_helper'
 
 describe "Customer", :vcr, class: Pin::Customer do
   before(:each) do
-    Pin::Base.new(key: "W_VrFld7oc9BnC4pOdQxmw", env: :test)
+    Pin::Base.new("W_VrFld7oc9BnC4pOdQxmw", :test)
   end
 
   it "should list customers" do

data/spec/refund_spec.rb

@@ -3,7 +3,7 @@ require 'spec_helper'
 
 describe "Refund", :vcr, class: Pin::Refund do
   before(:each) do
-    Pin::Base.new(key: "W_VrFld7oc9BnC4pOdQxmw", env: :test)
+    Pin::Base.new("W_VrFld7oc9BnC4pOdQxmw", :test)
   end
 
   it "should list all refunds made to a charge given a token" do

metadata

@@ -1,27 +1,27 @@
 --- !ruby/object:Gem::Specification
 name: pin_up
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Daniel Nitsikopoulos
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-07-05 00:00:00.000000000 Z
+date: 2013-07-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: shoulda
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
@@ -42,28 +42,28 @@ dependencies:
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: httparty
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
@@ -84,84 +84,56 @@ dependencies:
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: webmock
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: vcr
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: httparty
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: webmock
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: vcr
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
 description: A Ruby gem wrapper for the pin-payments (pin.net.au) API
@@ -222,17 +194,17 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.3
+rubygems_version: 2.0.2
 signing_key: 
 specification_version: 4
 summary: A Ruby gem wrapper for the pin-payments (pin.net.au) API