gocardless 1.9.0 → 1.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ed8ff8ba2e1109b3ec370bd8c52e2d1f2dc0ae70
-  data.tar.gz: 4321b58cabecafefbf4a5257ae6ee6e218d49364
+  metadata.gz: d3541d1c3a98b1d8812387e1122381ccf061648d
+  data.tar.gz: d1280282fed2de29f439389679a27165dbef197e
 SHA512:
-  metadata.gz: f8594375ca0b9ea638fedf5d2fc4ef137b81b791e2248307277eb4459e941b1606abd49f53e86a4829acd2fd3f09d72ca5a3fd5dbaadda148784d65df24d6a0e
-  data.tar.gz: c92b6f3708f2595533dcc368f904fbd83593f8eabf7059b8b9955cfe5bb964792335e584fd129da8b150773f1c0e9a317e70948a374974682ec12c69d23bd214
+  metadata.gz: c4238571659011a414b4ec82b8dab479c9f4bc2274ffd9f6de010e28dad76f34356d7a41be4fe49bb3b354d4a3a8818cff35bb21618c30799b9b42a53763fbec
+  data.tar.gz: 4fe530f0bf5531541366cae496bcc8d613abca06e638b11f10d36e3aaba00ce0d2ec7246a6b3aa811a0581a8b494dedc7016f9c92737b1195d17c05858084b7e

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 1.10.0 - June 02, 2014
+
+- Add alias methods for boolean attributes
+- Update resources with new attributes
+- Remove any nil values before sending params to GC
+- Support charge_customer_at on bill creation
+- Make depedency specifier less strict
+- Add pagination
+
+
 ## 1.9.0 - May 23, 2014
 
 - Add ability to refund bills

data/README.md

@@ -3,10 +3,7 @@
 The GoCardless Ruby client provides a simple Ruby interface to the GoCardless
 API.
 
-If you want to use the library as an individual merchant, refer to the
-[merchant guide](https://gocardless.com/docs/ruby/merchant_client_guide). If
-you want to support multiple merchant accounts, see the
-[partner guide](https://gocardless.com/docs/ruby/partner_client_guide).
+API documentation, usage guides, and setup information can be found at [developer.gocardless.com](https://developer.gocardless.com/ruby/).
 
 The full API reference is available at on
 [rubydoc.info](http://rubydoc.info/github/gocardless/gocardless-ruby/master/frames).

data/lib/gocardless.rb

@@ -7,7 +7,6 @@ module GoCardless
   require 'gocardless/pre_authorization'
   require 'gocardless/user'
   require 'gocardless/bill'
-  require 'gocardless/payment'
   require 'gocardless/merchant'
   require 'gocardless/client'
   require 'gocardless/payout'

data/lib/gocardless/bill.rb

@@ -5,20 +5,29 @@ module GoCardless
     creatable
 
     attr_accessor :amount,
-                  :source_type,
+                  :currency,
                   :description,
                   :name,
-                  :plan_id,
                   :status,
                   :gocardless_fees,
-                  :partner_fees
+                  :partner_fees,
+                  :amount_minus_fees,
+                  :can_be_retried,
+                  :can_be_cancelled,
+                  :is_setup_fee
 
     # @attribute source_id
     # @return [String] the ID of the bill's source (eg subscription, pre_authorization)
     attr_accessor :source_id
+    attr_accessor :source_type
 
-    reference_accessor :merchant_id, :user_id, :payment_id, :payout_id
-    date_accessor :created_at, :paid_at
+    reference_accessor :merchant_id, :user_id, :payout_id
+    date_accessor :created_at, :paid_at, :charge_customer_at
+
+    # Alias getter methods
+    alias_method :is_setup_fee?, :is_setup_fee
+    alias_method :can_be_cancelled?, :can_be_cancelled
+    alias_method :can_be_retried?, :can_be_retried
 
     def source
       klass = GoCardless.const_get(Utils.camelize(source_type.to_s))
@@ -47,7 +56,7 @@ module GoCardless
 
     # The ability to refund a payment is disabled by default.
     #
-    # Please contact help@gocardless.com if you require access to 
+    # Please contact help@gocardless.com if you require access to
     # the refunds API endpoint.
     def refund!
       path = self.class.endpoint.gsub(':id', id.to_s) + '/refund'
@@ -55,14 +64,17 @@ module GoCardless
     end
 
     def save
-      save_data({
-        :bill => {
-          :pre_authorization_id => self.source_id,
-          :amount => self.amount,
-          :name => self.name,
-          :description => self.description,
-        }
-      })
+      bill_params = {
+        :pre_authorization_id => self.source_id,
+        :amount => self.amount,
+        :name => self.name,
+        :description => self.description,
+        :charge_customer_at => self.charge_customer_at,
+      }
+
+      bill_params.delete_if { |_,v| v.nil? }
+
+      save_data({ :bill => bill_params })
       self
     end
 

data/lib/gocardless/client.rb

@@ -117,7 +117,7 @@ module GoCardless
     # @param [Hash] params query string parameters
     # @return [Hash] hash the parsed response data
     def api_get(path, params = {})
-      request(:get, "#{API_PATH}#{path}", :params => params).parsed
+      api_request(:get, path, :params => params).parsed
     end
 
     # Issue a POST request to the API server
@@ -127,7 +127,7 @@ module GoCardless
     # @param [Hash] data a hash of data that will be sent as the request body
     # @return [Hash] hash the parsed response data
     def api_post(path, data = {})
-      request(:post, "#{API_PATH}#{path}", :data => data).parsed
+      api_request(:post, path, :data => data).parsed
     end
 
     # Issue a PUT request to the API server
@@ -137,7 +137,7 @@ module GoCardless
     # @param [Hash] data a hash of data that will be sent as the request body
     # @return [Hash] hash the parsed response data
     def api_put(path, data = {})
-      request(:put, "#{API_PATH}#{path}", :data => data).parsed
+      api_request(:put, path, :data => data).parsed
     end
 
     # Issue a DELETE request to the API server
@@ -147,7 +147,18 @@ module GoCardless
     # @param [Hash] data a hash of data that will be sent as the request body
     # @return [Hash] hash the parsed response data
     def api_delete(path, data = {})
-      request(:delete, "#{API_PATH}#{path}", :data => data).parsed
+      api_request(:delete, path, :data => data).parsed
+    end
+
+
+    # Issue a request to the API server, returning the full response
+    #
+    # @note this method is for internal use
+    # @param [Symbol] method the HTTP method to use (e.g. +:get+, +:post+)
+    # @param [String] path the path that will be added to the API prefix
+    # @option [Hash] opts additional request options (e.g. form data, params)
+    def api_request(method, path, opts = {})
+      request(method, "#{API_PATH}#{path}", opts)
     end
 
     # @method merchant
@@ -185,13 +196,6 @@ module GoCardless
       Bill.find_with_client(self, id)
     end
 
-    # @method payment(id)
-    # @param [String] id of the payment
-    # @return [Payment] the payment matching the id requested
-    def payment(id)
-      Payment.find_with_client(self, id)
-    end
-
     # Create a new bill under a given pre-authorization
     # @see PreAuthorization#create_bill
     #
@@ -239,7 +243,7 @@ module GoCardless
     end
 
     # Confirm a newly-created subscription, pre-authorzation or one-off
-    # payment. This method also checks that the resource response data includes
+    # bill. This method also checks that the resource response data includes
     # a valid signature and will raise a {SignatureError} if the signature is
     # invalid.
     #

data/lib/gocardless/merchant.rb

@@ -11,6 +11,7 @@ module GoCardless
                   :pending_balance,
                   :next_payout_amount,
                   :hide_variable_amount
+
     date_accessor :created_at, :next_payout_date
   end
 end

data/lib/gocardless/page.rb

@@ -0,0 +1,43 @@
+module GoCardless
+  class Page
+    include Enumerable
+
+    def initialize(resource_class, data, links)
+      @resource_class = resource_class
+      @data = data
+      @links = links
+    end
+
+    # The next page number, nil if there is no next page
+    def next_page
+      @links['next']
+    end
+
+    # The previous page number, nil if there is no previous page
+    def previous_page
+      @links['previous']
+    end
+
+    # The first page number, nil if this is the first page
+    def first_page
+      @links['first']
+    end
+
+    # The last page number, nil if this is the last page
+    def last_page
+      @links['last']
+    end
+
+    # Used for page iteration
+    def has_next?
+      !!@links['next']
+    end
+
+    # Yield each of the items in the page as instances of the resource class
+    def each(&block)
+      @data.each do |attrs|
+        yield @resource_class.new(attrs)
+      end
+    end
+  end
+end

data/lib/gocardless/paginator.rb

@@ -0,0 +1,86 @@
+require 'multi_json'
+require 'gocardless/page'
+
+module GoCardless
+  class Paginator
+    include Enumerable
+
+    attr_reader :num_records
+    attr_reader :num_pages
+
+    DEFAULT_PAGE_NUMBER = 1
+    DEFAULT_PAGE_SIZE   = 30
+
+    def initialize(client, resource_class, path, query)
+      @client = client
+      @resource_class = resource_class
+      @path, @query = path, query
+      @page_number, @per_page = DEFAULT_PAGE_NUMBER, DEFAULT_PAGE_SIZE
+    end
+
+    # Set the number of records per page (page size), if an argument is
+    # provided. Returns the current per_page value, whether an argument is
+    # provided or not.
+    def per_page(results_per_page = nil)
+      if results_per_page
+        @num_records, @num_pages = nil, nil
+        @per_page = results_per_page
+        self
+      else
+        @per_page
+      end
+    end
+
+    # Fetch and return a single page.
+    def load_page(page_num)
+      params = @query.merge(pagination_params(page_num))
+      response = @client.api_request(:get, @path, :params => params)
+
+      metadata = parse_metadata(response)
+      @num_records, @num_pages = metadata['records'], metadata['pages']
+
+      Page.new(@resource_class, response.parsed, metadata['links'])
+    end
+
+    alias_method :page, :load_page
+
+    # Yield every record from every current page, auto-fetching new pages as
+    # the iteration happens. Records are returned as instances of the
+    # appropriate resource classes (e.g. Subscription).
+    def each(&block)
+      each_page { |page| page.each(&block) }
+    end
+
+    # Fetch and yield each page of results.
+    def each_page
+      page_obj = load_page(1)
+      loop do
+        yield page_obj
+        break unless page_obj.has_next?
+        page_obj = load_page(page_obj.next_page)
+      end
+    end
+
+    # Return the total number of records. May trigger an HTTP request.
+    def count
+      load_page(1) if @num_records.nil?  # load pagination metadata
+      @num_records
+    end
+
+    # Return the total number of pages. May trigger an HTTP request.
+    def page_count
+      load_page(1) if @num_records.nil?  # load pagination metadata
+      @num_pages
+    end
+
+    private
+
+    def pagination_params(page_num)
+      { :page => page_num, :per_page => @per_page }
+    end
+
+    def parse_metadata(response)
+      MultiJson.load(response.headers['X-Pagination'])
+    end
+  end
+end

data/lib/gocardless/pre_authorization.rb

@@ -9,9 +9,9 @@ module GoCardless
                   :interval_unit,
                   :name,
                   :description,
-                  :plan_id,
                   :status,
-                  :remaining_amount
+                  :remaining_amount,
+                  :setup_fee
 
     reference_accessor :merchant_id, :user_id
 

data/lib/gocardless/resource.rb

@@ -1,4 +1,5 @@
 require 'date'
+require 'gocardless/paginator'
 
 module GoCardless
   class Resource
@@ -18,18 +19,7 @@ module GoCardless
         path = uri.path.sub(%r{^/api/v\d+}, '')
 
         # Modify the instance's metaclass to add the method
-        metaclass = class << self; self; end
-        metaclass.send(:define_method, name) do |*args|
-          # 'name' will be something like 'bills', convert it to Bill and
-          # look up the resource class with that name
-          class_name = Utils.camelize(Utils.singularize(name.to_s))
-          klass = GoCardless.const_get(class_name)
-          query = default_query.merge(args.first || {})
-          client.api_get(path, query).map do |attrs|
-            # Convert the results to instances of the looked-up class
-            klass.new_with_client(client, attrs)
-          end
-        end
+        define_paginated_resource_method(name, path, default_query)
       end
 
       # Set resource attribute values
@@ -182,5 +172,21 @@ module GoCardless
       response = client.send("api_#{method}", path, data)
       response.each { |key,val| send("#{key}=", val) if respond_to?("#{key}=") } if response.is_a? Hash
     end
+
+    def define_paginated_resource_method(name, path, default_query)
+      metaclass = class << self; self; end
+      metaclass.send(:define_method, name) do |*args|
+        # 'name' will be something like 'bills', convert it to Bill and
+        # look up the resource class with that name
+        class_name = Utils.camelize(Utils.singularize(name.to_s))
+        klass = GoCardless.const_get(class_name)
+
+        # merge the default query, which may have been included in the
+        # sub_resource_uri, with the query params provided by the user
+        query = default_query.merge(args.first || {})
+
+        Paginator.new(client, self, path, query)
+      end
+    end
   end
 end

data/lib/gocardless/subscription.rb

@@ -9,17 +9,13 @@ module GoCardless
                    :interval_unit,
                    :name,
                    :description,
-                   :plan_id,
                    :status,
-                   :setup_fee,
-                   :trial_length,
-                   :trial_unit
+                   :setup_fee
 
     reference_accessor :merchant_id, :user_id
 
     date_accessor :start_at, :expires_at, :created_at, :next_interval_start
 
-
     def cancel!
       path = self.class.endpoint.gsub(':id', id.to_s) + '/cancel'
       client.api_put(path)

data/lib/gocardless/user.rb

@@ -2,7 +2,12 @@ module GoCardless
   class User < Resource
     self.endpoint = '/users/:id'
 
-    attr_accessor :name, :first_name, :last_name, :email
+    attr_accessor :name,
+                  :first_name,
+                  :last_name,
+                  :company_name,
+                  :email
+
     date_accessor :created_at
 
     def name

data/lib/gocardless/version.rb

@@ -1,3 +1,3 @@
 module GoCardless
-  VERSION = '1.9.0'.freeze
+  VERSION = '1.10.0'.freeze
 end

data/spec/bill_spec.rb

@@ -1,96 +1,46 @@
 require 'spec_helper'
 
 describe GoCardless::Bill do
-  before :each do
-    @app_id = 'abc'
-    @app_secret = 'xyz'
-    GoCardless.account_details = {:app_id => @app_id, :app_secret => @app_secret,
-                                  :token  => 'xxx', :merchant_id => '1'}
-    @client = GoCardless.client
+  before do
+    GoCardless.account_details = {:app_id => 'abc', :app_secret => 'xyz',
+                                  :token  => 'xxx', :merchant_id => '123'}
   end
+  let(:client) { GoCardless.client }
+  let(:bill) { GoCardless::Bill.new(:id => 123) }
 
   it "source getter works" do
-    b = GoCardless::Bill.new(:source_type => :subscription, :source_id => 123)
-    @client.access_token = 'TOKEN'
-    @client.merchant_id = '123'
-    stub_get(@client, :id => 123)
-    source = b.source
+    bill.source_id = 123
+    bill.source_type = :subscription
+    stub_get(client, :id => 123)
+    source = bill.source
     source.should be_a GoCardless::Subscription
     source.id.should == 123
   end
 
   it "source setter works" do
-    b = GoCardless::Bill.new
-    b.source = GoCardless::Subscription.new(:id => 123)
-    b.source_id.should == 123
-    b.source_type.should.to_s == 'subscription'
+    bill.source = GoCardless::Subscription.new(:id => 123)
+    bill.source_id.should == 123
+    bill.source_type.should.to_s == 'subscription'
   end
 
   it "should be able to be retried" do
-    b = GoCardless::Bill.new(:id => 123)
-    @client.should_receive(:api_post).with('/bills/123/retry')
-    b.retry!
+    client.should_receive(:api_post).with('/bills/123/retry')
+    bill.retry!
   end
 
   it "should be able to be cancelled" do
-    b = GoCardless::Bill.new(:id => 123)
-    @client.should_receive(:api_put).with('/bills/123/cancel')
-    b.cancel!
+    client.should_receive(:api_put).with('/bills/123/cancel')
+    bill.cancel!
   end
 
   it "should be able to be refunded" do
-    b = GoCardless::Bill.new(:id => 123)
-    @client.should_receive(:api_post).with('/bills/123/refund')
-    b.refund!
+    client.should_receive(:api_post).with('/bills/123/refund')
+    bill.refund!
   end
 
-  describe "pending query method" do
-    it "and_return true when the subscription status is pending" do
-      GoCardless::Bill.new(:status => 'pending').pending?.should be_true
-    end
-
-    it "and_return false otherwise" do
-      GoCardless::Bill.new.pending?.should be_false
-    end
-  end
-
-  describe "paid query method" do
-    it "and_return true when the subscription status is paid" do
-      GoCardless::Bill.new(:status => 'paid').paid?.should be_true
-    end
-
-    it "and_return false otherwise" do
-      GoCardless::Bill.new.paid?.should be_false
-    end
-  end
-
-  describe "failed query method" do
-    it "and_return true when the subscription status is failed" do
-      GoCardless::Bill.new(:status => 'failed').failed?.should be_true
-    end
-
-    it "and_return false otherwise" do
-      GoCardless::Bill.new.failed?.should be_false
-    end
-  end
-
-  describe "withdrawn query method" do
-    it "and_return true when the subscription status is withdrawn" do
-      GoCardless::Bill.new(:status => 'withdrawn').withdrawn?.should be_true
-    end
-
-    it "and_return false otherwise" do
-      GoCardless::Bill.new.withdrawn?.should be_false
-    end
-  end
-
-  describe "refunded query method" do
-    it "and_return true when the subscription status is refunded" do
-      GoCardless::Bill.new(:status => 'refunded').refunded?.should be_true
-    end
-
-    it "and_return false otherwise" do
-      GoCardless::Bill.new.refunded?.should be_false
-    end
-  end
+  it_behaves_like "it has a query method for", "pending"
+  it_behaves_like "it has a query method for", "paid"
+  it_behaves_like "it has a query method for", "failed"
+  it_behaves_like "it has a query method for", "withdrawn"
+  it_behaves_like "it has a query method for", "refunded"
 end