exchequer 0.1.0

data/Gemfile

@@ -0,0 +1,5 @@
+source :rubygems
+
+gemspec
+
+gem 'rake'

data/LICENCE

@@ -0,0 +1,20 @@
+Copyright (c) 2012-2013 Pat Allan
+
+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.textile

@@ -0,0 +1,74 @@
+h1. Exchequer
+
+A collection of helpful classes for a clean, object-oriented approach to dealing with Chargify.
+
+h2. Installation
+
+<pre><code>gem install exchequer</code></pre>
+
+h2. Usage
+
+This library currently comes with three classes: Card, Biller and ErrorMapper.
+
+h3. Card
+
+Card objects represent a Chargify credit card. It's built to be used in Rails forms, and has all the essential card attributes (first and last name, number, cvv, expiration month and year) plus billing address details (address, city, state, zip and country). This means you don't need to add misleading attribute accessors to your own models. At a basic level, it's much like any other ActiveModel object: you initialise it with a set of parameters (perhaps via @params@), and it responds to @#errors@.
+
+<pre><code>card = Exchequer::Card.new(
+  :first_name       => 'John',
+  :last_name        => 'Smith',
+  :full_number      => '1234567812345678',
+  :cvv              => '123',
+  :expiration_month => '10',
+  :expiration_year  => '2016',
+  :billing_address  => '1 Main Road',
+  :billing_city     => 'Melbourne',
+  :billing_state    => 'Victoria',
+  :billing_zip      => '3000',
+  :billing_country  => 'Australia'
+)</code></pre>
+
+It also provides a useful helper method @#to_hash@, which is useful if you want to feed it in to a Chargify::Subscription object's @credit_card_attributes@. The hash returned is much like what was passed in when initializing in the above example, except it always uses string keys.
+
+h3. Biller
+
+This is the most complicated piece of code - but it's nothing too tricky. It looks after the creation of Chargify customers and subscribers. You initialise it by passing through a Card object and some options - all of which are required: an email address for the customer, a unique reference for the customer, and the handle for the product the subscription is being applied to.
+
+<pre><code>biller = Exchequer::Biller.new card,
+  :email          => 'john@smith.com',
+  :reference      => 'customer-123',
+  :product_handle => 'default-subscription'</code></pre>
+
+When the biller object is created, you can then call @#charge@, which takes care of the communication with Chargify. It'll return true if everything is successful, but otherwise false - and will populate the card with any errors Chargify provides.
+
+It's worth noting that the customer's first and last name will be taken from the card object. Customising that may be an option in a later release.
+
+Once that's done, you can then call @#subscription_id@ to get the unique identifier for the subscription. It's probably worth storing that somewhere so you can interact with the subscription again at a later point.
+
+<pre><code>if biller.charged
+  customer.subscription_id = biller.subscription_id
+  customer.save
+else
+  # Use card.errors to determine why the subscription or customer could not
+  # be saved.
+end</code></pre>
+
+h3. ErrorMapper
+
+This has been built as an internal class for transferring errors from one ActiveModel object to another, with a few translations to shift errors on @:base@ to the appropriate attributes (eg: messages starting with 'Credit card number' are attached to the :full_number attribute). So, it's built with Card objects in mind, but if you find your own uses for it, wonderful.
+
+<pre><code>Exchequer::ErrorMapper.map(subscription, :to => card)</code></pre>
+
+h3. Putting it all together
+
+The last code example within the Biller details above should give you a good idea on how this library's expected to be used....
+
+h2. Contributing
+
+Patches are certainly welcome - though it's a good idea to contact me (either via email or through the GitHub issues on this project) to discuss what your planned changes are if they're beyond bug fixes. I want this project to reflect a clear and focused approach for dealing with Chargify (and possibly other payment gateways), and so I don't want people wasting their time on patches that I would consider inappropriate for that purpose.
+
+Yes, it's opinionated - but there's nothing stopping you from forking this code, modifying it, and using your version in whatever way you see fit.
+
+h2. Licence
+
+Copyright (c) 2012-2013, Exchequer is developed and maintained by Pat Allan, and is released under the open MIT Licence.

data/Rakefile

@@ -0,0 +1,9 @@
+require 'bundler'
+
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new
+
+task :default => :spec

data/exchequer.gemspec

@@ -0,0 +1,18 @@
+# -*- encoding: utf-8 -*-
+Gem::Specification.new do |s|
+  s.name          = 'exchequer'
+  s.version       = '0.1.0'
+  s.authors       = ['Pat Allan']
+  s.email         = ['pat@freelancing-gods.com']
+  s.homepage      = 'https://github.com/pat/exchequer'
+  s.summary       = 'Chargify Workflow Toolbox'
+  s.description   = 'An Object-Oriented approach to working with Chargify in Ruby'
+
+  s.files         = `git ls-files`.split("\n")
+  s.require_paths = ['lib']
+
+  s.add_runtime_dependency 'chargify_api_ares', '> 0'
+  s.add_runtime_dependency 'activemodel',       '> 0'
+
+  s.add_development_dependency 'rspec', '>= 2.11.0'
+end

data/lib/exchequer.rb

@@ -0,0 +1,7 @@
+module Exchequer
+  #
+end
+
+require 'exchequer/biller'
+require 'exchequer/card'
+require 'exchequer/error_mapper'

data/lib/exchequer/biller.rb

@@ -0,0 +1,46 @@
+class Exchequer::Biller
+  def initialize(card, options = {})
+    @card    = card
+    @options = options
+  end
+
+  def charge
+    map_errors_from(customer)     and return false if customer.id.nil?
+    map_errors_from(subscription) and return false if !subscription.save
+
+    true
+  end
+
+  def subscription_id
+    subscription.id
+  end
+
+  private
+
+  attr_reader :card, :options
+
+  def customer
+    @customer ||= begin
+      Chargify::Customer.find_by_reference(options[:reference])
+    rescue ActiveResource::ResourceNotFound
+      Chargify::Customer.create(
+        :first_name   => card.first_name,
+        :last_name    => card.last_name,
+        :email        => options[:email],
+        :reference    => options[:reference]
+      )
+    end
+  end
+
+  def map_errors_from(object)
+    Exchequer::ErrorMapper.map object, :to => card
+  end
+
+  def subscription
+    @subscription ||= Chargify::Subscription.new(
+      :customer_id            => customer.id,
+      :product_handle         => options[:product_handle],
+      :credit_card_attributes => card.to_hash
+    )
+  end
+end

data/lib/exchequer/card.rb

@@ -0,0 +1,32 @@
+class Exchequer::Card
+   attr_accessor :first_name, :last_name, :full_number, :cvv,
+    :expiration_month, :expiration_year, :billing_address, :billing_city,
+    :billing_state, :billing_zip, :billing_country
+
+  def initialize(params = {})
+    params ||= {}
+    params.keys.each do |key|
+      send "#{key}=", params[key]
+    end
+  end
+
+  def errors
+    @errors ||= ActiveModel::Errors.new(self)
+  end
+
+  def to_hash
+    {
+      'first_name'       => first_name,
+      'last_name'        => last_name,
+      'full_number'      => full_number,
+      'cvv'              => cvv,
+      'expiration_month' => expiration_month,
+      'expiration_year'  => expiration_year,
+      'billing_address'  => billing_address,
+      'billing_city'     => billing_city,
+      'billing_state'    => billing_state,
+      'billing_zip'      => billing_zip,
+      'billing_country'  => billing_country
+    }
+  end
+end

data/lib/exchequer/error_mapper.rb

@@ -0,0 +1,33 @@
+class Exchequer::ErrorMapper
+  MAPPINGS = {
+    'Credit card expiration year'  => :expiration_year,
+    'Credit card expiration month' => :expiration_month,
+    'Credit card number'           => :full_number,
+    'First name'                   => :first_name,
+    'Last name'                    => :last_name
+  }
+
+  def self.map(source, arguments)
+    new(source, arguments[:to]).map_errors
+  end
+
+  def initialize(source, destination)
+    @source, @destination = source, destination
+  end
+
+  def map_errors
+    source.errors[:base].dup.each do |error|
+      label = MAPPINGS.keys.detect { |key| error[/^#{key}:/] }
+
+      if label
+        destination.errors[MAPPINGS[label]] << error.gsub(/^#{label}:\s+/, '')
+      else
+        destination.errors[:base] << error
+      end
+    end
+  end
+
+  private
+
+  attr_reader :source, :destination
+end

data/spec/exchequer/biller_spec.rb

@@ -0,0 +1,96 @@
+require 'active_resource/exceptions'
+require './lib/exchequer'
+
+describe Exchequer::Biller do
+  let(:biller)       { Exchequer::Biller.new card,
+    :reference => 'my-unique-key', :email => 'me@domain.com',
+    :product_handle => 'standard-product' }
+  let(:card)         { double(:first_name => 'John', :last_name => 'Smith',
+    :to_hash => double) }
+  let(:customer)     { double(:id => 5234) }
+  let(:subscription) { double(:save => true) }
+
+  describe '#charge' do
+    before :each do
+      stub_const 'Chargify::Customer', double(:find_by_reference => customer)
+      stub_const 'Chargify::Subscription', double(:new => subscription)
+      stub_const 'Exchequer::ErrorMapper', double(:map => true)
+    end
+
+    it "uses an existing company for the given reference" do
+      Chargify::Customer.should_receive(:find_by_reference).
+        with('my-unique-key').and_return(customer)
+
+      biller.charge
+    end
+
+    it "creates a new company with the reference if necessary" do
+      Chargify::Customer.stub(:find_by_reference).
+        and_raise(ActiveResource::ResourceNotFound.new(''))
+
+      Chargify::Customer.should_receive(:create).with(
+        :first_name => 'John',
+        :last_name  => 'Smith',
+        :email      => 'me@domain.com',
+        :reference  => 'my-unique-key'
+      ).and_return(customer)
+
+      biller.charge
+    end
+
+    it "creates a new subscription" do
+      Chargify::Subscription.should_receive(:new).with(
+        :customer_id            => 5234,
+        :product_handle         => 'standard-product',
+        :credit_card_attributes => card.to_hash
+      ).and_return(subscription)
+      subscription.should_receive(:save)
+
+      biller.charge
+    end
+
+    it "returns true" do
+      biller.charge.should be_true
+    end
+
+    context 'customer cannot be saved' do
+      before :each do
+        customer.stub :id => nil
+      end
+
+      it "maps customer errors to the card" do
+        Exchequer::ErrorMapper.should_receive(:map).
+          with(customer, :to => card).and_return(true)
+
+        biller.charge
+      end
+
+      it "does not save a subscription" do
+        subscription.should_not_receive(:save)
+
+        biller.charge
+      end
+
+      it "returns false" do
+        biller.charge.should be_false
+      end
+    end
+
+    context 'subscription cannot be saved' do
+      before :each do
+        subscription.stub :save => false
+      end
+
+      it "maps the subscription errors to the card" do
+        Exchequer::ErrorMapper.should_receive(:map).
+          with(subscription, :to => card).and_return(true)
+
+        biller.charge
+      end
+
+      it "returns false" do
+        biller.charge.should be_false
+      end
+    end
+  end
+end

data/spec/exchequer/error_mapper_spec.rb

@@ -0,0 +1,73 @@
+require './lib/exchequer'
+
+describe Exchequer::ErrorMapper do
+  def errors_hash
+    Hash.new { |hash, key| hash[key] = [] }
+  end
+
+  let(:map_errors)  { Exchequer::ErrorMapper.map(source, :to => destination) }
+  let(:source)      { double(:errors => errors_hash) }
+  let(:destination) { double(:errors => errors_hash) }
+
+  describe '#map_errors' do
+    it "transfers credit card expiration year attributes" do
+      source.errors[:base] << 'Credit card expiration year: Not valid'
+
+      map_errors
+
+      destination.errors.should == {
+        :expiration_year => ['Not valid']
+      }
+    end
+
+    it "transfers credit card expiration month attributes" do
+      source.errors[:base] << 'Credit card expiration month: Not valid'
+
+      map_errors
+
+      destination.errors.should == {
+        :expiration_month => ['Not valid']
+      }
+    end
+
+    it "transfers credit card number attributes" do
+      source.errors[:base] << 'Credit card number: Not valid'
+
+      map_errors
+
+      destination.errors.should == {
+        :full_number => ['Not valid']
+      }
+    end
+
+    it "transfers first name attributes" do
+      source.errors[:base] << 'First name: Not valid'
+
+      map_errors
+
+      destination.errors.should == {
+        :first_name => ['Not valid']
+      }
+    end
+
+    it "transfers last name attributes" do
+      source.errors[:base] << 'Last name: Not valid'
+
+      map_errors
+
+      destination.errors.should == {
+        :last_name => ['Not valid']
+      }
+    end
+
+    it "transfers other errors to base" do
+      source.errors[:base] << 'Gateway error'
+
+      map_errors
+
+      destination.errors.should == {
+        :base => ['Gateway error']
+      }
+    end
+  end
+end

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification
+name: exchequer
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Pat Allan
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-01-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: chargify_api_ares
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>'
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>'
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>'
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>'
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 2.11.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 2.11.0
+description: An Object-Oriented approach to working with Chargify in Ruby
+email:
+- pat@freelancing-gods.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENCE
+- README.textile
+- Rakefile
+- exchequer.gemspec
+- lib/exchequer.rb
+- lib/exchequer/biller.rb
+- lib/exchequer/card.rb
+- lib/exchequer/error_mapper.rb
+- spec/exchequer/biller_spec.rb
+- spec/exchequer/error_mapper_spec.rb
+homepage: https://github.com/pat/exchequer
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: Chargify Workflow Toolbox
+test_files: []
+has_rdoc: