recurly 2.18.15 → 3.0.0.beta.1

data/lib/recurly/resources/tax_info.rb

@@ -0,0 +1,18 @@
+module Recurly
+  module Resources
+    class TaxInfo < Resource
+
+      # @!attribute rate
+      #   @return [Float] Rate
+      define_attribute :rate, Float
+
+      # @!attribute region
+      #   @return [String] Provides the tax region applied on an invoice. For U.S. Sales Tax, this will be the 2 letter state code. For EU VAT this will be the 2 letter country code. For all country level tax types, this will display the regional tax, like VAT, GST, or PST.
+      define_attribute :region, String
+
+      # @!attribute type
+      #   @return [String] Provides the tax type as "vat" for EU VAT, "usst" for U.S. Sales Tax, or the 2 letter country code for country level tax types like Canada, Australia, New Zealand, Israel, and all non-EU European countries.
+      define_attribute :type, String
+    end
+  end
+end

data/lib/recurly/resources/transaction.rb

@@ -0,0 +1,146 @@
+module Recurly
+  module Resources
+    class Transaction < Resource
+
+      # @!attribute account
+      #   @return [AccountMini]
+      define_attribute :account, :AccountMini
+
+      # @!attribute amount
+      #   @return [Float] Total transaction amount sent to the payment gateway.
+      define_attribute :amount, Float
+
+      # @!attribute avs_check
+      #   @return [String] When processed, result from checking the overall AVS on the transaction.
+      define_attribute :avs_check, String, {:enum => ["A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "M", "N", "O", "P", "Q", "R", "S", "T", "U", "V", "W", "X", "Y", "Z"]}
+
+      # @!attribute billing_address
+      #   @return [Address]
+      define_attribute :billing_address, :Address
+
+      # @!attribute collected_at
+      #   @return [DateTime] Collected at, or if not collected yet, the time the transaction was created.
+      define_attribute :collected_at, DateTime
+
+      # @!attribute created_at
+      #   @return [DateTime] Created at
+      define_attribute :created_at, DateTime
+
+      # @!attribute currency
+      #   @return [String] 3-letter ISO 4217 currency code.
+      define_attribute :currency, String
+
+      # @!attribute customer_message
+      #   @return [String] For declined (`success=false`) transactions, the message displayed to the customer.
+      define_attribute :customer_message, String
+
+      # @!attribute customer_message_locale
+      #   @return [String] Language code for the message
+      define_attribute :customer_message_locale, String
+
+      # @!attribute cvv_check
+      #   @return [String] When processed, result from checking the CVV/CVC value on the transaction.
+      define_attribute :cvv_check, String, {:enum => ["D", "I", "M", "N", "P", "S", "U", "X"]}
+
+      # @!attribute gateway_approval_code
+      #   @return [String] Transaction approval code from the payment gateway.
+      define_attribute :gateway_approval_code, String
+
+      # @!attribute gateway_message
+      #   @return [String] Transaction message from the payment gateway.
+      define_attribute :gateway_message, String
+
+      # @!attribute gateway_reference
+      #   @return [String] Transaction reference number from the payment gateway.
+      define_attribute :gateway_reference, String
+
+      # @!attribute gateway_response_code
+      #   @return [String] For declined transactions (`success=false`), this field lists the gateway error code.
+      define_attribute :gateway_response_code, String
+
+      # @!attribute gateway_response_time
+      #   @return [Integer] Time, in seconds, for gateway to process the transaction.
+      define_attribute :gateway_response_time, Integer
+
+      # @!attribute gateway_response_values
+      #   @return [Hash] The values in this field will vary from gateway to gateway.
+      define_attribute :gateway_response_values, Hash
+
+      # @!attribute id
+      #   @return [String] Transaction ID
+      define_attribute :id, String
+
+      # @!attribute invoice
+      #   @return [InvoiceMini]
+      define_attribute :invoice, :InvoiceMini
+
+      # @!attribute ip_address_country
+      #   @return [String] IP address's country
+      define_attribute :ip_address_country, String
+
+      # @!attribute ip_address_v4
+      #   @return [String] IP address provided when the billing information was collected:  - When the customer enters billing information into the Recurly.JS or Hosted Payment Pages, Recurly records the IP address. - When the merchant enters billing information using the API, the merchant may provide an IP address. - When the merchant enters billing information using the UI, no IP address is recorded.
+      define_attribute :ip_address_v4, String
+
+      # @!attribute object
+      #   @return [String] Object type
+      define_attribute :object, String
+
+      # @!attribute origin
+      #   @return [String] Describes how the transaction was triggered.
+      define_attribute :origin, String, {:enum => ["api", "hpp", "merchant", "recurly_admin", "recurlyjs", "recurring", "transparent", "force_collect", "refunded_externally", "chargeback"]}
+
+      # @!attribute original_transaction_id
+      #   @return [String] If this transaction is a refund (`type=refund`), this will be the ID of the original transaction on the invoice being refunded.
+      define_attribute :original_transaction_id, String
+
+      # @!attribute payment_gateway
+      #   @return [Hash]
+      define_attribute :payment_gateway, Hash
+
+      # @!attribute payment_method
+      #   @return [Hash] Payment method (TODO: this overlaps with BillinInfo’s payment_method but only documents credit cards)
+      define_attribute :payment_method, Hash
+
+      # @!attribute refunded
+      #   @return [Boolean] Indicates if part or all of this transaction was refunded.
+      define_attribute :refunded, :Boolean
+
+      # @!attribute status
+      #   @return [String] The current transaction status. Note that the status may change, e.g. a `pending` transaction may become `declined` or `success` may later become `void`.
+      define_attribute :status, String, {:enum => ["pending", "scheduled", "processing", "success", "void", "declined", "error", "chargeback"]}
+
+      # @!attribute status_code
+      #   @return [String] Status code
+      define_attribute :status_code, String
+
+      # @!attribute status_message
+      #   @return [String] For declined (`success=false`) transactions, the message displayed to the merchant.
+      define_attribute :status_message, String
+
+      # @!attribute subscription_ids
+      #   @return [Array[String]] If the transaction is charging or refunding for one or more subscriptions, these are their IDs.
+      define_attribute :subscription_ids, Array, {:item_type => String}
+
+      # @!attribute success
+      #   @return [Boolean] Did this transaction complete successfully?
+      define_attribute :success, :Boolean
+
+      # @!attribute type
+      #   @return [String] Transaction type
+      define_attribute :type, String, {:enum => ["authorization", "capture", "purchase", "refund", "verify"]}
+
+      # @!attribute uuid
+      #   @return [String] The UUID is useful for matching data with the CSV exports and building URLs into Recurly's UI.
+      define_attribute :uuid, String
+
+      # @!attribute voided_at
+      #   @return [DateTime] Voided at
+      define_attribute :voided_at, DateTime
+
+      # @!attribute voided_by_invoice
+      #   @return [InvoiceMini]
+      define_attribute :voided_by_invoice, :InvoiceMini
+    end
+  end
+end

data/lib/recurly/resources/unique_coupon_code.rb

@@ -0,0 +1,38 @@
+module Recurly
+  module Resources
+    class UniqueCouponCode < Resource
+
+      # @!attribute code
+      #   @return [String] The code the customer enters to redeem the coupon.
+      define_attribute :code, String
+
+      # @!attribute [r] created_at
+      #   @return [DateTime] Created at
+      define_attribute :created_at, DateTime, {:read_only => true}
+
+      # @!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 [r] id
+      #   @return [String] Unique Coupon Code ID
+      define_attribute :id, String, {:read_only => true}
+
+      # @!attribute [r] object
+      #   @return [String] Object type
+      define_attribute :object, String, {:read_only => true}
+
+      # @!attribute [r] redeemed_at
+      #   @return [DateTime] The date and time the unique coupon code was redeemed.
+      define_attribute :redeemed_at, DateTime, {:read_only => true}
+
+      # @!attribute state
+      #   @return [String] Indicates if the unique coupon code is redeemable or why not.
+      define_attribute :state, String, {:enum => ["redeemable", "maxed_out", "expired", "inactive"]}
+
+      # @!attribute [r] updated_at
+      #   @return [DateTime] Updated at
+      define_attribute :updated_at, DateTime, {:read_only => true}
+    end
+  end
+end

data/lib/recurly/resources/user.rb

@@ -0,0 +1,38 @@
+module Recurly
+  module Resources
+    class User < Resource
+
+      # @!attribute [r] created_at
+      #   @return [DateTime]
+      define_attribute :created_at, DateTime, {:read_only => true}
+
+      # @!attribute [r] deleted_at
+      #   @return [DateTime]
+      define_attribute :deleted_at, DateTime, {:read_only => true}
+
+      # @!attribute email
+      #   @return [String]
+      define_attribute :email, String
+
+      # @!attribute first_name
+      #   @return [String]
+      define_attribute :first_name, String
+
+      # @!attribute [r] id
+      #   @return [String]
+      define_attribute :id, String, {:read_only => true}
+
+      # @!attribute last_name
+      #   @return [String]
+      define_attribute :last_name, String
+
+      # @!attribute [r] object
+      #   @return [String] Object type
+      define_attribute :object, String, {:read_only => true}
+
+      # @!attribute time_zone
+      #   @return [String]
+      define_attribute :time_zone, String
+    end
+  end
+end

data/lib/recurly/schema.rb

@@ -0,0 +1,114 @@
+module Recurly
+  # The class responsible for describing a schema.
+  # This is used for requests and resources.
+  class Schema
+    # The attributes in the schema
+    # @return [Array<Attribute>]
+    attr_reader :attributes
+
+    def initialize
+      @attributes = []
+    end
+
+    # Adds an attribute to the schema definition
+    #
+    # @param name [Symbol] The name of the attribute
+    # @param type [Class,Symbol] The type of the attribute. Use capitalized symbol for Recurly class. Example: :Account.
+    # @param options [Hash] The attribute options. See {Attribute#options}
+    def add_attribute(name, type, options)
+      attribute = Attribute.new(name, type, options)
+      @attributes.push(attribute)
+      attribute
+    end
+
+    # Gets an attribute from this schema given a name
+    #
+    # @param name [String,Symbol] The name/key of the attribute
+    # @return [Attribute,nil] The found Attribute. nil if not found.
+    def get_attribute(name)
+      name = name.to_s
+      @attributes.find { |a| a.name.to_s == name }
+    end
+
+    # Gets a recurly class given a symbol name.
+    #
+    # @example
+    #   Schema.get_recurly_class(:Account)
+    #   #=> Recurly::Resources::Account
+    #
+    # @param type [Symbol] The name of the class you wish to find
+    # @return [Request,Resource]
+    # @raise ArgumentError If class can't be found.
+    def self.get_recurly_class(type)
+      raise ArgumentError, "#{type.inspect} must be a symbol but is a #{type.class}" unless type.is_a?(Symbol)
+
+      if Requests.const_defined?(type)
+        Requests.const_get(type)
+      elsif Resources.const_defined?(type)
+        Resources.const_get(type)
+      else
+        raise ArgumentError, "Recurly type '#{type}' is unknown"
+      end
+    end
+
+    # Describes a list attribute type
+    class List
+      # The type of the elements of the list
+      # @return [Symbol]
+      attr_accessor :item_type
+
+      def initialize(item_type)
+        @item_type = item_type
+      end
+
+      def to_s
+        "List<#{item_type}>"
+      end
+    end
+
+    # Describes and attribute for a schema.
+    class Attribute
+      # The name of the attribute.
+      # @return [Symbol]
+      attr_accessor :name
+
+      # The type of the attribute. Might be a class like `DateTime`
+      # or could be a Recurly object. In this case a symbol should be used.
+      # Example: :Account
+      # @return [Class,Symbol]
+      attr_accessor :type
+
+      # Options for the attribute.
+      # @return [Hash]
+      attr_accessor :options
+
+      # The description of the attribute for documentation.
+      # @return [String]
+      attr_accessor :description
+
+      def initialize(name, type, options={}, description=nil)
+        @name = name
+        @type = type
+        @options = options
+        @description = description
+      end
+
+      def read_only?
+        @options.fetch(:read_only, false)
+      end
+
+      def recurly_class
+        Schema.get_recurly_class(type == Array ? options[:item_type] : type)
+      end
+    end
+
+    private_constant :List
+    private_constant :Attribute
+  end
+
+
+  require_relative './schema/schema_factory'
+  require_relative './schema/schema_validator'
+  require_relative './schema/json_deserializer'
+  require_relative './schema/request_caster'
+end

data/lib/recurly/schema/json_deserializer.rb

@@ -0,0 +1,53 @@
+require 'date'
+
+module Recurly
+  class Schema
+    # The purpose of this class is to turn Recurly defined
+    # JSON data into Recurly ruby objects. It's to be used
+    # by the Resource as an extension.
+    module JsonDeserializer
+      # Gives the class the ability to initialize itself
+      # given some json data.
+      #
+      # @example
+      #   Recurly::Resources::Account.from_json({"code" => "mycode"})
+      #   #=> #<Recurly::Resources::Account @attributes={:code=>"mycode"}>
+      #
+      # @param attributes [Hash] A primitive Hash from JSON.parse of Recurly result.
+      # @return [Resource] the {Resource} (ruby object) representing the passed in JSON data.
+      def from_json(attributes = {})
+        resource = new()
+        attributes.each do |attr_name, val|
+          next if attr_name == 'object'
+
+          # if the Hash val is a recurly type, parse it into a Resource
+          if val.is_a?(Hash) && klazz = JSONParser.recurly_class(val['object'])
+            val = klazz.from_json(val)
+          elsif val.is_a?(Array)
+            val = val.map do |e|
+              if e.is_a?(Hash) && klazz = JSONParser.recurly_class(e['object'])
+                klazz.from_json(e)
+              else
+                e
+              end
+            end
+          elsif attr_name.end_with?("_at") && val && val.is_a?(String)
+            # TODO should use the schema to determine this probably
+            val = DateTime.parse(val)
+          end
+
+          writer = "#{attr_name}="
+
+          # TODO maybe check for protected writer first?
+          begin
+            resource.send(writer, val)
+          rescue => e
+            # TODO ignoring these missing fields for now
+            puts e
+          end
+        end
+        resource
+      end
+    end
+  end
+end

data/lib/recurly/schema/json_parser.rb

@@ -0,0 +1,71 @@
+require 'json'
+
+module Recurly
+  # This is a wrapper class to help parse responses 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.
+    #
+    # @param data [Hash] The parsed JSON data
+    # @return [Error,Resource]
+    def self.from_json(data)
+      type = if data.has_key?("error")
+               "error"
+             else
+               data.delete('object')
+             end
+      klazz = self.recurly_class(type)
+
+      unless klazz
+        raise ArgumentError, "Unknown resource for json type #{type}"
+      end
+
+      data = data["error"] if klazz == Resources::Error
+
+      klazz.from_json(data)
+    end
+
+    # Returns the Recurly ruby class responsible for the Recurly json key.
+    # TODO figure out how we should handle nil types
+    #
+    # @example
+    #   JSONParser.recurly_class('list')
+    #   #=> Recurly::Pager
+    # @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'
+        Pager
+      else
+        type_camelized = type.split('_').map(&:capitalize).join
+        if Resources.const_defined?(type_camelized)
+          klazz = Resources.const_get(type_camelized)
+          if klazz.ancestors.include?(Resource)
+            klazz
+          else
+            # TODO might want to throw an error?
+            nil
+          end
+        end
+      end
+    end
+  end
+end