recurly 0.1.4 → 0.2.0

data/README.md

@@ -16,13 +16,14 @@ Installation
 
 This library can be installed as a gem or a plugin. Your choice.
 
-**Gem Installation:**
+**Rails3 Bundle Integration:**
 
-    gem install recurly --source=http://gemcutter.org
-    
-**Plugin Installation:**
+    gem "recurly", :git => "http://github.com/railsjedi/recurly-client-ruby.git"
 
-    script/plugin install git@github.com:recurly/recurly-client-ruby.git
+
+**Plugin Installation (not recommended):**
+
+    script/plugin install http://github.com/railsjedi/recurly-client-ruby.git
 
 
 Authentication
@@ -35,6 +36,7 @@ Create a file in your Rails app at __/config/initializers/recurly_config.rb__ wi
     Recurly.configure do |c|
       c.username = 'api@yourcompany.com'
       c.password = 'super_secret_password'
+      c.site = 'https://my-recurly-site.recurly.com'
     end
 
 
@@ -43,13 +45,57 @@ Demo Application
 
 [Recurly Ruby Demo App](http://github.com/recurly/recurly-client-ruby-demo)
 
+
 Examples
 --------
 
-All the functionality is demonstrated by the unit tests in the __test__ directory.
+All the functionality is demonstrated by the tests in the __spec__ directory.
+
+
+Running the Specs
+------------------
+
+Recurly gem uses RSpec2 for testing. It also uses VCR / Webmock to handle fast and repeatable full integration tests with the API.
+
+The way this works is when each spec is first run, it will save each HTTP request generated within the spec/vcr folder. Subsequent http requests will be mocked using the data contained in these YML files.
+
+The first thing to do is install bundler if you don't already have it:
+
+    gem install bundler
+
+The next thing is to setup all the spec dependencies
+
+    bundle
+
+When first running the specs, you'll need to setup a recurly test account. Use the provided rake task to walk you through creating spec/spec_settings.yml with all the authentication info.
+
+    rake recurly:setup
+
+Now when you run `rake` it will hit recurly's api to run all the specs. Subsequent calls will no longer hit the API (and be run locally).
+
+
+Something go Wrong?
+------------------
+
+You can view the full http interactions with Recurly at spec/vcr. Please attached these to any bug reports so we can replicate.
+
+
+Clearing Test Data
+------------------
+
+You can delete the spec/vcr folder at any time, and it will regenerate the requests to recurly's apis. However if you do this, you'll also need to clear the test data on your recurly account. Here's how (manually):
+
+* Login to Recurly
+* Click "Configuration"" on the top right menu
+* Select "Clear Test Data"
+
+This is also automated via a rake task. It will delete the spec/vcr files, and clear the data for you on the server (using your spec_settings.yml authentication info).
+
+    rake recurly:clear
+
 
 
 API Documentation
 -----------------
 
-Please see the [Recurly API](http://support.recurly.com/faqs/api/) for more information.
+Please see the [Recurly API](http://docs.recurly.com/api/basics) for more information.

data/lib/recurly/account.rb

@@ -1,17 +1,70 @@
 module Recurly
   class Account < RecurlyBase
     self.element_name = "account"
-    
+    self.primary_key = :account_code
+
+    # Maps the
+    SHOW_PARAMS = {
+      :active => "active_subscribers",
+      :pastdue => "pastdue_subscribers",
+      :free => "non_subscribers"
+    }
+
+    # Lists all accounts (with optional filter)
+    #
+    # examples:
+    #   Account.list(:all) #=> returns all accounts
+    #   Account.list(:active) #=> returns active accounts
+    #   Account.list(:pastdue) #=> returns pastdue accounts
+    #   Account.list(:free) #=> returns the free accounts
+    #
+    def self.list(status = :all)
+      opts = {}
+      if status && status != :all
+        opts[:params] = {:show => SHOW_PARAMS[status] || status}
+      end
+      find(:all, opts)
+    end
+
     def close_account
       destroy
     end
-    
-    def primary_key
-      self.account_code
+
+    def charges
+      Charge.list(account_code)
+    end
+    memoize :charges
+
+    def lookup_charge(id)
+      Charge.lookup(account_code, id)
+    end
+
+    def credits
+      Credit.list(account_code)
+    end
+    memoize :credits
+
+    def lookup_credit(id)
+      Credit.lookup(account_code, id)
+    end
+
+    def transactions(status)
+      Transaction.list(account_code, status)
+    end
+    memoize :transactions
+
+    def lookup_transaction(id)
+      Transaction.lookup(account_code, id)
+    end
+
+    def invoices
+      Invoice.list(account_code)
     end
-    
-    def to_param
-      self.account_code
+    memoize :invoices
+
+    def lookup_invoice(id)
+      Invoice.lookup(account_code, id)
     end
+
   end
 end

data/lib/recurly/base.rb

@@ -1,14 +1,24 @@
-require "rubygems"
-require "active_resource"
+require 'active_support/memoizable'
+
+module Recurly
+  class RecurlyBase < ActiveResource::Base
+    extend ActiveSupport::Memoizable
+
+    self.format = Recurly::Formats::XmlWithPaginationFormat.new
+
+    # Add User-Agent to headers
+    def headers
+      super
+      @headers['User-Agent'] = "Recurly Ruby Client v#{VERSION}"
+      @headers
+    end
 
-# See http://github.com/rails/rails/commit/1488c6cc9e6237ce794e3c4a6201627b9fd4ca09
-# Errors in Rails 2.3.4 are not parsed correctly.
-module ActiveResource
-  class Base
     def update_only
       false
     end
-    
+
+    # See http://github.com/rails/rails/commit/1488c6cc9e6237ce794e3c4a6201627b9fd4ca09
+    # Errors in Rails 2.3.4 are not parsed correctly.
     def save
       if update_only
         update
@@ -16,7 +26,7 @@ module ActiveResource
         save_without_validation
       end
       true
-    rescue ResourceInvalid => error
+    rescue ActiveResource::ResourceInvalid => error
       case error.response['Content-Type']
       when /application\/xml/
         errors.from_xml(error.response.body)
@@ -25,52 +35,59 @@ module ActiveResource
       end
       false
     end
-  end
-end
 
-module Recurly
-  
-  VERSION = '0.1.3'
-  
-  class << self
-    attr_accessor :username, :password, :site
-    
-    def configure
-      yield self
-      
-      RecurlyBase.user = username
-      RecurlyBase.password = password
-      RecurlyBase.site = site || "https://app.recurly.com"
-      true
+    # patch persisted? so it looks to see if it actually is persisted
+    def persisted?
+      @persisted ||= false
+      @persisted
     end
-  end
-  
-  class RecurlyBase < ActiveResource::Base
-    
-    # Add User-Agent to headers
-    def headers
+
+    # patch new? to be the opposite of persisted
+    def new?
+      !persisted?
+    end
+
+    # patch load_attributes_from_response so it marks result records as persisted
+    def load_attributes_from_response(response)
       super
-      @headers['User-Agent'] = "Recurly Ruby Client v#{VERSION}"
-      @headers
+      @persisted = true
+    end
+
+    # patch instantiate_record so it marks result records as persisted
+    def self.instantiate_record(record, prefix_options)
+      result = super
+      result.instance_eval{ @persisted = true }
+      result
     end
   end
-  
+
   # ActiveRecord treats resources as plural by default.  Some resources are singular.
-  class RecurlySingularResourceBase < RecurlyBase
-    
+  class RecurlyAccountBase < RecurlyBase
+    self.prefix = "/accounts/:account_code/"
+
     # Override element_path because this is a singular resource
     def self.element_path(id, prefix_options = {}, query_options = nil)
       prefix_options, query_options = split_options(prefix_options) if query_options.nil?
-      # original: "#{prefix(prefix_options)}#{collection_name}/#{id}.#{format.extension}#{query_string(query_options)}"
-      "#{prefix(prefix_options)}#{CGI::escape(id || '')}/#{element_name}.#{format.extension}#{query_string(query_options)}"
+      prefix_options.merge!(:account_code => id) if id
+      # original: "#{prefix(prefix_options)}#{collection_name}/#{URI.escape id.to_s}.#{format.extension}#{query_string(query_options)}"
+      "#{prefix(prefix_options)}#{element_name}.#{format.extension}#{query_string(query_options)}"
     end
-    
+
+    # element path
+    def element_path(options = nil)
+      self.class.element_path(to_param, options || prefix_options)
+    end
+
+    def to_param
+      attributes[:account_code]
+    end
+
     # Override collection_path because this is a singular resource
-    def self.collection_path(prefix_options = {}, query_options = nil) 
-      prefix_options, query_options = split_options(prefix_options) if query_options.nil? 
-      # original: "#{prefix(prefix_options)}#{collection_name}.#{format.extension}#{query_string(query_options)}" 
-      "#{prefix(prefix_options)}/#{element_name}.#{format.extension}#{query_string(query_options)}"
+    def self.collection_path(prefix_options = {}, query_options = nil)
+      prefix_options, query_options = split_options(prefix_options) if query_options.nil?
+      # original: "#{prefix(prefix_options)}#{collection_name}.#{format.extension}#{query_string(query_options)}"
+      "#{prefix(prefix_options)}#{element_name}.#{format.extension}#{query_string(query_options)}"
     end
-    
+
   end
 end

data/lib/recurly/billing_info.rb

@@ -1,8 +1,7 @@
 module Recurly
-  class BillingInfo < RecurlySingularResourceBase
+  class BillingInfo < RecurlyAccountBase
     self.element_name = "billing_info"
-    self.prefix = "/accounts/:account_code"
-    
+
     def update_only
       true
     end

data/lib/recurly/charge.rb

@@ -2,9 +2,14 @@ module Recurly
   class Charge < RecurlyBase
     self.element_name = "charge"
     self.prefix = "/accounts/:account_code/"
-  
+
     def self.list(account_code)
-      Charge.find(:all, :params => { :account_code => account_code })
+      find(:all, :params => { :account_code => account_code })
     end
+
+    def self.lookup(account_code, id)
+      find(id, :params => { :account_code => account_code })
+    end
+
   end
 end

data/lib/recurly/credit.rb

@@ -2,9 +2,14 @@ module Recurly
   class Credit < RecurlyBase
     self.element_name = "credit"
     self.prefix = "/accounts/:account_code/"
-  
+
     def self.list(account_code)
-      Credit.find(:all, :params => { :account_code => account_code })
+      find(:all, :params => { :account_code => account_code })
     end
+
+    def self.lookup(account_code, id)
+      find(id, :params => { :account_code => account_code })
+    end
+
   end
 end

data/lib/recurly/formats/xml_with_pagination.rb

@@ -0,0 +1,38 @@
+module Recurly
+  module Formats
+    class XmlWithPaginationFormat
+      include ActiveResource::Formats::XmlFormat
+
+      def decode(xml)
+        data = super
+
+        if data.is_a?(Hash) and data["type"] == "collection" and data["current_page"]
+          data = paginate_data(data)
+        end
+
+        data
+      end
+
+      # convert the data into a paginated resultset (array with singleton methods)
+      def paginate_data(data)
+        # find the first array and use that as the resultset (lame workaround)
+        results = data.values.select{|v| v.is_a?(Array)}.first
+
+        # use a singleton methods for now (maybe wrap in WillPaginate later?)
+        total_entries = data["total_entries"] || 0
+        def results.total_entries; total_entries; end
+
+        current_page = data["current_page"] || 1
+        def results.current_page; current_page; end
+
+        per_page = data["per_page"]
+        if per_page
+          def results.per_page; per_page; end
+        end
+
+        results
+      end
+    end
+  end
+end
+

data/lib/recurly/invoice.rb

@@ -1,9 +1,24 @@
 module Recurly
   class Invoice < RecurlyBase
     self.element_name = "invoice"
-  
+    self.prefix = "/accounts/:account_code/"
+
     def self.list(account_code)
-      Invoice.find(:all, :from => "/accounts/#{account_code}/invoices")
+      find(:all, :params => { :account_code => account_code })
     end
+
+    def self.lookup(account_code, id)
+      find(id, :params => { :account_code => account_code })
+    end
+
+    def self.element_path(id, prefix_options = {}, query_options = nil)
+      path = super
+
+      # postprocess generated element url.
+      # changes /accounts/:account_code/invoices/:id to /invoices/:id
+      # this breaks update, however I dont believe recurly allows invoice updates anyways
+      path.sub("/accounts/#{CGI::escape(prefix_options[:account_code] || '')}/invoices/", "/invoices/")
+    end
+
   end
 end

data/lib/recurly/plan.rb

@@ -2,9 +2,6 @@ module Recurly
   class Plan < RecurlyBase
     self.element_name = "plan"
     self.prefix = "/company/"
-    
-    def to_param
-      self.plan_code
-    end
+    self.primary_key = :plan_code
   end
 end

data/lib/recurly/subscription.rb

@@ -1,36 +1,35 @@
 module Recurly
-  class Subscription < RecurlySingularResourceBase
+  class Subscription < RecurlyAccountBase
     self.element_name = "subscription"
-    self.prefix = "/accounts/:account_code"
-    
+
     def self.refund(account_code, refund_type = :partial)
       raise "Refund type must be :full or :partial." unless refund_type == :full or refund_type == :partial
       Subscription.delete(nil, {:account_code => account_code, :refund => refund_type})
     end
-    
+
     # Stops the subscription from renewing. The subscription remains valid until the end of
     # the current term (current_period_ends_at).
-    def cancel (account_code)
+    def cancel(account_code)
       Subscription.delete(account_code)
     end
-    
+
     # Terminates the subscription immediately and processes a full or partial refund
     def refund(refund_type)
       raise "Refund type must be :full or :partial." unless refund_type == :full or refund_type == :partial
       Subscription.delete(nil, {:account_code => self.subscription_account_code, :refund => refund_type})
     end
-    
+
     # Valid timeframe: :now or :renewal
     # Valid options: plan_code, quantity, unit_amount
     def change(timeframe, options = {})
-      raise "Timeframe must be :full or :partial." unless timeframe == 'now' or timeframe == 'renewal'
+      raise "Timeframe must be :full or :renewal." unless timeframe == 'now' or timeframe == 'renewal'
       options[:timeframe] = timeframe
       path = "/accounts/#{CGI::escape(self.subscription_account_code || '')}/subscription.xml"
-      connection.put(path, 
-        self.class.format.encode(options, :root => :subscription), 
+      connection.put(path,
+        self.class.format.encode(options, :root => :subscription),
         self.class.headers)
     end
-    
+
     def subscription_account_code
       acct_code = self.account_code if defined?(self.account_code) and !self.account_code.nil? and !self.account_code.blank?
       acct_code ||= account.account_code if defined?(account) and !account.nil?

data/lib/recurly/transaction.rb

@@ -1,6 +1,21 @@
 module Recurly
   class Transaction < RecurlyBase
     self.element_name = "transaction"
-    self.prefix = "/"  
+
+    def self.list(account_code, status = :all)
+      results = find(:all, :from => "/accounts/#{CGI::escape(account_code || '')}/transactions")
+
+      # filter by status
+      if status != :all
+        results = results.select{|t| t.status == status.to_s }
+      end
+
+      results
+    end
+
+    def self.lookup(account_code, id)
+      find(id, :params => { :account_code => account_code })
+    end
+
   end
 end

data/lib/recurly/version.rb

@@ -0,0 +1,3 @@
+module Recurly #:nodoc
+  VERSION = "0.2.0"
+end

data/lib/recurly.rb

@@ -1,11 +1,34 @@
+require 'rubygems'
 require "active_resource"
 
-require File.dirname(__FILE__) + '/recurly/base'
-require File.dirname(__FILE__) + '/recurly/account'
-require File.dirname(__FILE__) + '/recurly/billing_info'
-require File.dirname(__FILE__) + '/recurly/charge'
-require File.dirname(__FILE__) + '/recurly/credit'
-require File.dirname(__FILE__) + '/recurly/invoice'
-require File.dirname(__FILE__) + '/recurly/plan'
-require File.dirname(__FILE__) + '/recurly/subscription'
-require File.dirname(__FILE__) + '/recurly/transaction'
+require 'cgi'
+
+require 'recurly/version'
+require 'recurly/formats/xml_with_pagination'
+
+# configuration
+module Recurly
+  class << self
+    attr_accessor :username, :password, :site
+
+    def configure
+      yield self
+
+      RecurlyBase.user = username
+      RecurlyBase.password = password
+      RecurlyBase.site = site || "https://app.recurly.com"
+
+      true
+    end
+  end
+end
+
+require 'recurly/base'
+require 'recurly/account'
+require 'recurly/billing_info'
+require 'recurly/charge'
+require 'recurly/credit'
+require 'recurly/invoice'
+require 'recurly/plan'
+require 'recurly/subscription'
+require 'recurly/transaction'

data/spec/integration/account_spec.rb

@@ -0,0 +1,92 @@
+require 'spec_helper'
+
+module Recurly
+  describe Account do
+    timestamp = File.mtime(__FILE__).to_i
+
+    describe "#create" do
+      use_vcr_cassette "account/create/#{timestamp}"
+
+      before(:each) do
+        @account = Factory.create_account("account-create-#{timestamp}")
+      end
+
+      it "should have a created_at date" do
+        @account.created_at.should_not be_nil
+      end
+    end
+
+    describe "#find" do
+      use_vcr_cassette "account/find/#{timestamp}"
+      let(:orig){ Factory.create_account("account-get-#{timestamp}") }
+
+      before(:each) do
+        @account = Account.find(orig.account_code)
+      end
+
+      it "should return the account object" do
+        @account.should_not be_nil
+      end
+
+      describe "returned account" do
+        it "should have a created_at date" do
+          @account.created_at.should_not be_nil
+        end
+
+        it "should match the original account code" do
+          @account.account_code.should == orig.account_code
+        end
+
+        it "should match the original account email" do
+          @account.email.should == orig.email
+        end
+
+        it "should match the original first name" do
+          @account.first_name.should == orig.first_name
+        end
+      end
+    end
+
+    describe "#update" do
+      around(:each){ |e| VCR.use_cassette("account/update/#{timestamp}", &e) }
+
+      let(:orig){ Factory.create_account("account-update-#{timestamp}") }
+
+      before(:each) do
+        # update account data
+        @account = Account.find(orig.account_code)
+        @account.last_name = "Update Test"
+        @account.company_name = "Recurly Ruby Gem -- Update"
+        @account.save!
+
+        # refetch account
+        @account = Account.find(orig.account_code)
+      end
+
+      it "should not have updated the email address" do
+        @account.email.should == orig.email
+      end
+
+      it "should have updated the last_name" do
+        @account.last_name.should == "Update Test"
+      end
+
+      it "should have updated the company_name" do
+        @account.company_name.should == "Recurly Ruby Gem -- Update"
+      end
+    end
+
+    describe "#close_account" do
+      use_vcr_cassette "account/close/#{timestamp}"
+      let(:account){ Factory.create_account("account-close-#{timestamp}") }
+
+      before(:each) do
+        account.close_account
+      end
+
+      it "should mark the account as closed" do
+        Account.find(account.account_code).state.should == "closed"
+      end
+    end
+  end
+end