recurly 2.18.22 → 3.0.0.beta.1

data/lib/recurly/resources/subscription_add_on.rb

@@ -0,0 +1,42 @@
+module Recurly
+  module Resources
+    class SubscriptionAddOn < Resource
+
+      # @!attribute add_on
+      #   @return [AddOnMini]
+      define_attribute :add_on, :AddOnMini
+
+      # @!attribute created_at
+      #   @return [DateTime] Created at
+      define_attribute :created_at, DateTime
+
+      # @!attribute expired_at
+      #   @return [DateTime] Expired at
+      define_attribute :expired_at, DateTime
+
+      # @!attribute id
+      #   @return [String] Subscription Add-on ID
+      define_attribute :id, String
+
+      # @!attribute object
+      #   @return [String] Object type
+      define_attribute :object, String
+
+      # @!attribute quantity
+      #   @return [Integer] Add-on quantity
+      define_attribute :quantity, Integer
+
+      # @!attribute subscription_id
+      #   @return [String] Subscription ID
+      define_attribute :subscription_id, String
+
+      # @!attribute unit_amount
+      #   @return [Float] This is priced in the subscription's currency.
+      define_attribute :unit_amount, Float
+
+      # @!attribute updated_at
+      #   @return [DateTime] Updated at
+      define_attribute :updated_at, DateTime
+    end
+  end
+end

data/lib/recurly/resources/subscription_change.rb

@@ -0,0 +1,54 @@
+module Recurly
+  module Resources
+    class SubscriptionChange < Resource
+
+      # @!attribute [r] activate_at
+      #   @return [DateTime] Activated at
+      define_attribute :activate_at, DateTime, {:read_only => true}
+
+      # @!attribute activated
+      #   @return [Boolean] Returns `true` if the subscription change is activated.
+      define_attribute :activated, :Boolean
+
+      # @!attribute add_ons
+      #   @return [Array[SubscriptionAddOn]] These add-ons will be used when the subscription renews.
+      define_attribute :add_ons, Array, {:item_type => :SubscriptionAddOn}
+
+      # @!attribute [r] created_at
+      #   @return [DateTime] Created at
+      define_attribute :created_at, DateTime, {:read_only => true}
+
+      # @!attribute [r] deleted_at
+      #   @return [DateTime] Deleted at
+      define_attribute :deleted_at, DateTime, {:read_only => true}
+
+      # @!attribute id
+      #   @return [String] The ID of the Subscription Change.
+      define_attribute :id, String
+
+      # @!attribute object
+      #   @return [String] Object type
+      define_attribute :object, String
+
+      # @!attribute plan
+      #   @return [PlanMini]
+      define_attribute :plan, :PlanMini
+
+      # @!attribute quantity
+      #   @return [Integer] Subscription quantity
+      define_attribute :quantity, Integer
+
+      # @!attribute subscription_id
+      #   @return [String] The ID of the subscription that is going to be changed.
+      define_attribute :subscription_id, String
+
+      # @!attribute unit_amount
+      #   @return [Float] Unit amount
+      define_attribute :unit_amount, Float
+
+      # @!attribute [r] updated_at
+      #   @return [DateTime] Updated at
+      define_attribute :updated_at, DateTime, {:read_only => true}
+    end
+  end
+end

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/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

data/lib/recurly/schema/request_caster.rb

@@ -0,0 +1,66 @@
+require 'date'
+
+module Recurly
+  class Schema
+    # *Note*: This class 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(account_code: 'benjamin')
+      #   #=> {:account_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(data, schema=self.schema)
+        casted = {}
+        if data.is_a?(Resource) || data.is_a?(Request)
+          data = as_json(data, schema)
+        end
+
+        data.each do |k,v|
+          schema_attr = schema.get_attribute(k)
+          norm_val = if v.respond_to?(:attributes)
+                       cast(v, schema_attr.recurly_class.schema)
+                     elsif v.is_a?(Array)
+                       v.map do |elem|
+                         if elem.respond_to?(:attributes)
+                           cast(elem, schema_attr.recurly_class.schema)
+                         else
+                           elem
+                         end
+                       end
+                     elsif v.is_a?(Hash) && schema_attr.type.is_a?(Symbol)
+                       cast(v, schema_attr.recurly_class.schema)
+                     else
+                       v
+                     end
+
+          casted[k] = norm_val
+        end
+
+        casted
+      end
+
+      private
+
+      def as_json(resource, schema)
+        writeable_attributes = schema.attributes.reject(&:read_only?).map(&:name)
+        resource.attributes.select { |k,_| writeable_attributes.include?(k) }
+      end
+    end
+  end
+end

data/lib/recurly/schema/schema_factory.rb

@@ -0,0 +1,50 @@
+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
+
+        protected "#{name}=" if attribute.read_only?
+
+        self
+      end
+    end
+  end
+end