tronzap-sdk 1.0.0

data/lib/tronzap/models/direct_recharge_rate.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Tronzap
+  module Models
+    # A rate energy is delivered at for a direct recharge.
+    #
+    # @!attribute [r] duration
+    #   @return [Integer] rental duration in hours
+    # @!attribute [r] min_energy
+    #   @return [Integer] smallest energy amount this rate applies to
+    # @!attribute [r] max_energy
+    #   @return [Integer] largest energy amount this rate applies to
+    # @!attribute [r] price
+    #   @return [BigDecimal] price per unit of energy, in TRX
+    # @!attribute [r] price_32k
+    #   @return [BigDecimal] price of 32 000 energy, in TRX
+    # @!attribute [r] price_65k
+    #   @return [BigDecimal] price of 65 000 energy, in TRX
+    # @!attribute [r] price_131k
+    #   @return [BigDecimal] price of 131 000 energy, in TRX
+    DirectRechargeRate = Data.define(:duration, :min_energy, :max_energy,
+                                     :price, :price_32k, :price_65k, :price_131k) do
+      # @api private
+      def self.from_api(value)
+        data = Coerce.object(value, "direct recharge rate")
+        new(
+          duration: Coerce.integer(data["duration"], "duration"),
+          min_energy: Coerce.integer(data["min_energy"], "min_energy"),
+          max_energy: Coerce.integer(data["max_energy"], "max_energy"),
+          price: Coerce.decimal(data["price"], "price"),
+          price_32k: Coerce.decimal(data["price_32k"], "price_32k"),
+          price_65k: Coerce.decimal(data["price_65k"], "price_65k"),
+          price_131k: Coerce.decimal(data["price_131k"], "price_131k")
+        )
+      end
+    end
+  end
+end

data/lib/tronzap/models/energy_rate.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Tronzap
+  module Models
+    # An energy price tier. Energy is priced per unit.
+    #
+    # @!attribute [r] duration
+    #   @return [Integer] rental duration in hours
+    # @!attribute [r] min_amount
+    #   @return [Integer] smallest amount this tier applies to
+    # @!attribute [r] max_amount
+    #   @return [Integer] largest amount this tier applies to
+    # @!attribute [r] min_energy
+    #   @return [Integer] smallest energy amount this tier applies to
+    # @!attribute [r] max_energy
+    #   @return [Integer] largest energy amount this tier applies to
+    # @!attribute [r] price
+    #   @return [BigDecimal] price per unit of energy, in TRX
+    # @!attribute [r] price_32k
+    #   @return [BigDecimal] price of 32 000 energy, in TRX
+    # @!attribute [r] price_65k
+    #   @return [BigDecimal] price of 65 000 energy, in TRX
+    # @!attribute [r] price_131k
+    #   @return [BigDecimal] price of 131 000 energy, in TRX
+    EnergyRate = Data.define(:duration, :min_amount, :max_amount, :min_energy, :max_energy,
+                             :price, :price_32k, :price_65k, :price_131k) do
+      # @api private
+      def self.from_api(value)
+        data = Coerce.object(value, "energy 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"),
+          min_energy: Coerce.integer(data["min_energy"], "min_energy"),
+          max_energy: Coerce.integer(data["max_energy"], "max_energy"),
+          price: Coerce.decimal(data["price"], "price"),
+          price_32k: Coerce.decimal(data["price_32k"], "price_32k"),
+          price_65k: Coerce.decimal(data["price_65k"], "price_65k"),
+          price_131k: Coerce.decimal(data["price_131k"], "price_131k")
+        )
+      end
+    end
+  end
+end

data/lib/tronzap/models/enums.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Tronzap
+  # Value objects nested in API responses, and the symbols enum-like fields take.
+  #
+  # Enum-like fields are symbols. A value this SDK version does not recognise is reported as +:unknown+.
+  module Models
+    # Services a transaction is created for.
+    SERVICES = %i[energy bandwidth resource_bundle activate_address].freeze
+
+    # Transaction states: +:new+ → +:pending+ → +:success+ or +:failed+.
+    TRANSACTION_STATUSES = %i[new pending success failed].freeze
+
+    # What an AML check screens: a wallet address or a transaction hash.
+    AML_CHECK_TYPES = %i[address hash].freeze
+
+    # Directions of a screened transaction: incoming (+:deposit+) or outgoing (+:withdrawal+) funds.
+    AML_DIRECTIONS = %i[deposit withdrawal].freeze
+
+    # AML check states.
+    AML_STATUSES = %i[pending processing completed failed].freeze
+
+    # AML risk levels.
+    AML_RISK_LEVELS = %i[low medium high].freeze
+  end
+end

data/lib/tronzap/models/resource_amounts.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Tronzap
+  module Models
+    # The resources a transaction buys. A resource the transaction does not include is 0.
+    #
+    # @!attribute [r] energy
+    #   @return [Integer] energy bought
+    # @!attribute [r] bandwidth
+    #   @return [Integer] bandwidth bought
+    ResourceAmounts = Data.define(:energy, :bandwidth)
+  end
+end

data/lib/tronzap/models/timestamp.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Tronzap
+  module Models
+    # A timestamp as the API sent it, together with its parsed value.
+    #
+    # @!attribute [r] raw
+    #   @return [String] the text exactly as the API sent it
+    # @!attribute [r] value
+    #   @return [Time, nil] the parsed time, or +nil+ when {raw} is in a format the SDK does not recognise
+    Timestamp = Data.define(:raw, :value) do
+      # Parses a timestamp in any of the formats the API emits: RFC 3339 with or without an offset, a
+      # space-separated date and time, a bare date, or Unix seconds. Times without an offset are read as UTC.
+      #
+      # @param raw [String]
+      # @return [Timestamp]
+      def self.parse(raw)
+        raise ArgumentError, "raw must be a String" unless raw.is_a?(String)
+
+        new(raw: raw.dup.freeze, value: parse_time(raw.strip))
+      end
+
+      def self.parse_time(text)
+        if (match = /\A(\d{4})-(\d{2})-(\d{2})[T\ ](\d{2}):(\d{2})
+                     (?::(\d{2}(?:\.\d+)?))?\s*(Z|[+-]\d{2}(?::?\d{2})?)?\z/ix.match(text))
+          date_time(match)
+        elsif (match = /\A(\d{4})-(\d{2})-(\d{2})\z/.match(text))
+          calendar_day(Time.utc(*match.captures.map(&:to_i)), *match.captures)
+        elsif /\A\d{1,12}\z/.match?(text)
+          Time.at(text.to_i).utc
+        end
+      rescue ArgumentError
+        nil
+      end
+
+      def self.date_time(match)
+        year, month, day, hour, minute, second, zone = match.captures
+        zone = "+00:00" if zone.nil? || zone.casecmp?("z")
+        zone = "#{zone}:00" if zone.length == 3
+        time = Time.new(year.to_i, month.to_i, day.to_i, hour.to_i, minute.to_i, Rational(second || "0"), zone)
+        calendar_day(time, year, month, day)
+      end
+
+      # Time rolls an impossible date such as February 30 over into the next month instead of rejecting it.
+      def self.calendar_day(time, year, month, day)
+        time if [time.year, time.month, time.day] == [year.to_i, month.to_i, day.to_i]
+      end
+      private_class_method :parse_time, :date_time, :calendar_day
+
+      # @return [String] the parsed time in ISO 8601, or the raw text when it could not be parsed
+      def to_s
+        return raw unless value
+
+        value.iso8601(value.subsec.zero? ? 0 : 6)
+      end
+    end
+  end
+end

data/lib/tronzap/models/transaction_params.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Tronzap
+  module Models
+    # The parameters a transaction was created with.
+    #
+    # @!attribute [r] address
+    #   @return [String] the TRON address that receives the resources
+    # @!attribute [r] duration
+    #   @return [Integer] rental duration in hours
+    # @!attribute [r] amounts
+    #   @return [ResourceAmounts] the resources the transaction buys
+    # @!attribute [r] activate_address
+    #   @return [Boolean] whether the transaction also activates the address
+    TransactionParams = Data.define(:address, :duration, :amounts, :activate_address) do
+      # @api private
+      def self.from_api(value, service)
+        data = Coerce.object(value, "params")
+        new(
+          address: Coerce.text(data["address"], "params.address"),
+          duration: Coerce.integer(data["duration"], "params.duration"),
+          amounts: amounts(data, service),
+          activate_address: Coerce.boolean(data["activate_address"], "params.activate_address")
+        )
+      end
+
+      # Older transactions carry params.amount / params.energy_amount instead of params.amounts.
+      def self.amounts(data, service)
+        amounts = Coerce.object(data["amounts"], "params.amounts")
+        energy = Coerce.integer(amounts["energy"], "params.amounts.energy")
+        bandwidth = Coerce.integer(amounts["bandwidth"], "params.amounts.bandwidth")
+        if energy.zero? && bandwidth.zero?
+          energy = Coerce.integer(data["energy_amount"], "params.energy_amount")
+          amount = Coerce.integer(data["amount"], "params.amount")
+          if service == :bandwidth
+            bandwidth = amount
+          elsif energy.zero?
+            energy = amount
+          end
+        end
+        ResourceAmounts.new(energy: energy, bandwidth: bandwidth)
+      end
+      private_class_method :amounts
+    end
+  end
+end

data/lib/tronzap/requests/address_activation.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Tronzap
+  module Requests
+    # A TRON address to activate.
+    #
+    # @!attribute [r] address
+    #   @return [String] the TRON address to activate
+    # @!attribute [r] external_id
+    #   @return [String, nil] your own ID for the transaction, to look it up with {CheckTransaction.by_external_id}
+    AddressActivation = Data.define(:address, :external_id) do
+      # @param address [String]
+      # @param external_id [String, nil]
+      # @raise [ArgumentError]
+      def initialize(address:, external_id: nil)
+        super(
+          address: Validation.string(address, "address"),
+          external_id: Validation.optional_string(external_id, "external_id")
+        )
+      end
+
+      # @api private
+      def body
+        Validation.transaction("activate_address", { "address" => address }, external_id)
+      end
+    end
+  end
+end

data/lib/tronzap/requests/aml_check.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Tronzap
+  module Requests
+    # An address or a transaction hash to screen.
+    #
+    # @!attribute [r] type
+    #   @return [Symbol] what to screen, one of {Models::AML_CHECK_TYPES}
+    # @!attribute [r] network
+    #   @return [String] the network code, for example +TRX+, +BTC+ or +ETH+
+    # @!attribute [r] address
+    #   @return [String] the wallet address
+    # @!attribute [r] transaction_hash
+    #   @return [String, nil] the transaction hash, required when {type} is +:hash+
+    # @!attribute [r] direction
+    #   @return [Symbol, nil] the transaction direction for a hash check, one of {Models::AML_DIRECTIONS}
+    AmlCheck = Data.define(:type, :network, :address, :transaction_hash, :direction) do
+      # @param type [Symbol, String] +:address+ or +:hash+
+      # @param network [String]
+      # @param address [String]
+      # @param transaction_hash [String, nil]
+      # @param direction [Symbol, String, nil] +:deposit+ or +:withdrawal+
+      # @raise [ArgumentError]
+      def initialize(type:, network:, address:, transaction_hash: nil, direction: nil)
+        type = Validation.one_of(type, Models::AML_CHECK_TYPES, "type")
+        transaction_hash = Validation.optional_string(transaction_hash, "transaction_hash")
+        raise ArgumentError, "transaction_hash is required for a hash check" if type == :hash && !transaction_hash
+
+        super(
+          type: type,
+          network: Validation.string(network, "network"),
+          address: Validation.string(address, "address"),
+          transaction_hash: transaction_hash,
+          direction: Validation.optional_one_of(direction, Models::AML_DIRECTIONS, "direction")
+        )
+      end
+
+      # Screens a wallet address.
+      #
+      # @param network [String] the network code, for example +TRX+
+      # @param address [String]
+      # @return [AmlCheck]
+      def self.for_address(network, address)
+        new(type: :address, network: network, address: address)
+      end
+
+      # Screens a transaction.
+      #
+      # @param network [String] the network code, for example +BTC+
+      # @param address [String]
+      # @param transaction_hash [String]
+      # @param direction [Symbol, String, nil] +:deposit+ or +:withdrawal+
+      # @return [AmlCheck]
+      def self.for_hash(network, address, transaction_hash, direction: nil)
+        new(type: :hash, network: network, address: address, transaction_hash: transaction_hash,
+            direction: direction)
+      end
+
+      # @api private
+      def body
+        body = { "type" => type.name, "network" => network, "address" => address }
+        body["hash"] = transaction_hash if transaction_hash
+        body["direction"] = direction.name if direction
+        body
+      end
+    end
+  end
+end

data/lib/tronzap/requests/aml_history.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Tronzap
+  module Requests
+    # A page of AML check history to return.
+    #
+    # @!attribute [r] page
+    #   @return [Integer] the page number, starting at 1
+    # @!attribute [r] per_page
+    #   @return [Integer] the page size
+    # @!attribute [r] status
+    #   @return [Symbol, nil] only checks in this state, one of {Models::AML_STATUSES}, or all checks when +nil+
+    AmlHistory = Data.define(:page, :per_page, :status) do
+      # @param page [Integer]
+      # @param per_page [Integer]
+      # @param status [Symbol, String, nil]
+      # @raise [ArgumentError]
+      def initialize(page: 1, per_page: 10, status: nil)
+        super(
+          page: Validation.positive_integer(page, "page"),
+          per_page: Validation.positive_integer(per_page, "per_page"),
+          status: Validation.optional_one_of(status, Models::AML_STATUSES, "status")
+        )
+      end
+
+      # @api private
+      def body
+        body = { "page" => page, "per_page" => per_page }
+        body["status"] = status.name if status
+        body
+      end
+    end
+  end
+end

data/lib/tronzap/requests/bandwidth_transaction.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Tronzap
+  module Requests
+    # A bandwidth purchase. Bandwidth is rented for one hour.
+    #
+    # @!attribute [r] address
+    #   @return [String] the TRON address that receives the bandwidth
+    # @!attribute [r] bandwidth
+    #   @return [Integer] the amount of bandwidth to buy
+    # @!attribute [r] external_id
+    #   @return [String, nil] your own ID for the transaction, to look it up with {CheckTransaction.by_external_id}
+    BandwidthTransaction = Data.define(:address, :bandwidth, :external_id) do
+      # @param address [String]
+      # @param bandwidth [Integer]
+      # @param external_id [String, nil]
+      # @raise [ArgumentError]
+      def initialize(address:, bandwidth:, external_id: nil)
+        super(
+          address: Validation.string(address, "address"),
+          bandwidth: Validation.positive_integer(bandwidth, "bandwidth"),
+          external_id: Validation.optional_string(external_id, "external_id")
+        )
+      end
+
+      # @api private
+      def body
+        params = { "address" => address, "amounts" => { "bandwidth" => bandwidth }, "duration" => 1 }
+        Validation.transaction("bandwidth", params, external_id)
+      end
+    end
+  end
+end

data/lib/tronzap/requests/calculate.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Tronzap
+  module Requests
+    # An energy purchase to price.
+    #
+    # @!attribute [r] address
+    #   @return [String] the TRON address that would receive the energy
+    # @!attribute [r] energy
+    #   @return [Integer] the amount of energy
+    # @!attribute [r] duration
+    #   @return [Integer] rental duration in hours, one of the durations {Client#get_services} lists
+    Calculate = Data.define(:address, :energy, :duration) do
+      # @param address [String]
+      # @param energy [Integer]
+      # @param duration [Integer]
+      # @raise [ArgumentError]
+      def initialize(address:, energy:, duration: 1)
+        super(
+          address: Validation.string(address, "address"),
+          energy: Validation.positive_integer(energy, "energy"),
+          duration: Validation.positive_integer(duration, "duration")
+        )
+      end
+
+      # @api private
+      def body
+        { "address" => address, "amount" => energy, "duration" => duration }
+      end
+    end
+  end
+end

data/lib/tronzap/requests/check_transaction.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Tronzap
+  module Requests
+    # The transaction to look up, by its TronZap ID, your external ID, or both.
+    #
+    # @!attribute [r] id
+    #   @return [String, nil] the transaction ID assigned by TronZap
+    # @!attribute [r] external_id
+    #   @return [String, nil] the external ID you passed when creating the transaction
+    CheckTransaction = Data.define(:id, :external_id) do
+      # @param id [String, nil]
+      # @param external_id [String, nil]
+      # @raise [ArgumentError] when neither is given
+      def initialize(id: nil, external_id: nil)
+        id = Validation.optional_string(id, "id")
+        external_id = Validation.optional_string(external_id, "external_id")
+        raise ArgumentError, "either id or external_id is required" if id.nil? && external_id.nil?
+
+        super
+      end
+
+      # Looks a transaction up by its TronZap ID.
+      #
+      # @param id [String]
+      # @return [CheckTransaction]
+      def self.by_id(id)
+        new(id: id)
+      end
+
+      # Looks a transaction up by the external ID you passed when creating it.
+      #
+      # @param external_id [String]
+      # @return [CheckTransaction]
+      def self.by_external_id(external_id)
+        new(external_id: external_id)
+      end
+
+      # @api private
+      def body
+        body = {}
+        body["id"] = id if id
+        body["external_id"] = external_id if external_id
+        body
+      end
+    end
+  end
+end

data/lib/tronzap/requests/energy_transaction.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Tronzap
+  module Requests
+    # An energy purchase.
+    #
+    # @!attribute [r] address
+    #   @return [String] the TRON address that receives the energy
+    # @!attribute [r] energy
+    #   @return [Integer] the amount of energy to buy
+    # @!attribute [r] duration
+    #   @return [Integer] rental duration in hours, one of the durations {Client#get_services} lists
+    # @!attribute [r] external_id
+    #   @return [String, nil] your own ID for the transaction, to look it up with {CheckTransaction.by_external_id}
+    # @!attribute [r] activate_address
+    #   @return [Boolean] whether to activate the address in the same transaction
+    EnergyTransaction = Data.define(:address, :energy, :duration, :external_id, :activate_address) do
+      # @param address [String]
+      # @param energy [Integer]
+      # @param duration [Integer]
+      # @param external_id [String, nil]
+      # @param activate_address [Boolean]
+      # @raise [ArgumentError]
+      def initialize(address:, energy:, duration: 1, external_id: nil, activate_address: false)
+        super(
+          address: Validation.string(address, "address"),
+          energy: Validation.positive_integer(energy, "energy"),
+          duration: Validation.positive_integer(duration, "duration"),
+          external_id: Validation.optional_string(external_id, "external_id"),
+          activate_address: Validation.boolean(activate_address, "activate_address")
+        )
+      end
+
+      # @api private
+      def body
+        params = { "address" => address, "amounts" => { "energy" => energy }, "duration" => duration }
+        params["activate_address"] = true if activate_address
+        Validation.transaction("energy", params, external_id)
+      end
+    end
+  end
+end

data/lib/tronzap/requests/estimate_energy.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Tronzap
+  # The USDT (TRC20) contract address. The API estimates a transfer of this token when
+  # {Requests::EstimateEnergy#contract_address} is not set.
+  USDT_CONTRACT_ADDRESS = "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"
+
+  module Requests
+    # A token transfer to estimate the energy for.
+    #
+    # @!attribute [r] from_address
+    #   @return [String] the sender's TRON address
+    # @!attribute [r] to_address
+    #   @return [String] the recipient's TRON address
+    # @!attribute [r] contract_address
+    #   @return [String, nil] the token contract address. When not set the API estimates a USDT (TRC20) transfer.
+    EstimateEnergy = Data.define(:from_address, :to_address, :contract_address) do
+      # @param from_address [String]
+      # @param to_address [String]
+      # @param contract_address [String, nil]
+      # @raise [ArgumentError]
+      def initialize(from_address:, to_address:, contract_address: nil)
+        super(
+          from_address: Validation.string(from_address, "from_address"),
+          to_address: Validation.string(to_address, "to_address"),
+          contract_address: Validation.optional_string(contract_address, "contract_address")
+        )
+      end
+
+      # @api private
+      def body
+        body = { "from_address" => from_address, "to_address" => to_address }
+        body["contract_address"] = contract_address if contract_address
+        body
+      end
+    end
+  end
+end

data/lib/tronzap/requests/resource_bundle_transaction.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Tronzap
+  module Requests
+    # A purchase of energy and bandwidth in one transaction.
+    #
+    # @!attribute [r] address
+    #   @return [String] the TRON address that receives the resources
+    # @!attribute [r] energy
+    #   @return [Integer] the amount of energy to buy
+    # @!attribute [r] bandwidth
+    #   @return [Integer] the amount of bandwidth to buy
+    # @!attribute [r] duration
+    #   @return [Integer] rental duration in hours
+    # @!attribute [r] external_id
+    #   @return [String, nil] your own ID for the transaction, to look it up with {CheckTransaction.by_external_id}
+    # @!attribute [r] activate_address
+    #   @return [Boolean] whether to activate the address in the same transaction
+    ResourceBundleTransaction = Data.define(:address, :energy, :bandwidth, :duration, :external_id,
+                                            :activate_address) do
+      # @param address [String]
+      # @param energy [Integer]
+      # @param bandwidth [Integer]
+      # @param duration [Integer]
+      # @param external_id [String, nil]
+      # @param activate_address [Boolean]
+      # @raise [ArgumentError]
+      def initialize(address:, energy:, bandwidth:, duration: 1, external_id: nil, activate_address: false)
+        super(
+          address: Validation.string(address, "address"),
+          energy: Validation.positive_integer(energy, "energy"),
+          bandwidth: Validation.positive_integer(bandwidth, "bandwidth"),
+          duration: Validation.positive_integer(duration, "duration"),
+          external_id: Validation.optional_string(external_id, "external_id"),
+          activate_address: Validation.boolean(activate_address, "activate_address")
+        )
+      end
+
+      # @api private
+      def body
+        params = {
+          "address" => address,
+          "amounts" => { "energy" => energy, "bandwidth" => bandwidth },
+          "duration" => duration
+        }
+        params["activate_address"] = true if activate_address
+        Validation.transaction("resource_bundle", params, external_id)
+      end
+    end
+  end
+end

data/lib/tronzap/requests/validation.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Tronzap
+  # Parameters of {Client} calls. A request validates its values when it is created, so an invalid one raises
+  # +ArgumentError+ and never reaches the API.
+  module Requests
+    # @api private
+    module Validation
+      module_function
+
+      def string(value, name)
+        raise ArgumentError, "#{name} is required" unless value.is_a?(String) && !value.strip.empty?
+
+        value.dup.freeze
+      end
+
+      def optional_string(value, name)
+        return nil if value.nil?
+        raise ArgumentError, "#{name} must be a non-blank String when set" unless value.is_a?(String) &&
+                                                                                  !value.strip.empty?
+
+        value.dup.freeze
+      end
+
+      def positive_integer(value, name)
+        raise ArgumentError, "#{name} must be a positive Integer, got #{value.inspect}" unless value.is_a?(Integer) &&
+                                                                                               value.positive?
+
+        value
+      end
+
+      def boolean(value, name)
+        raise ArgumentError, "#{name} must be true or false, got #{value.inspect}" unless [true, false].include?(value)
+
+        value
+      end
+
+      def one_of(value, allowed, name)
+        symbol = value.is_a?(String) ? allowed.find { |item| item.name == value } : value
+        return symbol if allowed.include?(symbol)
+
+        raise ArgumentError, "#{name} must be one of #{allowed.map(&:inspect).join(", ")}, got #{value.inspect}"
+      end
+
+      def optional_one_of(value, allowed, name)
+        value.nil? ? nil : one_of(value, allowed, name)
+      end
+
+      def transaction(service, params, external_id)
+        body = { "service" => service, "params" => params }
+        body["external_id"] = external_id if external_id
+        body
+      end
+    end
+  end
+end