reg.api2 0.0.1 → 0.0.2

data/lib/reg_api2/request_contract.rb

@@ -0,0 +1,106 @@
+# -*- encoding : utf-8 -*-
+require 'ipaddr'
+
+module RegApi2
+  # Contract for API requests.
+  # Checks for specified `required` fields.
+  # Also checks for `optional` fields.
+  # Take in care :re option.
+  class RequestContract
+
+    # Options of contract.
+    # @return [Hash] Options hash.
+    attr_reader :opts
+
+    def initialize(opts = {})
+      @opts = opts
+    end
+
+    # Normalizes `required` and `optional` fields to the form of Hash with options.
+    # @param [NilClass,Hash,Array, etc.] arr Something to normalize.
+    def to_hash arr
+      return {}   if arr.nil?
+      return arr  if arr.kind_of?(Hash)
+      arr = [ arr.to_sym ]  unless arr.kind_of?(Array)
+      ret = {}
+      arr.each { |key| ret[key.to_sym] = {} }
+      ret
+    end
+
+    # Gets fields to validate
+    # @return [Hash] Fields to validate.
+    def fields_to_validate
+      required_fields = to_hash opts[:required]
+      optional_fields = to_hash opts[:optional]
+      required_fields.keys.each { |key| required_fields[key][:required] = true }
+      optional_fields.merge(required_fields)
+    end
+
+    # Validates specified `value` with `re` field.
+    # @param [Object] key Value to validate.
+    # @param [Object] value Value to validate.
+    # @param [Hash] opts opts with optional re field.
+    # @raise ContractError
+    def validate_re key, value, opts
+      if opts[:re]
+        if value.to_s !~ opts[:re]
+          raise RegApi2::ContractError.new(
+            "Field #{key} mismatch regular expression: #{value}",
+            [ key ]
+          )
+        end
+      end
+      value
+    end
+
+    # Validates specified `value` with `re` field.
+    # @param [Object] key Value to validate.
+    # @param [Object] value Value to validate.
+    # @param [Hash] opts opts with optional re field.
+    def validate_iso_date key, value, opts
+      if opts[:iso_date]
+        return value.strftime("%Y-%m-%d")  if value.respond_to?(:strftime)
+      end
+      value
+    end
+
+    # Validates specified `value` with `ipaddr` field.
+    # @param [Object] key Value to validate.
+    # @param [Object] value Value to validate.
+    # @param [Hash] opts opts with optional ipaddr field.
+    def validate_ipaddr key, value, opts
+      if opts[:ipaddr] == true && value.kind_of?(String)
+        value = IPAddr.new(value)
+      end
+      value.to_s
+    end
+
+    # Validates specified `form` with `required` and `optional` fields.
+    # @param [Hash] form Form to validate.
+    # @raise ContractError
+    def validate(form)
+      fields = fields_to_validate
+      return form  if fields.empty?
+      absent_fields = []
+      fields.each_pair do |key, opts|
+        if !form.has_key?(key) || form[key].nil?
+          if opts[:required]
+            absent_fields << key
+          end
+          next
+        end
+
+        form[key] = validate_re key, form[key], opts
+        form[key] = validate_iso_date key, form[key], opts
+        form[key] = validate_ipaddr key, form[key], opts
+      end
+      unless absent_fields.empty?
+        raise RegApi2::ContractError.new(
+          "Required fields missed: #{absent_fields.join(', ')}",
+          absent_fields
+        )
+      end
+      form
+    end
+  end
+end

data/lib/reg_api2/result_contract.rb

@@ -0,0 +1,118 @@
+# -*- encoding : utf-8 -*-
+
+require 'reg_api2/sym_hash'
+
+module RegApi2
+  # Contract for API results.
+  # Waits for answer field and returns it only by default.
+  # @see SymHash
+  class ResultContract
+    # Fields that will be converted to {Fixnum}.
+    # @see #convert
+    INT_FIELDS = %w[
+      active_domains_cnt
+      active_domains_get_ctrl_cnt
+      domain_folders_cnt
+      renew_domains_cnt
+      renew_domains_get_ctrl_cnt
+      undelegated_domains_cnt
+      bill_id
+    ].freeze
+
+    # Fields that will be converted to {Float}.
+    # @see #convert
+    FLOAT_FIELDS = %w[
+      amount
+      total_amount
+      payment
+      total_payment
+    ].freeze
+
+    # Fields that will be converted to {Boolean}.
+    # @see #convert
+    BOOL_FIELDS = %w[
+      success
+    ].freeze
+
+    # Options of contract.
+    # @return [Hash] Options hash.
+    attr_reader :opts
+
+    def initialize(opts = {})
+      @opts = opts
+    end
+
+    # Extracts answer field and returns it wrapped by {#handle_answer}.
+    # Result is unified using {SymHash.from}.
+    # @param [Hash] result API result.
+    # @return Reworked API answer field.
+    # @see SymHash
+    def handle_result(result)
+      result = SymHash.from(result)
+      handle_answer(result[:answer])
+    end
+
+    def convert_hash(answer)
+      answer.each_pair do |key, value|
+        case value
+        when String
+          if INT_FIELDS.include?(key.to_s)
+            answer[key] = value.to_i
+          elsif FLOAT_FIELDS.include?(key.to_s)
+            answer[key] = value.to_f
+          elsif BOOL_FIELDS.include?(key.to_s)
+            answer[key] = value.to_i.nonzero? ? true : false
+          end
+        when Hash
+          answer[key] = convert_hash(value)
+        when Array
+          answer[key] = convert_array(value)
+        end
+      end
+      answer
+    end
+
+    def convert_array(answer)
+      answer.map do |value|
+        case value
+        when Hash
+          convert_hash(value)
+        when Array
+          convert_array(value)
+        else
+          value
+        end
+      end
+    end
+
+    # Reworks answer to translate {INT_FIELDS}, {FLOAT_FIELDS} and {BOOL_FIELDS}.
+    # @param answer API answer field.
+    # @return Translated answer.
+    def convert(answer)
+      case answer
+      when Hash
+        convert_hash(answer)
+      when Array
+        convert_array(answer)
+      else
+        answer
+      end
+    end
+ 
+    # Handles API answer. Take in care `:field` option.
+    # @param answer API answer field.
+    # @return Converted answer by default.
+    # @see #convert
+    # @see #opts
+    def handle_answer(answer)
+      answer = convert(answer)
+      field = opts[:field]
+      if field
+        answer = answer[field]
+      end
+      answer
+    end
+
+    private :convert_array, :convert_hash
+  end
+end

data/lib/reg_api2/service.rb

@@ -8,9 +8,9 @@ module RegApi2
     category :service
 
     # @!method nop(opts = {})
+    # Return list of specified services with its stats if specified.
     # @param opts
     # @option opts [Array] services
-    # Return list of specified services with its stats if specified.
     # @return [Hash("services" => [])]
     # @example List of services by specified identifiers
     #  RegApi2.service.nop(services: [
@@ -22,6 +22,127 @@ module RegApi2
     #  ])
     define :nop
 
+    # @!method get_prices(opts = {})
+    # Get services registration/renewal prices.
+    # @param opts
+    # @option opts [Boolean] :show_renew_data With this flag enabled the system will return the price of renewal (1/0). Optional field.
+    # @option opts [String, Symbol] :currency Identifier of the currency in which the prices will be quoted: rur (default), uah, usd, eur. Optional field.
+    # @return [Hash(currency, price_group, show_renew_data, prices)] Prices.
+    # @example Get prices.
+    #    RegApi2.service.get_prices
+    define :get_prices
+
+    # @!method get_servtype_details(opts = {})
+    # Use this function to get prices for services and general data.
+    # @note To obtain prices for several service types, you can define them in the servtype field delimiting them with commas or include several servtype fields into the request. In this case the field subtype is ignored.
+    # @param opts
+    # @option opts [String, Symbol] :servtype Type of service: srv_webfwd — web forwarding, srv_parking — domain parking, srv_dns_both — DNS support, srv_hosting_ispmgr — hosting, srv_certificate — domain certificate, srv_voucher — domain voucher, srv_kvm — KVM access.
+    # @option opts [String, Symbol] :subtype Service subtype.
+    # @option opts [Boolean] :unroll_prices Show prices in expanded form.
+    # @return [Array(Hash(commonname, ...))] Service type details.
+    # @example Get service type details.
+    #    RegApi2.service.get_servtype_details servtype: :srv_hosting_ispmgr
+    define :get_servtype_details
+
+
+    # @!method create(opts = {})
+    # Use the function to order new services.
+    # `servtype` values are supported:
+    #
+    # | servtype | service type |
+    # | ---------|--------------|
+    # | srv_webfwd | web forwarding |
+    # | srv_parking | domain parking |
+    # | srv_dns_both | DNS support |
+    # | srv_hosting_ispmgr | ISPManager hosting |
+    # | srv_hosting_cpanel | CPanel hosting |
+    # | srv_hosting_plesk | PLesk hosting |
+    # | srv_ssl_certificate | SSL certificate |
+    # | srv_certificate | Domain certificate |
+    # | srv_voucher | Domain voucher |
+    # | srv_vps | VPS server |
+    # | srv_license_isp | ISP Manager license |
+    # | srv_addip | additional IP address |
+    # | srv_disk_space | additional disk space |
+    # | srv_antispam | advanced spam protection |
+    # | srv_dedicated | dedicated server |
+    # | srv_kvm | KVM access |
+    #
+    # Common payment options are allowed.
+    # folder_name or folder_id are allowed.
+    # @option opts [String] :domain_name Name of the domain, for which the service is ordered.
+    # @option opts [String, Symbol] :servtype The type of the ordered service.
+    # @option opts [Object] :period The period for which the service is ordered, the unit of measurement (year or month) depends on the type of the service being ordered. To learn about the measurement units used for each service, use the {#get_servtype_details} function.
+    # @option opts [String] :user_servid Domain ID set by the user. Allowed symbols: digits (from 0 through 9), Latin letters (from a through f). Maximum length: 32 symbols. This ID cannot be generated automatically; if it is not defined upon service ordering, the field will be empty. Optional field.
+    # @option opts :point_of_sale See common payment parameters in {file:README.md}.
+    # @option opts :pay_type See common payment parameters in {file:README.md}.
+    # @option opts :ok_if_no_money See common payment parameters in {file:README.md}.
+    # @option opts :folder_name Defines the name of the folder, to which the services will be added (see the list of common folder identification parameters in {file:README.md}).
+    # @option opts :folder_id Defines the name of the folder, to which the services will be added (see the list of common folder identification parameters in {file:README.md}).
+    # @option opts [Boolean] :no_new_folder Dont't create non-existing folder; otherwise create if not exists.
+    # @option opts [String] :comment An arbitrary text describing the order. Optional field.
+    # @option opts [String] :admin_comment A comment for administrators. An arbitrary text describing the order. Optional field.
+    # TODO: specific options.
+    # @return [Hash(descr, service_id, ...)] Information about ordered service.
+    # @see #get_servtype_details
+    # @example Create srv_hosting_ispmgr service.
+    #    RegApi2.service.create dname: 'qqq.ru', servtype: :srv_hosting_ispmgr, period: 1, plan: 'Host-2-1209'
+    define :create, required: %w[ servtype ]
+
+    # @!method delete(opts = {})
+    define :delete, required: %w[ servtype ]
+
+    # @!method get_info(opts = {})
+    define :get_info
+
+    # @!method get_list(opts = {})
+    define :get_list
+
+    # @!method get_folders(opts = {})
+    define :get_folders
+
+    # @!method get_details(opts = {})
+    define :get_details
+
+    # @!method service_get_details(opts = {})
+    define :service_get_details
+
+    # @!method get_dedicated_server_list(opts = {})
+    define :get_dedicated_server_list
+
+    # @!method update(opts = {})
+    define :update
+
+    # @!method renew(opts = {})
+    define :renew
+
+    # @!method get_bills(opts = {})
+    define :get_bills
+
+    # @!method set_autorenew_flag(opts = {})
+    define :set_autorenew_flag
+
+    # @!method suspend(opts = {})
+    define :suspend
+
+    # @!method resume(opts = {})
+    define :resume
+
+    # @!method get_depreciated_period(opts = {})
+    define :get_depreciated_period
+
+    # @!method upgrade(opts = {})
+    define :upgrade
+
+    # @!method partcontrol_grant(opts = {})
+    define :partcontrol_grant
+
+    # @!method partcontrol_revoke(opts = {})
+    define :partcontrol_revoke
+
+    # @!method resend_mail(opts = {})
+    define :resend_mail
+
     extend self
   end
 end

data/lib/reg_api2/sym_hash.rb

@@ -0,0 +1,63 @@
+module RegApi2
+  # Hash with indifferent access to its elements.
+  # Also have no difference between {String} ans {Symbol} keys. 
+  # @see ResultContract
+  class SymHash < Hash
+    # Forms data with indifferent access from specified source.
+    # @return [Object] Data with indifferent access
+    def self.from(source)
+      case source
+      when Hash
+        res = SymHash.new
+        source.each_pair do |key, value|
+          res[key] = self.from(value)
+        end
+        res
+      when Array
+        source.map do |el|
+          self.from(el)
+        end
+      else
+        source
+      end
+    end
+
+    # Returns true if the given key is present in hsh.
+    def has_key?(key)
+      key.kind_of?(Symbol) ? self.has_key?(key.to_s) : super(key)
+    end
+
+    # Returns true if the given key is present in hsh.
+    def include?(key)
+      has_key?(key)
+    end
+
+    # Element Reference — Retrieves the value object corresponding to the key object. If not found, returns the default value (see {Hash::new} for details).
+    def [](key)
+      key.kind_of?(Symbol) ? self[key.to_s] : super(key)
+    end
+
+    # Element Assignment — Associates the value given by value with the key given by key. key should not have its value changed while it is in use as a key (a String passed as a key will be duplicated and frozen).
+    def []=(key, new_value)
+      key.kind_of?(Symbol) ? self[key.to_s]=new_value : super(key, new_value)
+    end
+
+    # Always true
+    def respond_to?(key)
+      true
+    end
+
+    # Sets or gets field in the hash.
+    def method_missing(key, *args, &block)
+      if key.to_s =~ /\A(.+)=\z/
+        self[$1] = args.first
+        return args.first
+      end
+      if key.to_s =~ /\A(.+)\?\z/
+        return !!self[$1]
+      end
+      return self[key]  if has_key?(key)
+      nil
+    end
+  end
+end

data/lib/reg_api2/user.rb

@@ -25,7 +25,7 @@ module RegApi2
     # @return [String] user_id of new user.
     # @note Accessability: partners
     # New user registration.
-    define :create, required: %w[ user_login user_password user_email user_country_code ], field: 'user_id', result: :single_field
+    define :create, required: %w[ user_login user_password user_email user_country_code ], field: :user_id
 
     # @!method get_statistics(opts = {})
     # @param opts Opts
@@ -46,6 +46,20 @@ module RegApi2
     # @return [Hash(currency, prepay, blocked, credit)] User balance
     define :get_balance, required: %w[ currency ]
 
+    # @!method refill_balance(opts = {})
+    # Add funds to the account. Allows sending invoices to WebMoney and Yandex.Dengi.
+    # @param opts Opts
+    # @option opts [String] :pay_type Payment method. Available options: WM — WebMoney, requires specifying of WMID; ymbill - Yandex.Dengi (the invoice receipt function should be enabled).
+    # @option opts [String] :wmid WebMoney ID
+    # @option opts [String] :currency Currency of the transfer. RUR only for Yandex.Dengi; USD, EUR and UAH for WebMoney.
+    # @option opts [String] :amount Amount of the invoice.
+    # @note Accessability: clients
+    # @note Support of service lists: no
+    # @return [Hash(total_payment, ...)] Result of operation.
+    # @example Add funds though WebMoney
+    #   RegApi2.user.refill_balance(pay_type: 'WM', wmid: 123456789012, currency: 'RUR', amount: 1000)
+    define :refill_balance, required: %w[ pay_type wmid currency amount ]
+
     extend self
   end
 end

data/lib/reg_api2/version.rb

@@ -1,5 +1,5 @@
 # -*- encoding : utf-8 -*-
 module RegApi2
   # Gem version.
-  VERSION = "0.0.1"
+  VERSION = "0.0.2".freeze
 end