recurly 3.4.0 → 3.8.0

data/lib/recurly/http.rb

@@ -4,15 +4,16 @@ module Recurly
       attr_accessor :status, :body, :request,
         :request_id, :rate_limit, :rate_limit_remaining,
         :rate_limit_reset, :date, :proxy_metadata,
-        :content_type
+        :content_type, :total_records
 
       def initialize(resp, request)
-        @request = request
+        @request = Request.new(request.method, request.path, request.body)
         @status = resp.code.to_i
         @request_id = resp["x-request-id"]
         @rate_limit = resp["x-ratelimit-limit"].to_i
         @rate_limit_remaining = resp["x-ratelimit-remaining"].to_i
         @rate_limit_reset = Time.at(resp["x-ratelimit-reset"].to_i).to_datetime
+        @total_records = resp["recurly-total-records"]&.to_i
         if resp["content-type"]
           @content_type = resp["content-type"].split(";").first
         else

data/lib/recurly/pager.rb

@@ -7,7 +7,25 @@ module Recurly
       @client = client
       @path = path
       @options = map_array_params(options)
-      @next = build_path(@path, @options)
+      rewind!
+    end
+
+    # Performs a request with the pager `limit` set to 1 and only returns the first
+    # result in the response.
+    def first
+      # Modify the @next url to set the :limit to 1
+      original_next = @next
+      @next = @path
+      fetch_next!(@options.merge(limit: 1))
+      # Restore the @next url to the original
+      @next = original_next
+      @data.first
+    end
+
+    # Makes a HEAD request to the API to determine how many total records exist.
+    def count
+      resource = @client.send(:head, self.next, @options)
+      resource.get_response.total_records
     end
 
     # Enumerates each "page" from the server.
@@ -84,7 +102,9 @@ module Recurly
     def page_enumerator
       Enumerator.new do |yielder|
         loop do
-          fetch_next!
+          # Pass in @options when requesting the first page (@data.empty?)
+          next_options = @data.empty? ? @options : {}
+          fetch_next!(next_options)
           yielder << data
           unless has_more?
             rewind!
@@ -94,8 +114,9 @@ module Recurly
       end
     end
 
-    def fetch_next!
-      page = @client.next_page(self)
+    def fetch_next!(options)
+      path = extract_path(self.next)
+      page = @client.send(:get, path, options)
       @data = page.data.map { |d| JSONParser.from_json(d) }
       @has_more = page.has_more
       @next = page.next
@@ -103,15 +124,13 @@ module Recurly
 
     def rewind!
       @data = []
-      @next = build_path(@path, @options)
+      @next = @path
     end
 
-    def build_path(path, options)
-      if options.empty?
-        path
-      else
-        "#{path}?#{URI.encode_www_form(options)}"
-      end
+    # Returns just the path and parameters so we can safely reuse the connection
+    def extract_path(uri_or_path)
+      uri = URI(uri_or_path)
+      uri.kind_of?(URI::HTTP) ? uri.request_uri : uri_or_path
     end
 
     # Converts array parameters to CSV strings to maintain consistency with
@@ -121,7 +140,7 @@ module Recurly
       @options = params.map do |key, param|
         new_param = param.is_a?(Array) ? param.join(",") : param
         [key, new_param]
-      end
+      end.to_h
     end
   end
 end

data/lib/recurly/requests/add_on_create.rb

@@ -15,7 +15,7 @@ module Recurly
       define_attribute :code, String
 
       # @!attribute currencies
-      #   @return [Array[AddOnPricing]] If `item_code`/`item_id` is part of the request and the item has a default currency then `currencies` is optional. If the item does not have a default currency, then `currencies` is required. If `item_code`/`item_id` is not present `currencies` is required.
+      #   @return [Array[AddOnPricing]] * If `item_code`/`item_id` is part of the request and the item has a default currency then `currencies` is optional. If the item does not have a default currency, then `currencies` is required. If `item_code`/`item_id` is not present `currencies` is required. * If the add-on's `tier_type` is `tiered`, `volume`, or `stairstep`, then `currencies` must be absent.
       define_attribute :currencies, Array, { :item_type => :AddOnPricing }
 
       # @!attribute default_quantity
@@ -27,17 +27,21 @@ module Recurly
       define_attribute :display_quantity, :Boolean
 
       # @!attribute item_code
-      #   @return [String] Unique code to identify an item. Avaliable when the `Catalog: Item Add-Ons` feature is enabled. If `item_id` and `item_code` are both present, `item_id` will be used.
+      #   @return [String] Unique code to identify an item. Avaliable when the `Credit Invoices` and `Subscription Billing Terms` features are enabled. If `item_id` and `item_code` are both present, `item_id` will be used.
       define_attribute :item_code, String
 
       # @!attribute item_id
-      #   @return [String] System-generated unique identifier for an item. Available when the `Catalog: Item Add-Ons` feature is enabled. If `item_id` and `item_code` are both present, `item_id` will be used.
+      #   @return [String] System-generated unique identifier for an item. Available when the `Credit Invoices` and `Subscription Billing Terms` features are enabled. If `item_id` and `item_code` are both present, `item_id` will be used.
       define_attribute :item_id, String
 
       # @!attribute name
       #   @return [String] Describes your add-on and will appear in subscribers' invoices. If `item_code`/`item_id` is part of the request then `name` must be absent. If `item_code`/`item_id` is not present `name` is required.
       define_attribute :name, String
 
+      # @!attribute optional
+      #   @return [Boolean] Whether the add-on is optional for the customer to include in their purchase on the hosted payment page. If false, the add-on will be included when a subscription is created through the Recurly UI. However, the add-on will not be included when a subscription is created through the API.
+      define_attribute :optional, :Boolean
+
       # @!attribute plan_id
       #   @return [String] Plan ID
       define_attribute :plan_id, String
@@ -49,6 +53,14 @@ module Recurly
       # @!attribute tax_code
       #   @return [String] Optional field used by Avalara, Vertex, and Recurly's EU VAT tax feature to determine taxation rules. If you have your own AvaTax or Vertex account configured, use their tax codes to assign specific tax rules. If you are using Recurly's EU VAT feature, you can use values of `unknown`, `physical`, or `digital`. If `item_code`/`item_id` is part of the request then `tax_code` must be absent.
       define_attribute :tax_code, String
+
+      # @!attribute tier_type
+      #   @return [String] The pricing model for the add-on.  For more information, [click here](https://docs.recurly.com/docs/billing-models#section-quantity-based).
+      define_attribute :tier_type, String
+
+      # @!attribute tiers
+      #   @return [Array[Tier]] If the tier_type is `flat`, then `tiers` must be absent. The `tiers` object must include one to many tiers with `ending_quantity` and `unit_amount` for the desired `currencies`. There must be one tier with an `ending_quantity` of 999999999 which is the default if not provided.
+      define_attribute :tiers, Array, { :item_type => :Tier }
     end
   end
 end

data/lib/recurly/requests/add_on_update.rb

@@ -15,7 +15,7 @@ module Recurly
       define_attribute :code, String
 
       # @!attribute currencies
-      #   @return [Array[AddOnPricing]] Add-on pricing
+      #   @return [Array[AddOnPricing]] If the add-on's `tier_type` is `tiered`, `volume` or `stairstep`, then `currencies` must be absent.
       define_attribute :currencies, Array, { :item_type => :AddOnPricing }
 
       # @!attribute default_quantity
@@ -34,6 +34,10 @@ module Recurly
       #   @return [String] Describes your add-on and will appear in subscribers' invoices. If an `Item` is associated to the `AddOn` then `name` must be absent.
       define_attribute :name, String
 
+      # @!attribute optional
+      #   @return [Boolean] Whether the add-on is optional for the customer to include in their purchase on the hosted payment page. If false, the add-on will be included when a subscription is created through the Recurly UI. However, the add-on will not be included when a subscription is created through the API.
+      define_attribute :optional, :Boolean
+
       # @!attribute revenue_schedule_type
       #   @return [String] When this add-on is invoiced, the line item will use this revenue schedule. If an `Item` is associated to the `AddOn` then `revenue_schedule_type` must be absent in the request as the value will be set from the item.
       define_attribute :revenue_schedule_type, String
@@ -41,6 +45,10 @@ module Recurly
       # @!attribute tax_code
       #   @return [String] Optional field used by Avalara, Vertex, and Recurly's EU VAT tax feature to determine taxation rules. If you have your own AvaTax or Vertex account configured, use their tax codes to assign specific tax rules. If you are using Recurly's EU VAT feature, you can use values of `unknown`, `physical`, or `digital`. If an `Item` is associated to the `AddOn` then `tax code` must be absent.
       define_attribute :tax_code, String
+
+      # @!attribute tiers
+      #   @return [Array[Tier]] If the tier_type is `flat`, then `tiers` must be absent. The `tiers` object must include one to many tiers with `ending_quantity` and `unit_amount` for the desired `currencies`. There must be one tier with an `ending_quantity` of 999999999 which is the default if not provided.
+      define_attribute :tiers, Array, { :item_type => :Tier }
     end
   end
 end

data/lib/recurly/requests/billing_info_create.rb

@@ -6,6 +6,14 @@ module Recurly
   module Requests
     class BillingInfoCreate < Request
 
+      # @!attribute account_number
+      #   @return [String] The bank account number. (ACH, Bacs only)
+      define_attribute :account_number, String
+
+      # @!attribute account_type
+      #   @return [String] The bank account type. (ACH only)
+      define_attribute :account_type, String
+
       # @!attribute address
       #   @return [Address]
       define_attribute :address, :Address
@@ -39,7 +47,7 @@ module Recurly
       define_attribute :gateway_token, String
 
       # @!attribute iban
-      #   @return [String] The International Bank Account Number, up to 34 alphanumeric characters comprising a country code; two check digits; and a number that includes the domestic bank account number, branch identifier, and potential routing information
+      #   @return [String] The International Bank Account Number, up to 34 alphanumeric characters comprising a country code; two check digits; and a number that includes the domestic bank account number, branch identifier, and potential routing information. (SEPA only)
       define_attribute :iban, String
 
       # @!attribute ip_address
@@ -54,6 +62,10 @@ module Recurly
       #   @return [String] Expiration month
       define_attribute :month, String
 
+      # @!attribute name_on_account
+      #   @return [String] The name associated with the bank account (ACH, SEPA, Bacs only)
+      define_attribute :name_on_account, String
+
       # @!attribute number
       #   @return [String] Credit card number, spaces and dashes are accepted.
       define_attribute :number, String
@@ -62,18 +74,30 @@ module Recurly
       #   @return [String] PayPal billing agreement ID
       define_attribute :paypal_billing_agreement_id, String
 
+      # @!attribute routing_number
+      #   @return [String] The bank's rounting number. (ACH only)
+      define_attribute :routing_number, String
+
+      # @!attribute sort_code
+      #   @return [String] Bank identifier code for UK based banks. Required for Bacs based billing infos. (Bacs only)
+      define_attribute :sort_code, String
+
       # @!attribute three_d_secure_action_result_token_id
       #   @return [String] A token generated by Recurly.js after completing a 3-D Secure device fingerprinting or authentication challenge.
       define_attribute :three_d_secure_action_result_token_id, String
 
       # @!attribute token_id
-      #   @return [String] A token [generated by Recurly.js](https://docs.recurly.com/js/#getting-a-token).
+      #   @return [String] A token [generated by Recurly.js](https://developers.recurly.com/reference/recurly-js/#getting-a-token).
       define_attribute :token_id, String
 
       # @!attribute transaction_type
       #   @return [String] An optional type designation for the payment gateway transaction created by this request. Supports 'moto' value, which is the acronym for mail order and telephone transactions.
       define_attribute :transaction_type, String
 
+      # @!attribute type
+      #   @return [String] The payment method type for a non-credit card based billing info. The value of `bacs` is the only accepted value (Bacs only)
+      define_attribute :type, String
+
       # @!attribute vat_number
       #   @return [String] VAT number
       define_attribute :vat_number, String

data/lib/recurly/requests/external_transaction.rb

@@ -0,0 +1,26 @@
+# This file is automatically created by Recurly's OpenAPI generation process
+# and thus any edits you make by hand will be lost. If you wish to make a
+# change to this file, please create a Github issue explaining the changes you
+# need and we will usher them to the appropriate places.
+module Recurly
+  module Requests
+    class ExternalTransaction < Request
+
+      # @!attribute amount
+      #   @return [Float] The total amount of the transcaction. Cannot excceed the invoice total.
+      define_attribute :amount, Float
+
+      # @!attribute collected_at
+      #   @return [DateTime] Datetime that the external payment was collected. Defaults to current datetime.
+      define_attribute :collected_at, DateTime
+
+      # @!attribute description
+      #   @return [String] Used as the transaction's description.
+      define_attribute :description, String
+
+      # @!attribute payment_method
+      #   @return [String] Payment method used for the external transaction.
+      define_attribute :payment_method, String
+    end
+  end
+end

data/lib/recurly/requests/plan_create.rb

@@ -14,6 +14,10 @@ module Recurly
       #   @return [Array[AddOnCreate]] Add Ons
       define_attribute :add_ons, Array, { :item_type => :AddOnCreate }
 
+      # @!attribute allow_any_item_on_subscriptions
+      #   @return [Boolean] Used to determine whether items can be assigned as add-ons to individual subscriptions. If `true`, items can be assigned as add-ons to individual subscription add-ons. If `false`, only plan add-ons can be used.
+      define_attribute :allow_any_item_on_subscriptions, :Boolean
+
       # @!attribute auto_renew
       #   @return [Boolean] Subscriptions will automatically inherit this value once they are active. If `auto_renew` is `true`, then a subscription will automatically renew its term at renewal. If `auto_renew` is `false`, then a subscription will expire at the end of its term. `auto_renew` can be overridden on the subscription record itself.
       define_attribute :auto_renew, :Boolean
@@ -74,6 +78,10 @@ module Recurly
       #   @return [Integer] Length of plan's trial period in `trial_units`. `0` means `no trial`.
       define_attribute :trial_length, Integer
 
+      # @!attribute trial_requires_billing_info
+      #   @return [Boolean] Allow free trial subscriptions to be created without billing info. Should not be used if billing info is needed for initial invoice due to existing uninvoiced charges or setup fee.
+      define_attribute :trial_requires_billing_info, :Boolean
+
       # @!attribute trial_unit
       #   @return [String] Units for the plan's trial period.
       define_attribute :trial_unit, String

data/lib/recurly/requests/plan_update.rb

@@ -14,6 +14,10 @@ module Recurly
       #   @return [Array[AddOnCreate]] Add Ons
       define_attribute :add_ons, Array, { :item_type => :AddOnCreate }
 
+      # @!attribute allow_any_item_on_subscriptions
+      #   @return [Boolean] Used to determine whether items can be assigned as add-ons to individual subscriptions. If `true`, items can be assigned as add-ons to individual subscription add-ons. If `false`, only plan add-ons can be used.
+      define_attribute :allow_any_item_on_subscriptions, :Boolean
+
       # @!attribute auto_renew
       #   @return [Boolean] Subscriptions will automatically inherit this value once they are active. If `auto_renew` is `true`, then a subscription will automatically renew its term at renewal. If `auto_renew` is `false`, then a subscription will expire at the end of its term. `auto_renew` can be overridden on the subscription record itself.
       define_attribute :auto_renew, :Boolean
@@ -70,6 +74,10 @@ module Recurly
       #   @return [Integer] Length of plan's trial period in `trial_units`. `0` means `no trial`.
       define_attribute :trial_length, Integer
 
+      # @!attribute trial_requires_billing_info
+      #   @return [Boolean] Allow free trial subscriptions to be created without billing info. Should not be used if billing info is needed for initial invoice due to existing uninvoiced charges or setup fee.
+      define_attribute :trial_requires_billing_info, :Boolean
+
       # @!attribute trial_unit
       #   @return [String] Units for the plan's trial period.
       define_attribute :trial_unit, String

data/lib/recurly/requests/shipping_method_create.rb

@@ -0,0 +1,26 @@
+# This file is automatically created by Recurly's OpenAPI generation process
+# and thus any edits you make by hand will be lost. If you wish to make a
+# change to this file, please create a Github issue explaining the changes you
+# need and we will usher them to the appropriate places.
+module Recurly
+  module Requests
+    class ShippingMethodCreate < Request
+
+      # @!attribute accounting_code
+      #   @return [String] Accounting code for shipping method.
+      define_attribute :accounting_code, String
+
+      # @!attribute code
+      #   @return [String] The internal name used identify the shipping method.
+      define_attribute :code, String
+
+      # @!attribute name
+      #   @return [String] The name of the shipping method displayed to customers.
+      define_attribute :name, String
+
+      # @!attribute tax_code
+      #   @return [String] Used by Avalara, Vertex, and Recurly’s built-in tax feature. The tax code values are specific to each tax system. If you are using Recurly’s built-in taxes the values are:  - `FR` – Common Carrier FOB Destination - `FR022000` – Common Carrier FOB Origin - `FR020400` – Non Common Carrier FOB Destination - `FR020500` – Non Common Carrier FOB Origin - `FR010100` – Delivery by Company Vehicle Before Passage of Title - `FR010200` – Delivery by Company Vehicle After Passage of Title - `NT` – Non-Taxable
+      define_attribute :tax_code, String
+    end
+  end
+end

data/lib/recurly/requests/shipping_method_update.rb

@@ -0,0 +1,26 @@
+# This file is automatically created by Recurly's OpenAPI generation process
+# and thus any edits you make by hand will be lost. If you wish to make a
+# change to this file, please create a Github issue explaining the changes you
+# need and we will usher them to the appropriate places.
+module Recurly
+  module Requests
+    class ShippingMethodUpdate < Request
+
+      # @!attribute accounting_code
+      #   @return [String] Accounting code for shipping method.
+      define_attribute :accounting_code, String
+
+      # @!attribute code
+      #   @return [String] The internal name used identify the shipping method.
+      define_attribute :code, String
+
+      # @!attribute name
+      #   @return [String] The name of the shipping method displayed to customers.
+      define_attribute :name, String
+
+      # @!attribute tax_code
+      #   @return [String] Used by Avalara, Vertex, and Recurly’s built-in tax feature. The tax code values are specific to each tax system. If you are using Recurly’s built-in taxes the values are:  - `FR` – Common Carrier FOB Destination - `FR022000` – Common Carrier FOB Origin - `FR020400` – Non Common Carrier FOB Destination - `FR020500` – Non Common Carrier FOB Origin - `FR010100` – Delivery by Company Vehicle Before Passage of Title - `FR010200` – Delivery by Company Vehicle After Passage of Title - `NT` – Non-Taxable
+      define_attribute :tax_code, String
+    end
+  end
+end

data/lib/recurly/requests/subscription_add_on_create.rb

@@ -6,6 +6,10 @@ module Recurly
   module Requests
     class SubscriptionAddOnCreate < Request
 
+      # @!attribute add_on_source
+      #   @return [String] Used to determine where the associated add-on data is pulled from. If this value is set to `plan_add_on` or left blank, then add_on data will be pulled from the plan's add-ons. If the associated `plan` has `allow_any_item_on_subscriptions` set to `true` and this field is set to `item`, then the associated add-on data will be pulled from the site's item catalog.
+      define_attribute :add_on_source, String
+
       # @!attribute code
       #   @return [String] Add-on code
       define_attribute :code, String
@@ -18,8 +22,12 @@ module Recurly
       #   @return [String] Revenue schedule type
       define_attribute :revenue_schedule_type, String
 
+      # @!attribute tiers
+      #   @return [Array[SubscriptionAddOnTier]] If the plan add-on's `tier_type` is `flat`, then `tiers` must be absent. The `tiers` object must include one to many tiers with `ending_quantity` and `unit_amount`. There must be one tier with an `ending_quantity` of 999999999 which is the default if not provided.
+      define_attribute :tiers, Array, { :item_type => :SubscriptionAddOnTier }
+
       # @!attribute unit_amount
-      #   @return [Float] Optionally, override the add-on's default unit amount.
+      #   @return [Float] * Optionally, override the add-on's default unit amount. * If the plan add-on's `tier_type` is `tiered`, `volume`, or `stairstep`, then `unit_amount` must be absent.
       define_attribute :unit_amount, Float
     end
   end

data/lib/recurly/requests/subscription_add_on_tier.rb

@@ -0,0 +1,18 @@
+# This file is automatically created by Recurly's OpenAPI generation process
+# and thus any edits you make by hand will be lost. If you wish to make a
+# change to this file, please create a Github issue explaining the changes you
+# need and we will usher them to the appropriate places.
+module Recurly
+  module Requests
+    class SubscriptionAddOnTier < Request
+
+      # @!attribute ending_quantity
+      #   @return [Integer] Ending quantity
+      define_attribute :ending_quantity, Integer
+
+      # @!attribute unit_amount
+      #   @return [Float] Unit amount
+      define_attribute :unit_amount, Float
+    end
+  end
+end

data/lib/recurly/requests/subscription_add_on_update.rb

@@ -7,11 +7,11 @@ module Recurly
     class SubscriptionAddOnUpdate < Request
 
       # @!attribute code
-      #   @return [String] Add-on code
+      #   @return [String] If a code is provided without an id, the subscription add-on attributes will be set to the current value for those attributes on the plan add-on unless provided in the request.
       define_attribute :code, String
 
       # @!attribute id
-      #   @return [String] Set this to include or modify an existing subscription add-on.
+      #   @return [String] When an id is provided, the existing subscription add-on attributes will persist unless overridden in the request.
       define_attribute :id, String
 
       # @!attribute quantity
@@ -22,6 +22,10 @@ module Recurly
       #   @return [String] Revenue schedule type
       define_attribute :revenue_schedule_type, String
 
+      # @!attribute tiers
+      #   @return [Array[SubscriptionAddOnTier]] If the plan add-on's `tier_type` is `flat`, then `tiers` must be absent. The `tiers` object must include one to many tiers with `ending_quantity` and `unit_amount`. There must be one tier with an `ending_quantity` of 999999999 which is the default if not provided.
+      define_attribute :tiers, Array, { :item_type => :SubscriptionAddOnTier }
+
       # @!attribute unit_amount
       #   @return [Float] Optionally, override the add-on's default unit amount.
       define_attribute :unit_amount, Float

data/lib/recurly/requests/subscription_change_create.rb

@@ -7,7 +7,7 @@ module Recurly
     class SubscriptionChangeCreate < Request
 
       # @!attribute add_ons
-      #   @return [Array[SubscriptionAddOnUpdate]] If you provide a value for this field it will replace any existing add-ons. So, when adding or modifying an add-on, you need to include the existing subscription add-ons. Unchanged add-ons can be included just using the subscription add-on's ID: `{"id": "abc123"}`.
+      #   @return [Array[SubscriptionAddOnUpdate]] If you provide a value for this field it will replace any existing add-ons. So, when adding or modifying an add-on, you need to include the existing subscription add-ons. Unchanged add-ons can be included just using the subscription add-on's ID: `{"id": "abc123"}`.  If a subscription add-on's `code` is supplied without the `id`, `{"code": "def456"}`, the subscription add-on attributes will be set to the current values of the plan add-on unless provided in the request.  - If an `id` is passed, any attributes not passed in will pull from the   existing subscription add-on - If a `code` is passed, any attributes not passed in will pull from the   current values of the plan add-on - Attributes passed in as part of the request will override either of the   above scenarios
       define_attribute :add_ons, Array, { :item_type => :SubscriptionAddOnUpdate }
 
       # @!attribute collection_method