tronzap-sdk 1.0.0

data/lib/tronzap/coerce.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Tronzap
+  # Reads loosely typed JSON values into the types the models expose.
+  #
+  # @api private
+  module Coerce
+    # A value in the response does not have the expected shape.
+    class Error < StandardError; end
+
+    EMPTY_HASH = {}.freeze
+    EMPTY_ARRAY = [].freeze
+
+    module_function
+
+    # The API is backed by PHP, which encodes an empty associative array as [].
+    def object(value, name)
+      return EMPTY_HASH if value.nil? || value == EMPTY_ARRAY
+      raise Error, "#{name} is not an object" unless value.is_a?(Hash)
+
+      value
+    end
+
+    def list(value, name, &)
+      return EMPTY_ARRAY if value.nil? || value == EMPTY_HASH
+      raise Error, "#{name} is not an array" unless value.is_a?(Array)
+
+      value.map(&).freeze
+    end
+
+    def text(value, name)
+      case value
+      when nil then ""
+      when String then value
+      when Integer, true, false then value.to_s
+      when BigDecimal then value.to_s("F")
+      else raise Error, "#{name} is not a string"
+      end
+    end
+
+    def optional_text(value, name)
+      result = text(value, name)
+      result.empty? ? nil : result
+    end
+
+    def integer(value, name)
+      return 0 if value.nil? || (value.is_a?(String) && value.strip.empty?)
+      return value if value.is_a?(Integer)
+
+      number = to_decimal(value, name)
+      raise Error, "#{name} is not an integer: #{value.inspect}" unless number.frac.zero?
+
+      number.to_i
+    end
+
+    def decimal(value, name)
+      optional_decimal(value, name) || BigDecimal(0)
+    end
+
+    def optional_decimal(value, name)
+      return nil if value.nil? || (value.is_a?(String) && value.strip.empty?)
+
+      to_decimal(value, name)
+    end
+
+    # Amounts arrive as JSON numbers from some endpoints and as strings from others.
+    def to_decimal(value, name)
+      case value
+      when BigDecimal then value
+      when Integer then BigDecimal(value)
+      when Float then BigDecimal(value.to_s)
+      when String then parse_decimal(value, name)
+      else raise Error, "#{name} is not a number: #{value.inspect}"
+      end
+    end
+
+    def parse_decimal(value, name)
+      number = BigDecimal(value.strip)
+      raise Error, "#{name} is not a finite number: #{value.inspect}" unless number.finite?
+
+      number
+    rescue ArgumentError
+      raise Error, "#{name} is not a number: #{value.inspect}"
+    end
+
+    def boolean(value, name)
+      case value
+      when nil, false then false
+      when true then true
+      when Integer, BigDecimal then !value.zero?
+      when String then parse_boolean(value, name)
+      else raise Error, "#{name} is not a boolean: #{value.inspect}"
+      end
+    end
+
+    def parse_boolean(value, name)
+      case value.strip
+      when "true", "1" then true
+      when "", "false", "0" then false
+      else raise Error, "#{name} is not a boolean: #{value.inspect}"
+      end
+    end
+
+    def decimal_map(value, name)
+      object(value, name).to_h { |key, amount| [key.to_s.freeze, to_decimal(amount, "#{name}.#{key}")] }.freeze
+    end
+
+    def timestamp(value, name)
+      case value
+      when nil then nil
+      when String then value.strip.empty? ? nil : Models::Timestamp.parse(value)
+      when Integer then Models::Timestamp.parse(value.to_s)
+      else raise Error, "#{name} is not a timestamp: #{value.inspect}"
+      end
+    end
+
+    # Values the API may add later are reported as +:unknown+ instead of failing the response.
+    def enum(value, allowed, name)
+      wire = text(value, name)
+      allowed.find { |symbol| symbol.name == wire } || :unknown
+    end
+
+    def optional_enum(value, allowed, name)
+      optional_text(value, name) && enum(value, allowed, name)
+    end
+  end
+end

data/lib/tronzap/configuration.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Tronzap
+  # Settings of a {Client}. Every client owns its configuration: the client validates and freezes it when it is
+  # created, so there is no shared or global state.
+  #
+  # @example In the constructor
+  #   Tronzap::Client.new(api_token: token, api_secret: secret, timeout: 10)
+  #
+  # @example In a block
+  #   Tronzap::Client.new do |config|
+  #     config.api_token = token
+  #     config.api_secret = secret
+  #     config.base_url = "api.tronzap.com"
+  #   end
+  class Configuration
+    # The production API endpoint.
+    DEFAULT_BASE_URL = "https://api.tronzap.com"
+
+    # The default timeout, in seconds.
+    DEFAULT_TIMEOUT = 30
+
+    # @return [String] the API token from your TronZap dashboard, sent as a bearer token. Required.
+    attr_accessor :api_token
+
+    # @return [String] the API secret from your TronZap dashboard, used to sign every request body. It is never
+    #   sent. Required.
+    attr_accessor :api_secret
+
+    # @return [String] the API endpoint. A bare host such as +api.tronzap.com+ gets the +https+ scheme and a
+    #   trailing slash is removed. Give an explicit scheme to opt out, for example +http://localhost:8080+.
+    attr_accessor :base_url
+
+    # @return [Numeric] seconds allowed for connecting and for each read or write of a request
+    attr_accessor :timeout
+
+    # @return [String] the +User-Agent+ header
+    attr_accessor :user_agent
+
+    # @return [#call] the HTTP adapter, see {HttpAdapter}
+    attr_accessor :adapter
+
+    # @param api_token [String, nil]
+    # @param api_secret [String, nil]
+    # @param base_url [String]
+    # @param timeout [Numeric]
+    # @param user_agent [String]
+    # @param adapter [#call, nil] defaults to {HttpAdapter::NetHttp}
+    def initialize(api_token: nil, api_secret: nil, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT,
+                   user_agent: "tronzap-sdk-ruby/#{VERSION}", adapter: nil)
+      @api_token = api_token
+      @api_secret = api_secret
+      @base_url = base_url
+      @timeout = timeout
+      @user_agent = user_agent
+      @adapter = adapter
+    end
+
+    # Validates and normalizes the settings, then freezes the configuration.
+    #
+    # @return [self]
+    # @raise [ArgumentError] when a setting is invalid
+    def finalize!
+      @api_token = credential(@api_token, "api_token")
+      @api_secret = credential(@api_secret, "api_secret")
+      @base_url = self.class.normalize_base_url(@base_url)
+      @timeout = validate_timeout(@timeout)
+      @user_agent = validate_user_agent(@user_agent)
+      @adapter = validate_adapter(@adapter || HttpAdapter::NetHttp.new)
+      freeze
+    end
+
+    # @return [String] a description that leaves out the credentials
+    def inspect
+      "#<#{self.class.name} base_url=#{@base_url.inspect} timeout=#{@timeout.inspect} " \
+        "user_agent=#{@user_agent.inspect} adapter=#{@adapter.class.name}>"
+    end
+
+    # @param base_url [String]
+    # @return [String] the URL with a scheme and without a trailing slash
+    # @raise [ArgumentError] when it is not an http or https URL
+    def self.normalize_base_url(base_url)
+      raise ArgumentError, "base_url must be a String" unless base_url.is_a?(String)
+
+      normalized = base_url.strip
+      raise ArgumentError, "base_url must not be blank" if normalized.empty?
+
+      normalized = "https://#{normalized.delete_prefix("/")}" unless normalized.include?("://")
+      normalized = normalized.sub(%r{/+\z}, "")
+      check_url(normalized, base_url)
+      normalized
+    end
+
+    def self.check_url(url, original)
+      uri = begin
+        URI.parse(url)
+      rescue URI::InvalidURIError
+        raise ArgumentError, "base_url is not a valid URL: #{original}"
+      end
+      raise ArgumentError, "base_url must use http or https: #{original}" unless %w[http https].include?(uri.scheme)
+      raise ArgumentError, "base_url has no host: #{original}" if uri.host.nil? || uri.host.empty?
+      return unless uri.query || uri.fragment
+
+      raise ArgumentError, "base_url must not have a query or fragment: #{original}"
+    end
+    private_class_method :check_url
+
+    private
+
+    def credential(value, name)
+      raise ArgumentError, "#{name} is required" unless value.is_a?(String) && !value.strip.empty?
+
+      value.dup.freeze
+    end
+
+    def validate_timeout(value)
+      unless value.is_a?(Numeric) && value.real? && value.positive? && value.to_f.finite?
+        raise ArgumentError, "timeout must be a positive number of seconds, got #{value.inspect}"
+      end
+
+      value
+    end
+
+    def validate_user_agent(value)
+      unless value.is_a?(String) && !value.strip.empty? && !value.match?(/[\r\n]/)
+        raise ArgumentError, "user_agent must be a non-blank single-line String"
+      end
+
+      value.dup.freeze
+    end
+
+    def validate_adapter(value)
+      raise ArgumentError, "adapter must respond to #call" unless value.respond_to?(:call)
+
+      value
+    end
+  end
+end

data/lib/tronzap/errors.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Tronzap
+  # The base class of every failure of a TronZap API call.
+  #
+  # Invalid arguments are not API failures: they raise +ArgumentError+ before anything is sent.
+  class Error < StandardError; end
+
+  # The API rejected the request with a non-zero error code.
+  #
+  # The API reports some errors with a 2xx status and others with 4xx or 5xx, so this error takes precedence over
+  # {HttpError} whenever the response carries an error code.
+  class ApiError < Error
+    # @return [Integer] the numeric error code, one of the {ErrorCode} constants or a code this SDK does not know
+    attr_reader :code
+
+    # @return [String, nil] the error key, for example +invalid_tron_address+ or
+    #   +invalid_tron_address.from_address+
+    attr_reader :error_key
+
+    # @return [String, nil] the ID the API assigned to the request. Quote it when contacting support.
+    attr_reader :request_id
+
+    # @return [Integer] the HTTP status of the response
+    attr_reader :status
+
+    # @return [String] the raw response body
+    attr_reader :response_body
+
+    # @param message [String] the error message from the API
+    # @param code [Integer] the numeric error code
+    # @param status [Integer] the HTTP status of the response
+    # @param response_body [String] the raw response body
+    # @param error_key [String, nil] the error key
+    # @param request_id [String, nil] the request ID
+    def initialize(message, code:, status:, response_body:, error_key: nil, request_id: nil)
+      super(message)
+      @code = code
+      @status = status
+      @response_body = response_body
+      @error_key = error_key
+      @request_id = request_id
+    end
+  end
+
+  # The API answered with a non-2xx status and no error code in the body.
+  class HttpError < Error
+    # @return [Integer] the HTTP status of the response
+    attr_reader :status
+
+    # @return [String] the raw response body
+    attr_reader :response_body
+
+    # @param message [String] the error message
+    # @param status [Integer] the HTTP status of the response
+    # @param response_body [String] the raw response body
+    def initialize(message, status:, response_body:)
+      super(message)
+      @status = status
+      @response_body = response_body
+    end
+  end
+
+  # The API answered with HTTP 429: too many requests. Back off and retry.
+  class RateLimitError < HttpError
+    # @return [Float, nil] seconds the API asked to wait before retrying, from the +Retry-After+ header
+    attr_reader :retry_after
+
+    # @param message [String] the error message
+    # @param status [Integer] the HTTP status of the response
+    # @param response_body [String] the raw response body
+    # @param retry_after [Float, nil] seconds to wait before retrying
+    def initialize(message, status:, response_body:, retry_after: nil)
+      super(message, status: status, response_body: response_body)
+      @retry_after = retry_after
+    end
+  end
+
+  # The API answered with HTTP 401 or 403: check the API token and secret.
+  class UnauthorizedError < HttpError; end
+
+  # The API answered with an HTTP 5xx status. Usually transient.
+  class ServerError < HttpError; end
+
+  # The API answered with a 2xx status, but the SDK could not read the response.
+  class InvalidResponseError < Error
+    # @return [Integer, nil] the HTTP status of the response, +nil+ when the body was rejected before the status was
+    #   known
+    attr_reader :status
+
+    # @return [String] the raw response body, empty when it was too large to keep
+    attr_reader :response_body
+
+    # @param message [String] the error message
+    # @param status [Integer, nil] the HTTP status of the response
+    # @param response_body [String] the raw response body
+    def initialize(message, status:, response_body:)
+      super(message)
+      @status = status
+      @response_body = response_body
+    end
+  end
+
+  # No response arrived: the request failed below the HTTP level.
+  class NetworkError < Error; end
+
+  # The connection could not be established: the host name did not resolve or the connection was refused.
+  class ConnectionError < NetworkError; end
+
+  # The request did not complete within the configured timeout.
+  class TimeoutError < NetworkError; end
+
+  # The TLS handshake failed, for example because the server certificate is not trusted.
+  class SslError < NetworkError; end
+
+  # Error codes the TronZap API reports in {ApiError#code}.
+  module ErrorCode
+    # Authentication error: check the API token and that the signature is calculated correctly.
+    AUTH_ERROR = 1
+    # Invalid service or parameters: check the service name and the parameters.
+    INVALID_SERVICE_OR_PARAMS = 2
+    # Wallet not found: verify the wallet address, or contact support if you believe this is an error.
+    WALLET_NOT_FOUND = 5
+    # Insufficient funds: top up the account or request a smaller amount.
+    INSUFFICIENT_FUNDS = 6
+    # Invalid TRON address: it should be a valid 34-character TRON address.
+    INVALID_TRON_ADDRESS = 10
+    # Invalid energy amount.
+    INVALID_ENERGY_AMOUNT = 11
+    # Invalid duration.
+    INVALID_DURATION = 12
+    # Transaction or subscription not found: check the transaction ID or external ID. The API reports this code
+    # under the key +subscription_not_found+.
+    TRANSACTION_NOT_FOUND = 20
+    # The subscription cannot be stopped right now.
+    CANNOT_STOP_SUBSCRIPTION = 21
+    # Address not activated: activate it first with an address activation transaction.
+    ADDRESS_NOT_ACTIVATED = 24
+    # Address already activated. No action is needed.
+    ADDRESS_ALREADY_ACTIVATED = 25
+    # AML check not found: check the ID or run the AML check again.
+    AML_CHECK_NOT_FOUND = 30
+    # The service is temporarily unavailable.
+    SERVICE_NOT_AVAILABLE = 35
+    # Invalid bandwidth amount.
+    INVALID_BANDWIDTH_AMOUNT = 50
+    # Internal server error. Contact support if it persists.
+    INTERNAL_SERVER_ERROR = 500
+  end
+end

data/lib/tronzap/http_adapter.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "zlib"
+
+module Tronzap
+  # The transport a {Client} sends requests through.
+  #
+  # An adapter is any object with a +call+ method that takes a {Request} and returns a {Response} (or any object
+  # with +status+, +headers+ and +body+). The client builds the body, signs it and parses the response; the adapter
+  # only moves bytes. {NetHttp} is the default.
+  #
+  # Failures raised by an adapter are reported as {NetworkError} subclasses when they are standard Ruby network
+  # errors: +Timeout::Error+, +OpenSSL::SSL::SSLError+, +SocketError+, +SystemCallError+, +IOError+ and the
+  # +Net::HTTP+ protocol errors. An adapter built on another HTTP library should rescue that library's errors and
+  # raise {TimeoutError}, {ConnectionError}, {SslError} or {NetworkError} itself.
+  #
+  # @example An adapter on top of Faraday
+  #   class FaradayAdapter
+  #     def initialize(connection) = @connection = connection
+  #
+  #     def call(request)
+  #       response = @connection.post(request.url, request.body, request.headers) do |req|
+  #         req.options.timeout = request.timeout
+  #       end
+  #       Tronzap::HttpAdapter::Response.new(status: response.status, headers: response.headers.to_h,
+  #                                          body: response.body.to_s)
+  #     rescue Faraday::TimeoutError => e
+  #       raise Tronzap::TimeoutError, e.message
+  #     rescue Faraday::SSLError => e
+  #       raise Tronzap::SslError, e.message
+  #     rescue Faraday::ConnectionFailed => e
+  #       raise Tronzap::ConnectionError, e.message
+  #     end
+  #   end
+  module HttpAdapter
+    # An HTTP request to send.
+    #
+    # @!attribute [r] http_method
+    #   @return [Symbol] the HTTP method, always +:post+
+    # @!attribute [r] url
+    #   @return [String] the absolute URL
+    # @!attribute [r] headers
+    #   @return [Hash{String => String}] the request headers
+    # @!attribute [r] body
+    #   @return [String] the JSON body. It is signed byte for byte, so send it unchanged.
+    # @!attribute [r] timeout
+    #   @return [Numeric] seconds allowed for connecting and for each read or write
+    Request = Data.define(:http_method, :url, :headers, :body, :timeout)
+
+    # An HTTP response.
+    #
+    # @!attribute [r] status
+    #   @return [Integer] the HTTP status
+    # @!attribute [r] headers
+    #   @return [Hash{String => String}] the response headers; names are matched case-insensitively
+    # @!attribute [r] body
+    #   @return [String] the response body
+    Response = Data.define(:status, :headers, :body)
+
+    # The largest response body the default adapter reads.
+    MAX_RESPONSE_BYTES = 8 * 1024 * 1024
+
+    # The default adapter, on top of +Net::HTTP+ from the standard library.
+    #
+    # It opens a new connection for every request and keeps no state between requests, so it is safe to share
+    # across threads. TLS certificates are always verified. Proxies are taken from the +http_proxy+ and
+    # +https_proxy+ environment variables.
+    class NetHttp
+      # @param ca_file [String, nil] a PEM file with the certificates to trust instead of the system store
+      def initialize(ca_file: nil)
+        @ca_file = ca_file&.dup&.freeze
+        freeze
+      end
+
+      # @param request [Request]
+      # @return [Response]
+      def call(request)
+        uri = URI.parse(request.url)
+        http = connection(uri, request.timeout)
+        post = Net::HTTP::Post.new(uri.request_uri, request.headers)
+        post.body = request.body
+
+        http.start do
+          http.request(post) do |response|
+            return Response.new(status: response.code.to_i, headers: headers(response), body: read(response))
+          end
+        end
+      end
+
+      private
+
+      def connection(uri, timeout)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        if http.use_ssl?
+          http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+          http.ca_file = @ca_file if @ca_file
+        end
+        http.open_timeout = timeout
+        http.read_timeout = timeout
+        http.write_timeout = timeout
+        http.ssl_timeout = timeout
+        http.max_retries = 0
+        http
+      end
+
+      def headers(response)
+        response.each_header.to_h
+      end
+
+      def read(response)
+        status = response.code.to_i
+        raise too_large(status) if response.content_length.to_i > MAX_RESPONSE_BYTES
+
+        body = +""
+        response.read_body do |chunk|
+          raise too_large(status) if body.bytesize + chunk.bytesize > MAX_RESPONSE_BYTES
+
+          body << chunk
+        end
+        body
+      end
+
+      def too_large(status)
+        InvalidResponseError.new("Response body exceeds #{MAX_RESPONSE_BYTES} bytes",
+                                 status: status, response_body: "")
+      end
+    end
+
+    CONNECTION_ERRORS = [
+      SocketError, Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::ENETUNREACH, Errno::EADDRNOTAVAIL
+    ].freeze
+    private_constant :CONNECTION_ERRORS
+
+    NETWORK_ERRORS = [
+      OpenSSL::SSL::SSLError, Timeout::Error, IOError, SystemCallError, Net::ProtocolError, Net::HTTPBadResponse,
+      Zlib::Error, *CONNECTION_ERRORS
+    ].freeze
+    private_constant :NETWORK_ERRORS
+
+    # Runs the block and reports standard Ruby network failures as {NetworkError} subclasses.
+    #
+    # @api private
+    def self.translate_errors
+      yield
+    rescue Tronzap::Error
+      raise
+    rescue *NETWORK_ERRORS => e
+      raise classify(e)
+    end
+
+    def self.classify(error)
+      case error
+      when OpenSSL::SSL::SSLError
+        SslError.new("TLS error: #{error.message}")
+      when Timeout::Error, Errno::ETIMEDOUT
+        TimeoutError.new("The request timed out: #{error.message}")
+      when *CONNECTION_ERRORS
+        ConnectionError.new("Connection failed: #{error.message}")
+      else
+        NetworkError.new("Network error: #{error.class}: #{error.message}")
+      end
+    end
+    private_class_method :classify
+  end
+end

data/lib/tronzap/models/activate_address_rate.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Tronzap
+  module Models
+    # The price of activating a TRON address.
+    #
+    # @!attribute [r] price
+    #   @return [BigDecimal] activation price, in TRX
+    ActivateAddressRate = Data.define(:price)
+  end
+end

data/lib/tronzap/models/address_resources.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Tronzap
+  module Models
+    # The resources a TRON address has available.
+    #
+    # @!attribute [r] energy
+    #   @return [Integer] available energy
+    # @!attribute [r] bandwidth
+    #   @return [Integer] available bandwidth
+    AddressResources = Data.define(:energy, :bandwidth)
+  end
+end

data/lib/tronzap/models/aml_risk_factor.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Tronzap
+  module Models
+    # One factor that contributed to an AML risk score.
+    #
+    # @!attribute [r] name
+    #   @return [String] machine-readable factor name
+    # @!attribute [r] label
+    #   @return [String] human-readable factor label
+    # @!attribute [r] group
+    #   @return [String] the group the factor belongs to
+    # @!attribute [r] score
+    #   @return [BigDecimal] the factor's share of the risk score
+    AmlRiskFactor = Data.define(:name, :label, :group, :score) do
+      # @api private
+      def self.from_api(value)
+        data = Coerce.object(value, "risk factor")
+        new(
+          name: Coerce.text(data["name"], "name"),
+          label: Coerce.text(data["label"], "label"),
+          group: Coerce.text(data["group"], "group"),
+          score: Coerce.decimal(data["score"], "score")
+        )
+      end
+    end
+  end
+end

data/lib/tronzap/models/bandwidth_rate.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Tronzap
+  module Models
+    # A bandwidth price tier. Bandwidth is priced per 1000 units: 345 bandwidth at a {price} of 1 costs 0.345.
+    #
+    # @!attribute [r] duration
+    #   @return [Integer] rental duration in hours
+    # @!attribute [r] min_amount
+    #   @return [Integer] smallest bandwidth amount this tier applies to
+    # @!attribute [r] max_amount
+    #   @return [Integer] largest bandwidth amount this tier applies to
+    # @!attribute [r] price
+    #   @return [BigDecimal] price per 1000 units of bandwidth, in TRX
+    BandwidthRate = Data.define(:duration, :min_amount, :max_amount, :price) do
+      # @api private
+      def self.from_api(value)
+        data = Coerce.object(value, "bandwidth rate")
+        new(
+          duration: Coerce.integer(data["duration"], "duration"),
+          min_amount: Coerce.integer(data["min_amount"], "min_amount"),
+          max_amount: Coerce.integer(data["max_amount"], "max_amount"),
+          price: Coerce.decimal(data["price"], "price")
+        )
+      end
+    end
+  end
+end