sequence-sdk 1.0.3 → 1.0.4

data/lib/sequence/key.rb

@@ -7,30 +7,37 @@ module Sequence
   # Keys are used to sign transactions.
   class Key < ResponseObject
     # @!attribute [r] id
-    # Unique identifier of the key, based on the public key material itself.
+    #   Unique identifier of the key, based on the public key material itself.
     # @return [String]
     attrib :id
 
     # @!attribute [r] alias
-    # Unique, user-specified identifier of the key.
+    #   Unique, user-specified identifier of the key.
     # @return [String]
     attrib :alias
 
     class ClientModule < Sequence::ClientModule
-
       # Creates a key.
-      # @param [Hash] opts Options hash
-      # @option opts [String] alias Unique, user-specified identifier of the key.
+      # @param [Hash] opts
+      #   Options hash
+      # @option opts [String] alias
+      #   Unique, user-specified identifier of the key.
       # @return [Key]
       def create(opts = {})
+        validate_inclusion_of!(opts, :alias)
         Key.new(client.session.request('create-key', opts))
       end
 
       # Executes a query, returning an enumerable over individual keys.
-      # @param [Hash] opts Options hash
-      # @option opts [Array<String>] aliases A list of aliases of keys to retrieve.
+      # @param [Hash] opts
+      #   Options hash
+      # @option opts [Array<String>] aliases
+      #   A list of aliases of keys to retrieve.
+      # @option opts [Integer>] page_size
+      #   The number of items to return in the result set.
       # @return [Query]
       def query(opts = {})
+        validate_inclusion_of!(opts, :aliases, :page_size, :after)
         Query.new(client, opts)
       end
     end

data/lib/sequence/page.rb

@@ -1,6 +1,7 @@
 require_relative './response_object'
 
 module Sequence
+  # @private
   class Page < ResponseObject
     # @!attribute [r] items
     # List of items.

data/lib/sequence/query.rb

@@ -4,6 +4,7 @@ module Sequence
   class Query
     include ::Enumerable
 
+    # @private
     # @return [Client]
     attr_reader :client
 
@@ -29,23 +30,25 @@ module Sequence
       end
     end
 
-    def pages
-      PageQuery.new(client, query, method(:fetch), method(:translate))
-    end
-
-    # @abstract
+    # @private
     def fetch(query)
       raise NotImplementedError
     end
 
     # Overwrite to translate API response data to a different Ruby object.
-    # @abstract
+    # @private
     def translate(response_object)
       raise NotImplementedError
     end
 
     alias_method :all, :to_a
 
+    # @private
+    def pages
+      PageQuery.new(client, query, method(:fetch), method(:translate))
+    end
+
+    # @private
     class PageQuery
       include ::Enumerable
 

data/lib/sequence/session.rb

@@ -5,6 +5,7 @@ require_relative './errors'
 require_relative './version'
 
 module Sequence
+  # @private
   class Session
     def initialize(opts)
       @opts = opts
@@ -41,33 +42,24 @@ module Sequence
     end
 
     def request(path, body = {})
-      request_full_resp(path, body)[:parsed_body]
+      request_full_resp(nil, path, body)[:parsed_body]
     end
 
-    def request_full_resp(path, body={})
-      refresh!
-
-      response = @ledger_api.post(ledger_url(path), body)
-      req_id = response['Chain-Request-ID']
-      unless req_id.is_a?(String) && req_id.size > 0
-        raise InvalidRequestIDError.new(response)
-      end
-
-      status = Integer(response.code)
-      parsed_body = nil
-      if status != 204 # No Content
-        begin
-          parsed_body = JSON.parse(response.body)
-        rescue JSON::JSONError
-          raise JSONError.new(req_id, response)
+    def request_full_resp(id, path, body = {})
+      refresh!(id)
+      id ||= SecureRandom.hex(10)
+      @ledger_api.post(id, ledger_url(path), body) do |response|
+        # require that the response contains the Chain-Request-ID
+        # http header. Since the Sequence API will always set this
+        # header, its absence indicates that the request stopped at
+        # some intermediary like a proxy on the local network or
+        # a Sequence load balancer. This error will be retried by
+        # HttpWrapper.post.
+        req_id = response['Chain-Request-ID']
+        unless req_id.is_a?(String) && req_id.size > 0
+          raise InvalidRequestIDError.new(response)
         end
       end
-      if status / 100 != 2
-        klass = status == 401 ? UnauthorizedError : APIError
-        raise klass.new(parsed_body, response)
-      end
-
-      {parsed_body: parsed_body, response: response}
     end
 
     private
@@ -77,14 +69,13 @@ module Sequence
       "/#{@team_name}/#{@ledger}/#{path}"
     end
 
-    def refresh!
+    def refresh!(id)
       return if @refresh_at > Time.now.to_i
 
       result = if @refresh_method
         @refresh_method.call(@macaroon)
       else
-        r = @session_api.post('/sessions/validate', {macaroon: @macaroon})
-        JSON.parse(r.body)
+        @session_api.post(id, '/sessions/validate', macaroon: @macaroon)[:parsed_body]
       end
 
       @team_name = result['team_name']

data/lib/sequence/stats.rb

@@ -4,8 +4,8 @@ require_relative './query'
 
 module Sequence
   # An object describing summary information about a ledger.
+  # @private
   class Stats < ResponseObject
-
     # @!attribute [r] asset_count
     # The number of assets in the ledger.
     # @return [Integer]
@@ -28,6 +28,5 @@ module Sequence
         Stats.new(client.session.request('stats'))
       end
     end
-
   end
 end

data/lib/sequence/transaction.rb

@@ -3,47 +3,50 @@ require 'securerandom'
 require_relative './client_module'
 require_relative './query'
 require_relative './response_object'
+require_relative './validations'
 
 module Sequence
   # A transaction is an atomic update to the state of the ledger. Transactions
   # can issue new asset units, transfer of asset units from one account to
   # another, and/or the retire asset units from an account.
   class Transaction < ResponseObject
-
     # @!attribute [r] id
-    # A unique ID.
+    #   A unique ID.
     # @return [String]
     attrib :id
 
     # @!attribute [r] timestamp
-    # Time of transaction.
+    #   Time of transaction.
     # @return [Time]
     attrib :timestamp, rfc3339_time: true
 
     # @!attribute [r] sequence_number
-    # Sequence number of the transaction.
+    #   Sequence number of the transaction.
     # @return [Integer]
     attrib :sequence_number
 
     # @!attribute [r] reference_data
-    # User-specified key-value data embedded into the transaction.
+    #   User-specified key-value data embedded into the transaction.
     # @return [Hash]
     attrib :reference_data
 
     # @!attribute [r] actions
-    # List of actions taken by the transaction.
+    #   List of actions taken by the transaction.
     # @return [Array<Action>]
     attrib(:actions) { |raw| raw.map { |v| Action.new(v) } }
 
     # @!attribute [r] contracts
-    # List of contracts created by the transaction.
+    #   List of contracts created by the transaction.
     # @return [Array<Contract>]
     attrib(:contracts) { |raw| raw.map { |v| Contract.new(v) } }
 
     class ClientModule < Sequence::ClientModule
       # Builds, signs, and submits a transaction.
-      # @param [Builder] builder Builder object with actions defined. If provided, overrides block parameter.
-      # @yield Block defining transaction actions. A {Builder} object is passed as the only parameter.
+      # @param [Builder] builder
+      #   Builder object with actions defined. If provided, overrides block
+      #   parameter.
+      # @yield Block defining transaction actions. A {Builder} object is passed
+      #   as the only parameter.
       # @return Transaction
       def transact(builder = nil, &block)
         if builder.nil?
@@ -55,18 +58,25 @@ module Sequence
           '/sign-transaction',
           transaction: tpl,
         )
-        Transaction.new(client.session.request(
-          'submit-transaction',
-          {transaction: tpl}
-        ))
+        Transaction.new(
+          client.session.request('submit-transaction', transaction: tpl),
+        )
       end
 
       # Executes a query, returning an enumerable over individual transactions.
       # @param [Hash] opts Options hash
-      # @option opts [String] filter A filter expression.
-      # @option opts [Array<String|Integer>] filter_params A list of values that will be interpolated into the filter expression.
-      # @option opts [Integer] start_time A Unix timestamp in milliseconds of the earliest transaction timestamp to include in the query results.
-      # @option opts [Integer] end_time A Unix timestamp in milliseconds of the most recent transaction timestamp to include in the query results.
+      # @option opts [String] filter
+      #   A filter expression.
+      # @option opts [Array<String|Integer>] filter_params
+      #   A list of values that will be interpolated into the filter expression.
+      # @option opts [Integer] start_time
+      #   A Unix timestamp in milliseconds of the earliest transaction timestamp
+      #   to include in the query results.
+      # @option opts [Integer] end_time
+      #   A Unix timestamp in milliseconds of the most recent transaction
+      #   timestamp to include in the query results.
+      # @option opts [Integer>] page_size
+      #   The number of items to return in the result set.
       # @return [Query]
       def query(opts = {})
         Query.new(client, opts)
@@ -86,72 +96,80 @@ module Sequence
     # An action taken by a transaction.
     class Action < ResponseObject
       # @!attribute [r] type
-      # The type of the action. Possible values are "issue", "transfer" and "retire".
+      #   The type of the action. Possible values are "issue", "transfer" and
+      #   "retire".
       # @return [String]
       attrib :type
 
       # @!attribute [r] asset_id
-      # The id of the action's asset.
+      #   The id of the action's asset.
       # @return [String]
       attrib :asset_id
 
       # @!attribute [r] asset_alias
-      # The alias of the action's asset.
+      #   The alias of the action's asset.
       # @return [String]
       attrib :asset_alias
 
       # @!attribute [r] asset_tags
-      # The tags of the action's asset.
+      #   The tags of the action's asset.
       # @return [Hash]
       attrib :asset_tags
 
       # @!attribute [r] amount
-      # The number of asset units issues, transferred, or retired.
+      #   The number of asset units issues, transferred, or retired.
       # @return [Integer]
       attrib :amount
 
       # @!attribute [r] source_account_id
-      # The ID of the account serving as the source of asset units. Null for issuances.
+      #   The ID of the account serving as the source of asset units. Null for
+      #   issuances.
       # @return [String]
       attrib :source_account_id
 
       # @!attribute [r] source_account_alias
-      # The alias of the account serving as the source of asset units. Null for issuances.
+      #   The alias of the account serving as the source of asset units. Null
+      #   for issuances.
       # @return [String]
       attrib :source_account_alias
 
       # @!attribute [r] source_account_tags
-      # The tags of the account serving as the source of asset units. Null for issuances.
+      #   The tags of the account serving as the source of asset units. Null for
+      #   issuances.
       # @return [String]
       attrib :source_account_tags
 
       # @!attribute [r] destination_account_id
-      # The ID of the account receiving the asset units. Null for retirements.
+      #   The ID of the account receiving the asset units. Null for retirements.
       # @return [String]
       attrib :destination_account_id
 
       # @!attribute [r] destination_account_alias
-      # The alias of the account receiving the asset units. Null for retirements.
+      #   The alias of the account receiving the asset units. Null for
+      #   retirements.
       # @return [String]
       attrib :destination_account_alias
 
       # @!attribute [r] destination_account_tags
-      # The tags of the account receiving the asset units. Null for retirements.
+      #   The tags of the account receiving the asset units. Null for
+      #   retirements.
       # @return [String]
       attrib :destination_account_tags
 
       # @!attribute [r] reference_data
-      # User-specified, key-value data embedded into the action.
+      #   User-specified, key-value data embedded into the action.
       # @return [Hash]
       attrib :reference_data
     end
 
     # A configuration object for creating and submitting transactions.
     class Builder
+      include Sequence::Validations
+
       attr_accessor :reference_data
 
       def initialize(&block)
-        block.call(self) if block
+        yield(self) if block
       end
 
       def actions
@@ -170,78 +188,165 @@ module Sequence
       end
 
       # Adds an action to a transaction builder.
-      # @param [Hash] params Action parameters.
+      # @param [Hash] opts
+      #   Action parameters.
       # @return [Builder]
-      def add_action(params)
-        # Some actions require an idempotency token, so we'll add it here as a
-        # generic parameter.
-        params = {client_token: SecureRandom.uuid}.merge(params)
-        actions << params
+      def add_action(opts = {})
+        if opts[:amount].nil?
+          raise ArgumentError, ':amount must be provided'
+        end
+        actions << opts
         self
       end
 
       # Issues new units of an asset to a destination account.
       #
-      # @param [Hash] params Options hash
-      # @option params [String] :asset_id ID of the asset to be issued.
-      #                                   You must specify either an ID or an alias.
-      # @option params [String] :asset_alias Asset alias of the asset to be issued.
-      #                                   You must specify either an ID or an alias.
-      # @option params [Integer] :amount amount of the asset to be issued.
-      # @option params [String] :destination_account_id ID of the account receiving the asset units.
-      #                                   You must specify a destination account ID or alias.
-      # @option params [String] :destination_account_alias alias of the account receiving the asset units.
-      #                                   You must specify a destination account ID or alias.
-      # @option params [Hash] :reference_data reference data for the action.
+      # @param [Hash] opts
+      #   Options hash
+      # @option opts [Integer] :amount
+      #   Amount of the asset to be issued.
+      # @option opts [String] :asset_id
+      #   ID of the asset to be issued. You must specify either an ID or an
+      #   alias.
+      # @option opts [String] :asset_alias
+      #   Asset alias of the asset to be issued. You must specify either an ID
+      #   or an alias.
+      # @option opts [String] :destination_account_id
+      #   ID of the account receiving the asset units. You must specify a
+      #   destination account ID or alias.
+      # @option opts [String] :destination_account_alias
+      #   Alias of the account receiving the asset units. You must specify a
+      #   destination account ID or alias.
+      # @option opts [Hash] :reference_data
+      #   Reference data for the action.
       # @return [Builder]
-      def issue(params)
-        add_action(params.merge(type: :issue))
+      def issue(opts = {})
+        validate_inclusion_of!(
+          opts,
+          :amount,
+          :asset_id,
+          :asset_alias,
+          :destination_account_id,
+          :destination_account_alias,
+          :reference_data,
+        )
+        validate_either!(opts, :asset_id, :asset_alias)
+        validate_either!(
+          opts,
+          :destination_account_id,
+          :destination_account_alias,
+        )
+        add_action(opts.merge(type: :issue))
       end
 
-      # Moves units of an asset from a source (an account or contract) to a destination account.
+      # Moves units of an asset from a source (an account or contract) to a
+      # destination account.
       #
-      # @param [Hash] params Options hash
-      # @option params [String] :source_account_id ID of the account serving as the source of asset units.
-      #                                   You must specify a source account ID, account alias, or contract ID.
-      # @option params [String] :source_account_alias Alias of the account serving as the source of asset units
-      #                                   You must specify a source account ID, account alias, or contract ID.
-      # @option params [String] :source_contract_id ID of the contract serving as the source of asset units.
-      #                                   You must specify a source account ID, account alias, or contract ID.
-      # @option params [String] :asset_id ID of the asset to be transferred.
-      #                                   You must specify either an ID or an alias.
-      # @option params [String] :asset_alias Asset alias of the asset to be transferred.
-      #                                   You must specify either an ID or an alias.
-      # @option params [Integer] :amount amount of the asset to be transferred.
-      # @option params [String] :destination_account_id ID of the account receiving the asset units.
-      #                                   You must specify a destination account ID or alias.
-      # @option params [String] :destination_account_alias alias of the account receiving the asset units.
-      #                                   You must specify a destination account ID or alias.
-      # @option params [Hash] :reference_data reference data for the action.
-      # @option params [Hash] :change_reference_data reference data for the change contract.
+      # @param [Hash] opts
+      #   Options hash
+      # @option opts [Integer] :amount
+      #   Amount of the asset to be transferred.
+      # @option opts [String] :asset_id
+      #   ID of the asset to be transferred. You must specify either an ID or an
+      #   alias.
+      # @option opts [String] :asset_alias
+      #   Asset alias of the asset to be transferred. You must specify either an
+      #   ID or an alias.
+      # @option opts [String] :source_account_id
+      #   ID of the account serving as the source of asset units. You must
+      #   specify a source account ID, account alias, or contract ID.
+      # @option opts [String] :source_account_alias
+      #   Alias of the account serving as the source of asset units You must
+      #   specify a source account ID, account alias, or contract ID.
+      # @option opts [String] :source_contract_id
+      #   ID of the contract serving as the source of asset units. You must
+      #   specify a source account ID, account alias, or contract ID.
+      # @option opts [String] :destination_account_id
+      #   ID of the account receiving the asset units. You must specify a
+      #   destination account ID or alias.
+      # @option opts [String] :destination_account_alias
+      #   Alias of the account receiving the asset units. You must specify a
+      #   destination account ID or alias.
+      # @option opts [Hash] :reference_data
+      #   reference data for the action.
+      # @option opts [Hash] :change_reference_data
+      #   reference data for the change contract.
       # @return [Builder]
-      def transfer(params)
-        add_action(params.merge(type: :transfer))
+      def transfer(opts = {})
+        validate_inclusion_of!(
+          opts,
+          :amount,
+          :asset_id,
+          :asset_alias,
+          :source_account_id,
+          :source_account_alias,
+          :source_contract_id,
+          :destination_account_id,
+          :destination_account_alias,
+          :reference_data,
+          :change_reference_data,
+        )
+        validate_either!(opts, :asset_id, :asset_alias)
+        validate_either!(
+          opts,
+          :source_account_id,
+          :source_account_alias,
+          :source_contract_id,
+        )
+        validate_either!(
+          opts,
+          :destination_account_id,
+          :destination_account_alias,
+        )
+        add_action(opts.merge(type: :transfer))
       end
 
-      # Takes units of an asset from a source (an account or contract) and retires them.
+      # Takes units of an asset from a source (an account or contract) and
+      # retires them.
       #
-      # @param [Hash] params Options hash
-      # @option params [String] :source_account_id ID of the account serving as the source of asset units.
-      #                                   You must specify a source account ID, account alias, or contract ID.
-      # @option params [String] :source_account_alias Alias of the account serving as the source of asset units
-      #                                   You must specify a source account ID, account alias, or contract ID.
-      # @option params [String] :source_contract_id ID of the contract serving as the source of asset units.
-      #                                   You must specify a source account ID, account alias, or contract ID.
-      # @option params [String] :asset_id ID of the asset to be retired.
-      #                                   You must specify either an ID or an alias.
-      # @option params [String] :asset_alias Asset alias of the asset to be retired.
-      #                                   You must specify either an ID or an alias.
-      # @option params [Integer] :amount amount of the asset to be retired.
-      # @option params [Hash] :reference_data reference data for the action.
-      # @option params [Hash] :change_reference_data reference data for the change contract.
+      # @param [Hash] opts Options hash
+      # @option opts [Integer] :amount
+      #   Amount of the asset to be retired.
+      # @option opts [String] :asset_id
+      #   ID of the asset to be retired. You must specify either an ID or an
+      #   alias.
+      # @option opts [String] :asset_alias
+      #   Asset alias of the asset to be retired. You must specify either an ID
+      #   or an alias.
+      # @option opts [String] :source_account_id
+      #   ID of the account serving as the source of asset units. You must
+      #   specify a source account ID, account alias, or contract ID.
+      # @option opts [String] :source_account_alias
+      #   Alias of the account serving as the source of asset units You must
+      #   specify a source account ID, account alias, or contract ID.
+      # @option opts [String] :source_contract_id
+      #   ID of the contract serving as the source of asset units. You must
+      #   specify a source account ID, account alias, or contract ID.
+      # @option opts [Hash] :reference_data
+      #   Reference data for the action.
+      # @option opts [Hash] :change_reference_data
+      #   Reference data for the change contract.
       # @return [Builder]
-      def retire(params)
-        add_action(params.merge(type: :retire))
+      def retire(opts = {})
+        validate_inclusion_of!(
+          opts,
+          :amount,
+          :asset_id,
+          :asset_alias,
+          :source_account_id,
+          :source_account_alias,
+          :source_contract_id,
+          :reference_data,
+          :change_reference_data,
+        )
+        validate_either!(opts, :asset_id, :asset_alias)
+        validate_either!(
+          opts,
+          :source_account_id,
+          :source_account_alias,
+          :source_contract_id,
+        )
+        add_action(opts.merge(type: :retire))
       end
     end
   end