recurly 2.17.0 → 3.14.0

data/lib/recurly/resources/transaction_payment_gateway.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 Resources
+    class TransactionPaymentGateway < Resource
+
+      # @!attribute id
+      #   @return [String]
+      define_attribute :id, String
+
+      # @!attribute name
+      #   @return [String]
+      define_attribute :name, String
+
+      # @!attribute object
+      #   @return [String] Object type
+      define_attribute :object, String
+
+      # @!attribute type
+      #   @return [String]
+      define_attribute :type, String
+    end
+  end
+end

data/lib/recurly/resources/unique_coupon_code.rb

@@ -0,0 +1,50 @@
+# 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 Resources
+    class UniqueCouponCode < Resource
+
+      # @!attribute bulk_coupon_code
+      #   @return [String] The Coupon code of the parent Bulk Coupon
+      define_attribute :bulk_coupon_code, String
+
+      # @!attribute bulk_coupon_id
+      #   @return [String] The Coupon ID of the parent Bulk Coupon
+      define_attribute :bulk_coupon_id, String
+
+      # @!attribute code
+      #   @return [String] The code the customer enters to redeem the coupon.
+      define_attribute :code, String
+
+      # @!attribute created_at
+      #   @return [DateTime] Created at
+      define_attribute :created_at, DateTime
+
+      # @!attribute expired_at
+      #   @return [DateTime] The date and time the coupon was expired early or reached its `max_redemptions`.
+      define_attribute :expired_at, DateTime
+
+      # @!attribute id
+      #   @return [String] Unique Coupon Code ID
+      define_attribute :id, String
+
+      # @!attribute object
+      #   @return [String] Object type
+      define_attribute :object, String
+
+      # @!attribute redeemed_at
+      #   @return [DateTime] The date and time the unique coupon code was redeemed.
+      define_attribute :redeemed_at, DateTime
+
+      # @!attribute state
+      #   @return [String] Indicates if the unique coupon code is redeemable or why not.
+      define_attribute :state, String
+
+      # @!attribute updated_at
+      #   @return [DateTime] Updated at
+      define_attribute :updated_at, DateTime
+    end
+  end
+end

data/lib/recurly/resources/usage.rb

@@ -0,0 +1,70 @@
+# 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 Resources
+    class Usage < Resource
+
+      # @!attribute amount
+      #   @return [Float] The amount of usage. Can be positive, negative, or 0. No decimals allowed, we will strip them. If the usage-based add-on is billed with a percentage, your usage will be a monetary amount you will want to format in cents. (e.g., $5.00 is "500").
+      define_attribute :amount, Float
+
+      # @!attribute billed_at
+      #   @return [DateTime] When the usage record was billed on an invoice.
+      define_attribute :billed_at, DateTime
+
+      # @!attribute created_at
+      #   @return [DateTime] When the usage record was created in Recurly.
+      define_attribute :created_at, DateTime
+
+      # @!attribute id
+      #   @return [String]
+      define_attribute :id, String
+
+      # @!attribute measured_unit_id
+      #   @return [String] The ID of the measured unit associated with the add-on the usage record is for.
+      define_attribute :measured_unit_id, String
+
+      # @!attribute merchant_tag
+      #   @return [String] Custom field for recording the id in your own system associated with the usage, so you can provide auditable usage displays to your customers using a GET on this endpoint.
+      define_attribute :merchant_tag, String
+
+      # @!attribute object
+      #   @return [String] Object type
+      define_attribute :object, String
+
+      # @!attribute recording_timestamp
+      #   @return [DateTime] When the usage was recorded in your system.
+      define_attribute :recording_timestamp, DateTime
+
+      # @!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[SubscriptionAddOnTier]] The tiers and prices of the subscription based on the usage_timestamp. If tier_type = flat, tiers = null
+      define_attribute :tiers, Array, { :item_type => :SubscriptionAddOnTier }
+
+      # @!attribute unit_amount
+      #   @return [Float] Unit price
+      define_attribute :unit_amount, Float
+
+      # @!attribute updated_at
+      #   @return [DateTime] When the usage record was billed on an invoice.
+      define_attribute :updated_at, DateTime
+
+      # @!attribute usage_percentage
+      #   @return [Float] The percentage taken of the monetary amount of usage tracked. This can be up to 4 decimal places. A value between 0.0 and 100.0.
+      define_attribute :usage_percentage, Float
+
+      # @!attribute usage_timestamp
+      #   @return [DateTime] When the usage actually happened. This will define the line item dates this usage is billed under and is important for revenue recognition.
+      define_attribute :usage_timestamp, DateTime
+
+      # @!attribute usage_type
+      #   @return [String] Type of usage, returns usage type if `add_on_type` is `usage`.
+      define_attribute :usage_type, String
+    end
+  end
+end

data/lib/recurly/resources/user.rb

@@ -0,0 +1,42 @@
+# 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 Resources
+    class User < Resource
+
+      # @!attribute created_at
+      #   @return [DateTime]
+      define_attribute :created_at, DateTime
+
+      # @!attribute deleted_at
+      #   @return [DateTime]
+      define_attribute :deleted_at, DateTime
+
+      # @!attribute email
+      #   @return [String]
+      define_attribute :email, String
+
+      # @!attribute first_name
+      #   @return [String]
+      define_attribute :first_name, String
+
+      # @!attribute id
+      #   @return [String]
+      define_attribute :id, String
+
+      # @!attribute last_name
+      #   @return [String]
+      define_attribute :last_name, String
+
+      # @!attribute object
+      #   @return [String] Object type
+      define_attribute :object, String
+
+      # @!attribute time_zone
+      #   @return [String]
+      define_attribute :time_zone, String
+    end
+  end
+end

data/lib/recurly/resources.rb

@@ -0,0 +1,18 @@
+# Include all resource files
+resources = File.join(File.dirname(__FILE__), "resources", "*.rb")
+Dir.glob(resources, &method(:require))
+
+module Recurly
+  module Resources
+    class Empty < Resource
+    end
+
+    class Page < Resource
+      # leave data untyped
+      define_attribute :data, Array, item_type: Hash
+      define_attribute :has_more, :Boolean
+      define_attribute :next, String
+      define_attribute :object, String
+    end
+  end
+end

data/lib/recurly/schema/file_parser.rb

@@ -0,0 +1,13 @@
+module Recurly
+  # This is a wrapper class to help parse http response into Recurly objects.
+  class FileParser
+
+    # Parses the json body into a recurly object.
+    #
+    # @param body [String] The data string to cast.
+    # @return [Resource]
+    def self.parse(body)
+      Recurly::Resources::BinaryFile.cast(data: body)
+    end
+  end
+end

data/lib/recurly/schema/json_parser.rb

@@ -0,0 +1,72 @@
+require "json"
+
+module Recurly
+  # This is a wrapper class to help parse http response into Recurly objects.
+  class JSONParser
+
+    # Parses the json body into a recurly object.
+    #
+    # @param client [Client] The Recurly client which made the request.
+    # @param body [String] The JSON string to parse.
+    # @return [Resource]
+    def self.parse(client, body)
+      data = JSON.parse(body)
+      from_json(data).tap do |object|
+        object.client = client if object.requires_client?
+      end
+    end
+
+    # Converts the parsed JSON into a Recurly object.
+    #
+    # *TODO*: Instead of inferring this type from the `object`
+    # attribute. We should instead "register" the response type
+    # in the client/operations code. The `get`, `post`, etc methods
+    # could explicitly state their response types.
+    #
+    # @param data [Hash] The parsed JSON data
+    # @return [Error,Resource]
+    def self.from_json(data)
+      type = if data.has_key?("error")
+          "error_may_have_transaction"
+        else
+          data["object"]
+        end
+      klazz = self.recurly_class(type)
+
+      unless klazz
+        raise ArgumentError, "Unknown resource for json type #{type}"
+      end
+
+      data = data["error"] if klazz == Resources::ErrorMayHaveTransaction
+
+      klazz.cast(data)
+    end
+
+    # Returns the Recurly ruby class responsible for the Recurly json key.
+    #
+    # @example
+    #   JSONParser.recurly_class('list')
+    #   #=> Recurly::Page
+    # @example
+    #   JSONParser.recurly_class('shipping_address')
+    #   #=> Recurly::Resources::ShippingAddress
+    #
+    # @param type [String] The JSON key.
+    # @return [Resource,Pager,nil]
+    def self.recurly_class(type)
+      case type
+      when nil
+        nil
+      when "list"
+        Resources::Page
+      else
+        type_camelized = type.split("_").map(&:capitalize).join
+        if Resources.const_defined?(type_camelized, false)
+          Resources.const_get(type_camelized, false)
+        elsif Recurly::STRICT_MODE
+          raise ArgumentError, "Could not find Recurly Resource responsible for key #{type}"
+        end
+      end
+    end
+  end
+end

data/lib/recurly/schema/request_caster.rb

@@ -0,0 +1,60 @@
+require "date"
+
+module Recurly
+  class Schema
+    # *Note*: This module is for internal use.
+    # The RequestCaster turns mixed data into a pure Hash
+    # so it can be serialized into JSON and used as the body of a request.
+    # This module is to be extended by the Request class.
+    module RequestCaster
+
+      # This method casts the data object (of mixed types) into a Hash ready for JSON
+      # serialization. The *schema* will default to the self's schema.
+      # You should pass in the schema where possible. This is because objects are serialized
+      # differently depending on the context in which they are being written.
+      #
+      # @example
+      #   Recurly::Requests::AccountUpdatable.cast(code: 'benjamin')
+      #   #=> {:code=>"benjamin"}
+      # @example
+      #   # If you have some mixed data, like passing in an Address, it should cast that
+      #   # address into a Hash based on the Schema defined in AccountUpdatable
+      #   address = Recurly::Resources::Address.new(city: 'New Orleans')
+      #   Recurly::Requests::AccountUpdatable.cast(account_code: 'benjamin', address: address)
+      #   #=> {:account_code=>"benjamin", :address=>{:city=>"New Orleans"}}
+      #
+      # @param data [Hash,Resource,Request] The data to transform into a JSON Hash.
+      # @param schema [Schema] The schema to use to transform the data into a JSON Hash.
+      # @return [Hash] The pure Hash ready to be serialized into JSON.
+      def cast_request(data, schema = self.schema)
+        casted = {}
+        if data.is_a?(Resource) || data.is_a?(Request)
+          data = data.attributes.reject { |_k, v| v.nil? }
+        end
+
+        data.each do |k, v|
+          schema_attr = schema.get_attribute(k)
+          norm_val = if v.respond_to?(:attributes)
+              cast_request(v, v.class.schema)
+            elsif v.is_a?(Array)
+              v.map do |elem|
+                if elem.respond_to?(:attributes)
+                  cast_request(elem, elem.class.schema)
+                else
+                  elem
+                end
+              end
+            elsif v.is_a?(Hash) && schema_attr && schema_attr.is_a?(Schema::ResourceAttribute)
+              cast_request(v, schema_attr.recurly_class.schema)
+            else
+              v
+            end
+
+          casted[k] = norm_val
+        end
+
+        casted
+      end
+    end
+  end
+end

data/lib/recurly/schema/resource_caster.rb

@@ -0,0 +1,46 @@
+require "date"
+
+module Recurly
+  class Schema
+    # The purpose of this class is to turn JSON parsed Hashes
+    # defined into Recurly ruby objects. It's to be used
+    # by the Resource as an extension.
+    module ResourceCaster
+
+      # Gives the class the ability to initialize itself
+      # given some json data.
+      #
+      # @example
+      #   Recurly::Resources::Account.cast({"code" => "mycode"})
+      #   #=> #<Recurly::Resources::Account @attributes={:code=>"mycode"}>
+      #
+      # @param attributes [Hash] A primitive Hash from JSON.parse of Recurly response.
+      # @return [Resource] the {Resource} (ruby object) representing the passed in JSON data.
+      def cast(attributes = {})
+        resource = new()
+        attributes.each do |attr_name, val|
+          schema_attr = self.schema.get_attribute(attr_name)
+
+          if schema_attr
+            val = if val.nil?
+                val
+              elsif schema_attr.is_valid?(val)
+                schema_attr.cast(val)
+              else
+                if Recurly::STRICT_MODE
+                  msg = "#{self.class}##{attr_name} does not have the right type. Value: #{val.inspect} was expected to be a #{schema_attr}"
+                  raise ArgumentError, msg
+                end
+              end
+
+            writer = "#{attr_name}="
+            resource.send(writer, val)
+          elsif Recurly::STRICT_MODE
+            raise ArgumentError, "#{resource.class.name} encountered json attribute #{attr_name.inspect}: #{val.inspect} but it's unknown to it's schema"
+          end
+        end
+        resource
+      end
+    end
+  end
+end

data/lib/recurly/schema/schema_factory.rb

@@ -0,0 +1,48 @@
+module Recurly
+  class Schema
+    # A mixin that allows a class to be treated like a recurly
+    # object. This gives the class the power to describe
+    # it's schema. It adds the *define_attribute* method
+    # and a *schema* reader.
+    module SchemaFactory
+
+      # Gets the schema for this class
+      # @return [Schema]
+      def schema
+        @schema ||= ::Recurly::Schema.new
+      end
+
+      protected
+
+      # Macro that allows this class to define it's schema and associated
+      # attribute getters and setters.
+      #
+      # @example
+      #   class Account
+      #     extend Schema::SchemaFactory
+      #     define_attribute :code, String, {:read_only=>true}
+      #   end
+      #   account = Account.new(code: "mycode")
+      #   account.schema
+      #   #=> Recurly::Schema
+      #   acount.code = "newcode" # this method protected since read_only = true
+      #   account.code
+      #   #=> "mycode"
+      def define_attribute(name, type, options = {})
+        attribute = schema.add_attribute(name, type, options)
+
+        # Define the reader
+        define_method(name) do
+          self.attributes[name]
+        end
+
+        # Define the writer
+        define_method("#{name}=") do |val|
+          self.attributes[name] = val
+        end
+
+        self
+      end
+    end
+  end
+end

data/lib/recurly/schema/schema_validator.rb

@@ -0,0 +1,144 @@
+module Recurly
+  class Schema
+    # This module is responsible for validating that the raw data
+    # passed in to *attributes* matches the schema belonging to this class.
+    # It should be mixed in to the Request class.
+    module SchemaValidator
+      # Validates the attributes and throws an error if something is wrong.
+      #
+      # @example
+      #   Recurly::Requests::PlanCreate.new(code: 'plan123').validate!
+      #   #=> {:code=>"plan123"}
+      # @example
+      #   Recurly::Requests::PlanCreate.new(code: 3.14).validate!
+      #   #=> ArgumentError: Attribute 'code' on the resource Recurly::Requests::PlanCreate is type Float but should be a String.
+      # @example
+      #   Recurly::Requests::PlanCreate.new(kode: 'plan123').validate!
+      #   #=> ArgumentError: Attribute 'kode' does not exist on request Recurly::Requests::PlanCreate. Did you mean 'code'?
+      #
+      # @raise [ArgumentError] if the attribute data does not match the schema.
+      def validate!
+        attributes.each do |attr_name, val|
+          schema_attr = schema.get_attribute(attr_name)
+          if schema_attr.nil?
+            err_msg = "Attribute '#{attr_name}' does not exist on request #{self.class.name}."
+            if did_you_mean = get_did_you_mean(schema, attr_name)
+              err_msg << " Did you mean '#{did_you_mean}'?"
+            end
+            raise ArgumentError, err_msg
+          else
+            validate_attribute!(attr_name, schema_attr, val)
+          end
+        end
+      end
+
+      # Validates an individual attribute
+      def validate_attribute!(name, schema_attr, val)
+        unless val.nil? || schema_attr.is_valid?(val)
+          # If it's safely castable, the json deserializer or server
+          # will take care of it for us
+          unless safely_castable?(val.class, schema_attr.type)
+            expected = case schema_attr
+              when Schema::ArrayAttribute
+                "Array of #{schema_attr.type}s"
+              else
+                schema_attr.type
+              end
+
+            raise ArgumentError, "Attribute '#{name}' on the resource #{self.class.name} is type #{val.class} but should be a #{expected}"
+          end
+        end
+
+        # This is the convention for a recurly object
+        if schema_attr.is_a?(Schema::ResourceAttribute) && val.is_a?(Hash)
+          # Using send because the initializer may be private
+          instance = schema_attr.recurly_class.send(:new, val)
+          instance.validate!
+        end
+      end
+
+      # Gets the closest term to the misspelled attribute
+      def get_did_you_mean(schema, misspelled_attr)
+        closest = schema.attributes.keys.sort_by do |v|
+          levenshtein_distance(v, misspelled_attr)
+        end.first
+
+        if closest && levenshtein_distance(closest, misspelled_attr) <= 4
+          closest
+        end
+      end
+
+      private
+
+      def safely_castable?(from_type, to_type)
+        # TODO we can drop this switch when 2.3 support is dropped
+        int_class = if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("2.4.0")
+            :Integer
+          else
+            :Fixnum
+          end
+        int_class = Kernel.const_get(int_class)
+
+        case [from_type, to_type]
+        when [Symbol, String]
+          true
+        when [int_class, Float]
+          true
+        else
+          false
+        end
+      end
+
+      # This code is copied directly from the did_you mean gem which is based
+      # directly on the Text gem implementation.
+      #
+      # did_you_mean: Copyright (c) 2014-2016 Yuki Nishijima.
+      # Text:         Copyright (c) 2006-2013 Paul Battley, Michael Neumann, Tim Fletcher.
+      #
+      # Returns a value representing the "cost" of transforming str1 into str2
+      def levenshtein_distance(str1, str2)
+        str1 = str1.to_s unless str1.is_a? String
+        str2 = str2.to_s unless str2.is_a? String
+        n = str1.length
+        m = str2.length
+        return m if n.zero?
+        return n if m.zero?
+
+        d = (0..m).to_a
+        x = nil
+
+        # to avoid duplicating an enumerable object, create it outside of the loop
+        str2_codepoints = str2.codepoints
+
+        str1.each_codepoint.with_index(1) do |char1, i|
+          j = 0
+          while j < m
+            cost = (char1 == str2_codepoints[j]) ? 0 : 1
+            x = min3(
+              d[j + 1] + 1, # insertion
+              i + 1,      # deletion
+              d[j] + cost # substitution
+            )
+            d[j] = i
+            i = x
+
+            j += 1
+          end
+          d[m] = x
+        end
+
+        x
+      end
+
+      def min3(a, b, c)
+        if a < b && a < c
+          a
+        elsif b < c
+          b
+        else
+          c
+        end
+      end
+    end
+  end
+end