recurly 0.4.16 → 2.0.0

data/lib/recurly/resource/pager.rb

@@ -0,0 +1,210 @@
+module Recurly
+  class Resource
+    # Pages through an index resource, yielding records as it goes. It's rare
+    # to instantiate one on its own: use {Resource.paginate},
+    # {Resource.find_each}, and <tt>Resource#{has_many_association}</tt>
+    # instead.
+    #
+    # Because pagers handle +has_many+ associations, pagers can also build and
+    # create child records.
+    #
+    # @example Through a resource class:
+    #   Recurly::Account.paginate # => #<Recurly::Resource::Pager...>
+    #
+    #   Recurly::Account.find_each { |a| p a }
+    # @example Through an resource instance:
+    #   account.transactions
+    #   # => #<Recurly::Resource::Pager...>
+    #
+    #   account.transactions.new(attributes) # or #create, or #create!
+    #   # => #<Recurly::Transaction ...>
+    class Pager
+      include Enumerable
+
+      # @return [Resource] The resource class of the pager.
+      attr_reader :resource_class
+
+      # @return [Hash, nil] A hash of links to which the pager can page.
+      attr_reader :links
+
+      # @return [String, nil] An ETag for the current page.
+      attr_reader :etag
+
+      # A pager for paginating through resource records.
+      #
+      # @param resource_class [Resource] The resource to be paginated.
+      # @param options [Hash] A hash of pagination options.
+      # @option options [Integer] :per_page The number of records returned per
+      #   page.
+      # @option options [DateTime, Time, Integer] :cursor A timestamp that the
+      #   pager will skim back to and return records created before it.
+      # @option options [String] :etag When set, will raise {API::NotModified}
+      #   if the loaded page content has not changed.
+      # @option options [String] :uri The default location the pager will
+      #   request.
+      # @raise [API::NotModified] If the <tt>:etag</tt> option is set and
+      #   matches the server's.
+      def initialize resource_class, options = {}
+        options[:cursor] &&= options[:cursor].to_i
+        @parent = options.delete :parent
+        @uri    = options.delete :uri
+        @etag   = options.delete :etag
+        @resource_class, @options = resource_class, options
+        @collection = @count = nil
+      end
+
+      # @return [String] The URI of the paginated resource.
+      def uri
+        @uri ||= resource_class.collection_path
+      end
+
+      # @return [Integer] The total record count of the resource in question.
+      # @see Resource.count
+      def count
+        @count ||= API.head(uri, @options)['X-Records'].to_i
+      end
+
+      # @return [Array] Iterates through the current page of records.
+      # @yield [record]
+      def each
+        return enum_for :each unless block_given?
+        load! unless @collection
+        @collection.each { |record| yield record }
+      end
+
+      # @return [nil]
+      # @see Resource.find_each
+      # @yield [record]
+      def find_each
+        return enum_for :find_each unless block_given?
+        begin
+          each { |record| yield record }
+        end while self.next
+      end
+
+      # @return [Array, nil] Refreshes the pager's collection of records with
+      #   the next page.
+      def next
+        load_from links['next'], nil if links.key? 'next'
+      end
+
+      # @return [Array, nil] Refreshes the pager's collection of records with
+      #   the first page.
+      def start
+        load_from links['start'], nil if links.key? 'start'
+      end
+
+      # @return [Array, nil] Load (or reload) the pager's collection from the
+      #   original, supplied options.
+      def load!
+        load_from uri, @options
+      end
+      alias reload load!
+
+      # @return [Pager] Duplicates the pager, updating it with the options
+      #   supplied. Useful for resource scopes.
+      # @see #initialize
+      # @example
+      #   Recurly::Account.active.paginate :per_page => 20
+      def paginate options = {}
+        dup.instance_eval {
+          @collection = @count = @etag = nil
+          @options.update options and self
+        }
+      end
+      alias scoped paginate
+      alias where  paginate
+
+      def all options = {}
+        paginate(options).to_a
+      end
+
+      # Instantiates a new record in the scope of the pager.
+      #
+      # @return [Resource] A new record.
+      # @example
+      #   account = Recurly::Account.find 'schrader'
+      #   subscription = account.subscriptions.new attributes
+      # @see Resource.new
+      def new attributes = {}
+        record = resource_class.send(:new, attributes) { |r|
+          r.attributes[@parent.class.member_name] ||= @parent if @parent
+          r.uri = uri
+        }
+        yield record if block_given?
+        record
+      end
+
+      # Instantiates and saves a record in the scope of the pager.
+      #
+      # @return [Resource] The record.
+      # @raise [Transaction::Error] A monetary transaction failed.
+      # @example
+      #   account = Recurly::Account.find 'schrader'
+      #   subscription = account.subscriptions.create attributes
+      # @see Resource.create
+      def create attributes = {}
+        new(attributes) { |record| record.save }
+      end
+
+      # Instantiates and saves a record in the scope of the pager.
+      #
+      # @return [Resource] The saved record.
+      # @raise [Invalid] The record is invalid.
+      # @raise [Transaction::Error] A monetary transaction failed.
+      # @example
+      #   account = Recurly::Account.find 'schrader'
+      #   subscription = account.subscriptions.create! attributes
+      # @see Resource.create!
+      def create! attributes = {}
+        new(attributes) { |record| record.save! }
+      end
+
+      # @return [true, false]
+      # @see Object#respond_to?
+      def respond_to? method_name, include_private = false
+        super || [].respond_to?(method_name, include_private)
+      end
+
+      private
+
+      def load_from uri, params
+        options = {}
+        options[:head] = { 'If-None-Match' => etag } if etag
+        response = API.get uri, params, options
+
+        @etag = response['ETag']
+        @count = response['X-Records'].to_i
+        @links = {}
+        if links = response['Link']
+          links.scan(/<([^>]+)>; rel="([^"]+)"/).each do |link|
+            @links[link.last] = link.first.freeze
+          end
+        end
+        @links.freeze
+
+        @collection = []
+        document = XML.new response.body
+        document.each_element(resource_class.member_name) do |el|
+          record = resource_class.from_xml el
+          record.attributes[@parent.class.member_name] = @parent if @parent
+          @collection << record
+        end
+        @collection.freeze
+      rescue API::NotModified
+        defined? @collection and @collection or raise
+      end
+
+      def method_missing name, *args, &block
+        scope = resource_class.scopes[name] and return paginate scope
+
+        if [].respond_to? name
+          load! unless defined? @collection
+          return @collection.send name, *args, &block
+        end
+        
+        super
+      end
+    end
+  end
+end

data/lib/recurly/subscription.rb

@@ -1,87 +1,110 @@
 module Recurly
-  class Subscription < AccountBase
-    self.element_name = "subscription"
+  class Subscription < Resource
+    autoload :AddOns, 'recurly/subscription/add_ons'
 
-    def self.known_attributes
-      [
-        "plan_code",
-        "coupon_code",
-        "unit_amount_in_cents",
-        "quantity",
-        "trial_ends_at"
-      ]
-    end
+    # @macro [attach] scope
+    #   @scope class
+    #   @return [Pager<Subscription>] A pager that yields +$1+ subscriptions.
+    scope :active,       :state => :active
+    scope :in_trial,     :state => :in_trial
+    scope :non_renewing, :state => :non_renewing
 
-    # initialize associations
-    def initialize(attributes = {}, persisted = false)
-      attributes = attributes.with_indifferent_access
-      attributes[:account] ||= {}
-      attributes[:addons] ||= []
-      super
-    end
+    # @return [Account]
+    belongs_to :account
+    # @return [Plan]
+    belongs_to :plan
 
-    # API inconsistency workaround: Pull plan_code into subscription to conform to known_attributes
-    def load(attributes, remove_root = false)
-      attributes = attributes.with_indifferent_access
-      attributes[:plan_code] ||= attributes[:plan][:plan_code] if attributes.include?(:plan)
-      super
-    end
-    
-    def self.refund(account_code, refund_type = :partial)
-      raise "Refund type must be :full, :partial, or :none." unless [:full, :partial, :none].include?(refund_type)
-      Subscription.delete(nil, {:account_code => account_code, :refund => refund_type})
-    end
+    define_attribute_methods %w(
+      uuid
+      state
+      unit_amount_in_cents
+      currency
+      quantity
+      activated_at
+      canceled_at
+      expires_at
+      current_period_started_at
+      current_period_ends_at
+      trial_started_at
+      trial_ends_at
+      pending_subscription
+      subscription_add_ons
+    )
+    alias to_param uuid
 
-    # Terminates the subscription immediately and processes a full or partial refund
-    def refund(refund_type)
-      self.class.refund(self.subscription_account_code, refund_type)
+    # @return [Subscription] A new subscription.
+    def initialize attributes = {}
+      super({ :currency => Recurly.default_currency }.merge attributes)
     end
 
-    def self.cancel(account_code)
-      Subscription.delete(account_code)
+    # Assign a Plan resource (rather than a plan code).
+    #
+    # @param plan [Plan]
+    def plan= plan
+      self[:plan_code] = plan.plan_code if plan.respond_to? :plan_code
+      attributes[:plan] = plan
     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 = nil)
-      unless account_code.nil?
-        ActiveSupport::Deprecation.warn('Calling Recurly::Subscription#cancel with an account_code has been deprecated. Use the static method Recurly::Subscription.cancel(account_code) instead', caller)
-      end
-      self.class.cancel(account_code || self.subscription_account_code)
+    # @return [AddOns]
+    def subscription_add_ons
+      AddOns.new self, super
     end
+    alias add_ons subscription_add_ons
 
-    def self.reactivate(account_code, options = {})
-      path = "/accounts/#{CGI::escape(account_code.to_s)}/subscription/reactivate"
-      connection.post(path, "", headers)
-    rescue ActiveResource::Redirection => e
-      return true
+    # Assign an array of subscription add-ons.
+    def subscription_add_ons= subscription_add_ons
+      super AddOns.new self, subscription_add_ons
     end
+    alias add_ons= subscription_add_ons=
 
-    def reactivate
-      self.class.reactivate(self.subscription_account_code)
+    # Cancel a subscription so that it will not renew.
+    #
+    # @return [true, false] +true+ when successful, +false+ when unable to
+    #   (e.g., the subscription is not active).
+    # @example
+    #   account = Account.find account_code
+    #   subscription = account.subscriptions.first
+    #   subscription.cancel # => true
+    def cancel
+      return false unless self[:cancel]
+      reload self[:cancel].call
+      true
     end
 
-    # Valid timeframe: :now or :renewal
-    # Valid options: plan_code, quantity, unit_amount
-    def change(timeframe, options = {})
-      raise "Timeframe must be :now or :renewal." unless ['now','renewal'].include?(timeframe)
-      options[:timeframe] = timeframe
-      path = "/accounts/#{CGI::escape(self.subscription_account_code.to_s)}/subscription.xml"
-      connection.put(path,
-        self.class.format.encode(options, :root => :subscription),
-        self.class.headers)
-    rescue ActiveResource::ResourceInvalid => e
-      self.load_errors e.response.body
+    # An array of acceptable refund types.
+    REFUND_TYPES = ['none', 'full', 'partial'].freeze
+
+    # Immediately terminate a subscription (with optional refund).
+    #
+    # @return [true, false] +true+ when successful, +false+ when unable to
+    #   (e.g., the subscription is not active).
+    # @param refund_type [:none, :full, :partial] <tt>:none</tt> terminates the
+    #   subscription with no refund (the default), <tt>:full</tt> refunds the
+    #   subscription in full, and <tt>:partial</tt> refunds the subscription in
+    #   part.
+    # @raise [ArgumentError] Invalid +refund_type+.
+    # @example
+    #   account = Account.find account_code
+    #   subscription = account.subscriptions.first
+    #   subscription.terminate(:partial) # => true
+    def terminate refund_type = :none
+      return false unless self[:terminate]
+      unless REFUND_TYPES.include? refund_type.to_s
+        raise ArgumentError, "refund must be one of: #{REFUND_TYPES.join ', '}"
+      end
+      reload self[:terminate].call(:params => { :refund => refund_type })
+      true
     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?
-      acct_code ||= self.primary_key if defined?(self.primary_key)
-      acct_code ||= self.id if defined?(self.id)
-      raise 'Missing Account Code' if acct_code.blank?
-      acct_code
+    # Reactivate a subscription.
+    #
+    # @return [true, false] +true+ when successful, +false+ when unable to
+    #   (e.g., the subscription is already active), and may raise an exception
+    #   if the reactivation fails.
+    def reactivate
+      return false unless self[:reactivate]
+      reload self[:reactivate].call
+      true
     end
   end
 end
-

data/lib/recurly/subscription/add_ons.rb

@@ -0,0 +1,73 @@
+module Recurly
+  class Subscription < Resource
+    class AddOns
+      instance_methods.each do |method|
+        undef_method method if method !~ /^__|^(object_id|respond_to\?|send)$/ 
+      end
+
+      # @param subscription [Subscription]
+      # @param add_ons [Array, nil]
+      def initialize subscription, add_ons = []
+        @subscription, @add_ons = subscription, []
+        add_ons and add_ons.each { |a| self << a }
+      end
+
+      # @return [self]
+      # @param add_on [AddOn, String, Symbol, Hash] A {Plan} add-on,
+      #   +add_on_code+, or hash with optional <tt>:quantity</tt> and
+      #   <tt>:unit_amount_in_cents</tt> keys.
+      # @example
+      #   pp subscription.add_ons << '1YEARWAR' << '1YEARWAR' << :BONUS
+      #   [
+      #     {:add_on_code => "1YEARWAR", :quantity => 2},
+      #     {:add_on_code => "BONUS"}
+      #   ]
+      def << add_on
+        case add_on
+          when AddOn then add_on = { :add_on_code => add_on.add_on_code }
+          when String, Symbol then add_on = { :add_on_code => add_on.to_s }
+        end
+
+        exist = @add_ons.find { |a| a[:add_on_code] == add_on[:add_on_code] }
+        if exist
+          exist[:quantity] ||= 1 and exist[:quantity] += 1
+
+          if add_on[:unit_amount_in_cents]
+            exist[:unit_amount_in_cents] = add_on[:unit_amount_in_cents]
+          end
+        else
+          @add_ons << add_on
+        end
+
+        @subscription[:subscription_add_ons] = to_a and self
+      end
+
+      def to_a
+        @add_ons.dup
+      end
+
+      def to_xml options = {}
+        builder = options[:builder] || XML.new('<subscription_add_ons/>')
+        @add_ons.each do |add_on|
+          node = builder.add_element 'subscription_add_on'
+          add_on.each_pair { |k, v| node.add_element k.to_s, v }
+        end
+        builder.to_s
+      end
+
+      def respond_to? method_name, include_private = false
+        super || @add_ons.respond_to?(method_name, include_private)
+      end
+
+      private
+
+      def method_missing name, *args, &block
+        if @add_ons.respond_to? name
+          return @add_ons.send name, *args, &block
+        end
+
+        super
+      end
+    end
+  end
+end