mixin_bot 1.4.0 → 2.0.0

data/lib/mixin_bot/cli/api.rb

@@ -1,214 +1,295 @@
 # frozen_string_literal: true
 
 module MixinBot
-  class CLI < Thor
-    desc 'api PATH', 'request PATH of Mixin API'
+  class CLI
+    desc 'api PATH', 'Signed GET/POST request to a Mixin API path'
     long_desc <<-LONGDESC
-      use `mixinbot api PATH` to request any Mixin API
+      Use `mixinbot api PATH` to call any Mixin REST endpoint via MixinBot::Client.
 
-      Get user infomation:
+      Get user information:
 
       $ mixinbot api /me -k ~/.mixinbot/keystore.json
 
-      Search user infomation:
+      Search user:
 
       $ mixinbot api /search/1051445 -k ~/.mixinbot/keystore.json
 
-      Generate a multisig payment:
+      POST with JSON body:
 
-      $ mixinbot api /payments -k ~/.mixinbot/keystore.json -m POST -d '{"asset_id":"965e5c6e-434c-3fa9-b780-c50f43cd955c", "amount":"1", "trace_id": "37f16abb-0640-4d01-9423-a06121732d35", "memo":"test", "opponent_multisig":{"receivers":["0508a116-1239-4e28-b150-85a8e3e6b400", "7ed9292d-7c95-4333-aa48-a8c640064186", "a67c6e87-1c9e-4a1c-b81c-47a9f4f1bff1"], "threshold":2}}'
+      $ mixinbot api /payments -k keystore.json -m POST -d '{"asset_id":"..."}'
     LONGDESC
     option :keystore, type: :string, aliases: '-k', required: true, desc: 'keystore or keystore.json file path'
-    option :method, type: :string, aliases: '-m', default: 'GET', desc: 'HTTP method, GET or POST'
-    option :params, type: :hash, aliases: '-p', desc: 'HTTP GET params'
-    option :data, type: :string, aliases: '-d', default: '{}', desc: 'HTTP POST data'
-    option :accesstoken, type: :string, aliases: '-t', desc: 'Specify a accesstoken, or will generate by keystore'
+    option :method, type: :string, aliases: '-m', default: 'GET', desc: 'HTTP method: GET or POST'
+    option :params, type: :hash, aliases: '-p', desc: 'HTTP GET query parameters'
+    option :data, type: :string, aliases: '-d', default: '{}', desc: 'HTTP POST JSON body (object or array)'
+    option :accesstoken, type: :string, aliases: '-t', desc: 'Override JWT access token'
+    option :data_only, type: :boolean, default: true, desc: 'Print only response data (default: true)'
     def api(path)
-      path = "#{path}?#{URI.encode_www_form(options[:params])}" if options[:params].present?
-      payload =
-        begin
-          JSON.parse options[:data]
-        rescue JSON::ParserError => e
-          log UI.fmt("{{x}} #{e.inspect}")
-          {}
+      with_command_name('api') do
+        setup_api_instance!
+        verb = options[:method].to_s.upcase
+        abort_with_error("unsupported HTTP method #{verb} (use GET or POST)", kind: :unsupported) unless %w[GET POST].include?(verb)
+
+        path_with_query = path
+        path_with_query = "#{path}?#{URI.encode_www_form(options[:params])}" if options[:params].present?
+
+        payload = parse_api_body(options[:data])
+        res = with_spinner("#{verb} #{path_with_query}") do
+          case verb
+          when 'GET'
+            api_instance.client.get(
+              path_with_query,
+              access_token: options[:accesstoken]
+            )
+          when 'POST'
+            post_via_client(path, payload, access_token: options[:accesstoken])
+          end
         end
 
-      access_token = options[:accesstoken] || api_instance.access_token(options[:method].upcase, path, payload.blank? ? '' : payload.to_json)
-      authorization = format('Bearer %<access_token>s', access_token:)
-      res = {}
-
-      CLI::UI::Spinner.spin("#{options[:method]} #{path}, payload: #{payload}") do |_spinner|
-        res =
-          case options[:method].downcase.to_sym
-          when :post
-            api_instance.client.post(path, headers: { Authorization: authorization }, json: payload)
-          when :get
-            api_instance.client.get(path, headers: { Authorization: authorization })
-          end
+        print_result(res, data_only: options[:data_only], command: 'api')
       end
-
-      log res['data']
+    rescue MixinBot::Error => e
+      abort_with_error(e.message, exception: e)
     end
 
-    desc 'authcode', 'code to authorize other mixin account'
+    desc 'authcode', 'OAuth authorization code for another Mixin account'
     option :keystore, type: :string, aliases: '-k', required: true, desc: 'keystore or keystore.json file path'
-    option :app_id, type: :string, required: true, aliases: '-c', desc: 'app_id of bot to authorize'
-    option :scope, type: :array, default: ['PROFILE:READ'], aliases: '-s', desc: 'scope to authorize'
+    option :app_id, type: :string, required: true, aliases: '-c', desc: 'client_id of the app to authorize'
+    option :scope, type: :array, default: ['PROFILE:READ'], aliases: '-s', desc: 'OAuth scopes'
     def authcode
-      res = {}
-      CLI::UI::Spinner.spin('POST /oauth/authorize') do |_spinner|
-        res =
+      with_command_name('authcode') do
+        setup_api_instance!
+        res = with_spinner('POST /oauth/authorize') do
           api_instance.authorize_code(
             user_id: options[:app_id],
             scope: options[:scope],
             pin: keystore['pin']
           )
+        end
+        print_result(res, data_only: true, command: 'authcode')
       end
-      log res['data']
+    rescue MixinBot::Error => e
+      abort_with_error(e.message, exception: e)
     end
 
-    desc 'updatetip PIN', 'update TIP pin'
+    desc 'updatetip PIN', 'Update TIP PIN'
     option :keystore, type: :string, aliases: '-k', required: true, desc: 'keystore or keystore.json file path'
     def updatetip(pin)
-      profile = api_instance.me
-      log UI.fmt "{{v}} #{profile['full_name']}, TIP counter: #{profile['tip_counter']}"
+      with_command_name('updatetip') do
+        setup_api_instance!
+        profile = api_instance.me
+        emit_info("#{profile['full_name']}, TIP counter: #{profile['tip_counter']}")
 
-      counter = profile['tip_counter']
-      key = api_instance.prepare_tip_key counter
-      log UI.fmt "{{v}} Generated key: #{key[:private_key]}"
+        counter = profile['tip_counter']
+        key = api_instance.prepare_tip_key counter
+        emit_info("Generated key: #{key[:private_key]}")
 
-      res = api_instance.update_pin old_pin: pin.to_s, pin: key[:public_key]
+        res = api_instance.update_tip_pin(pin.to_s, key[:public_key])
 
-      log({
-            pin: key[:private_key],
-            tip_key_base64: res['tip_key_base64']
-          })
-    rescue StandardError => e
-      log UI.fmt "{{x}} #{e.inspect}"
+        emit_success(
+          {
+            'pin' => key[:private_key],
+            'tip_key_base64' => res['tip_key_base64']
+          },
+          command: 'updatetip'
+        )
+      end
+    rescue MixinBot::Error => e
+      abort_with_error(e.message, exception: e)
     end
 
-    desc 'verifypin PIN', 'verify pin'
+    desc 'verifypin PIN', 'Verify PIN'
     option :keystore, type: :string, aliases: '-k', required: true, desc: 'keystore or keystore.json file path'
     def verifypin(pin)
-      res = api_instance.verify_pin pin.to_s
-
-      log res
-    rescue StandardError => e
-      log UI.fmt "{{x}} #{e.inspect}"
+      with_command_name('verifypin') do
+        setup_api_instance!
+        res = api_instance.verify_pin pin.to_s
+        print_result(res, command: 'verifypin')
+      end
+    rescue MixinBot::Error => e
+      abort_with_error(e.message, exception: e)
     end
 
-    desc 'transfer USER_ID', 'transfer asset to USER_ID'
+    desc 'transfer USER_ID', 'Safe transfer to USER_ID'
     option :asset, type: :string, required: true, desc: 'Asset ID'
-    option :amount, type: :numeric, required: true, desc: 'Amount'
-    option :memo, type: :string, required: false, desc: 'memo'
+    option :amount, type: :string, required: true, desc: 'Amount'
+    option :memo, type: :string, required: false, desc: 'Memo'
+    option :trace, type: :string, required: false, desc: 'Trace ID'
+    option :spend_key, type: :string, required: false, desc: 'Spend private key (hex); defaults to keystore spend_key'
     option :keystore, type: :string, aliases: '-k', required: true, desc: 'keystore or keystore.json file path'
+    option :dry_run, type: :boolean, default: false, desc: 'Validate and print transfer kwargs without submitting'
     def transfer(user_id)
-      res = {}
+      with_command_name('transfer') do
+        setup_api_instance!
+        perform_safe_transfer(user_id)
+      end
+    end
 
-      CLI::UI::Spinner.spin "Try to transfer #{options[:amount]} #{options[:asset]} to #{user_id}" do |_spinner|
-        res = api_instance.create_transfer(
-          keystore['pin'],
-          {
+    desc 'legacy-transfer USER_ID', 'Legacy POST /transfers (deprecated)'
+    option :asset, type: :string, required: true, desc: 'Asset ID'
+    option :amount, type: :numeric, required: true, desc: 'Amount'
+    option :memo, type: :string, required: false, desc: 'Memo'
+    option :keystore, type: :string, aliases: '-k', required: true, desc: 'keystore or keystore.json file path'
+    def legacy_transfer(user_id)
+      with_command_name('legacy-transfer') do
+        setup_api_instance!
+        warn_deprecated('legacy-transfer uses deprecated POST /transfers; use `transfer` (Safe API) instead')
+        res = with_spinner("Legacy transfer #{options[:amount]} #{options[:asset]} to #{user_id}") do
+          api_instance.create_transfer(
+            keystore['pin'],
             asset_id: options[:asset],
             opponent_id: user_id,
             amount: options[:amount],
             memo: options[:memo]
-          }
-        )
-      end
+          )
+        end
 
-      return unless res['snapshot_id'].present?
+        emit_transfer_result(res)
+      end
+    rescue MixinBot::Error => e
+      abort_with_error(e.message, exception: e)
+    end
 
-      log UI.fmt "{{v}} Finished: https://mixin.one/snapshots/#{res['snapshot_id']}"
+    desc 'safetransfer USER_ID', 'Alias for transfer (deprecated name)'
+    option :asset, type: :string, required: true, desc: 'Asset ID'
+    option :amount, type: :string, required: true, desc: 'Amount'
+    option :trace, type: :string, required: false, desc: 'Trace ID'
+    option :memo, type: :string, required: false, desc: 'Memo'
+    option :spend_key, type: :string, required: false, desc: 'Spend private key (hex)'
+    option :keystore, type: :string, aliases: '-k', required: true, desc: 'keystore or keystore.json file path'
+    option :dry_run, type: :boolean, default: false, desc: 'Validate and print transfer kwargs without submitting'
+    def safetransfer(user_id)
+      warn_deprecated('safetransfer is deprecated; use `transfer` instead')
+      transfer(user_id)
     end
 
-    desc 'saferegister', 'register SAFE network'
-    option :spend_key, type: :string, required: true, desc: 'spend_key'
+    desc 'saferegister', 'Register on SAFE network'
+    option :spend_key, type: :string, required: true, desc: 'Spend private key'
     option :keystore, type: :string, aliases: '-k', required: true, desc: 'keystore or keystore.json file path'
     def saferegister
-      res = api_instance.safe_register options[:spend_key]
-      log res
+      with_command_name('saferegister') do
+        setup_api_instance!
+        res = api_instance.safe_register options[:spend_key]
+        print_result(res, command: 'saferegister')
+      end
+    rescue MixinBot::Error => e
+      abort_with_error(e.message, exception: e)
     end
 
-    desc 'pay', 'generate payment url'
-    option :members, type: :array, required: true, desc: 'Reveivers, maybe multisig'
-    option :threshold, type: :numeric, required: false, default: 1, desc: 'Threshold of multisig'
+    desc 'pay', 'Generate Safe payment URL'
+    option :members, type: :array, required: true, desc: 'Receivers (supports multisig)'
+    option :threshold, type: :numeric, required: false, default: 1, desc: 'Multisig threshold'
     option :asset, type: :string, required: true, desc: 'Asset ID'
-    option :amount, type: :numeric, required: true, desc: 'Amount'
+    option :amount, type: :string, required: true, desc: 'Amount'
     option :trace, type: :string, required: false, desc: 'Trace ID'
-    option :memo, type: :string, required: false, desc: 'memo'
+    option :memo, type: :string, required: false, desc: 'Memo'
     def pay
-      url = api_instance.safe_pay_url(
-        members: options[:members],
-        threshold: options[:threshold],
-        asset_id: options[:asset],
-        amount: options[:amount],
-        trace_id: options[:trace],
-        memo: options[:memo]
-      )
+      with_command_name('pay') do
+        setup_api_instance!
+        url = api_instance.safe_pay_url(
+          members: options[:members],
+          threshold: options[:threshold],
+          asset_id: options[:asset],
+          amount: options[:amount],
+          trace_id: options[:trace],
+          memo: options[:memo]
+        )
 
-      log UI.fmt "{{v}} #{url}"
+        emit_success({ 'url' => url }, command: 'pay')
+      end
+    rescue MixinBot::Error => e
+      abort_with_error(e.message, exception: e)
     end
 
-    desc 'safetransfer USER_ID', 'transfer asset to USER_ID with SAFE network'
-    option :asset, type: :string, required: true, desc: 'Asset ID'
-    option :amount, type: :numeric, required: true, desc: 'Amount'
-    option :trace, type: :string, required: false, desc: 'Trace ID'
-    option :memo, type: :string, required: false, desc: 'memo'
-    option :keystore, type: :string, aliases: '-k', required: true, desc: 'keystore or keystore.json file path'
-    def safetransfer(user_id)
-      amount = options[:amount].to_d
-      asset = options[:asset]
-      memo = options[:memo] || ''
+    private
+
+    def with_spinner(title)
+      if spinner_enabled?
+        CLI::UI::Spinner.spin(title) { |_spinner| yield }
+      else
+        yield
+      end
+    end
+
+    def spinner_enabled?
+      ENV['MIXINBOT_NO_SPINNER'].to_s != '1' && $stdout.tty? && !structured_output?
+    end
 
-      # step 1: select inputs
-      outputs = api_instance.safe_outputs(state: 'unspent', asset_id: asset, limit: 500)['data'].sort_by { |o| o['amount'].to_d }
-      balance = outputs.sum(&->(output) { output['amount'].to_d })
+    def parse_api_body(json_string)
+      return nil if json_string.blank? || json_string == '{}'
 
-      utxos = []
-      outputs.each do |output|
-        break if utxos.sum { |o| o['amount'].to_d } >= amount
+      JSON.parse(json_string)
+    rescue JSON::ParserError => e
+      abort_with_error("invalid JSON body: #{e.message}", kind: :invalid_args)
+    end
+
+    def post_via_client(path, payload, access_token: nil)
+      client = api_instance.client
+      token_opt = { access_token: access_token.presence }.compact
+
+      if payload.is_a?(Array)
+        client.fetch_post_array(path, payload, **token_opt)
+      elsif payload.is_a?(Hash)
+        client.fetch_post(path, body: payload, **token_opt)
+      elsif payload.nil?
+        client.post(path, **token_opt)
+      else
+        abort_with_error('POST body must be a JSON object or array', kind: :invalid_args)
+      end
+    end
+
+    def build_transfer_opts(user_id)
+      transfer_opts = {
+        members: [user_id],
+        threshold: 1,
+        asset_id: options[:asset],
+        amount: options[:amount].to_s,
+        memo: options[:memo] || ''
+      }
+      transfer_opts[:trace_id] = options[:trace] if options[:trace].present?
+      spend = options[:spend_key] || keystore&.dig('spend_key')
+      transfer_opts[:spend_key] = spend if spend.present?
+      transfer_opts
+    end
 
-        utxos.shift if utxos.size >= 255
-        utxos << output
+    def perform_safe_transfer(user_id)
+      transfer_opts = build_transfer_opts(user_id)
+
+      if options[:dry_run]
+        emit_success(
+          { 'dry_run' => true, 'method' => 'create_safe_transfer', 'kwargs' => transfer_opts.transform_keys(&:to_s) },
+          command: 'transfer'
+        )
+        return
+      end
+
+      res = with_spinner(
+        "Safe transfer #{transfer_opts[:amount]} #{transfer_opts[:asset_id]} to #{user_id}"
+      ) do
+        api_instance.create_safe_transfer(**transfer_opts)
       end
 
-      log UI.fmt "Step 1/7: {{v}} Found #{outputs.count} unspent outputs, balance: #{balance}, selected #{utxos.count} outputs"
-
-      # step 2: build transaction
-      tx = api_instance.build_safe_transaction(
-        utxos:,
-        receivers: [
-          members: [user_id],
-          threshold: 1,
-          amount:
-        ],
-        extra: memo
-      )
-      raw = MixinBot::Utils.encode_raw_transaction tx
-      log UI.fmt "Step 2/5: {{v}} Built raw: #{raw}"
-
-      # step 3: verify transaction
-      request_id = SecureRandom.uuid
-      request = api_instance.create_safe_transaction_request(request_id, raw)['data']
-      log UI.fmt "Step 3/5: {{v}} Verified transaction, request_id: #{request[0]['request_id']}"
-
-      # step 4: sign transaction
-      signed_raw = api_instance.sign_safe_transaction(
-        raw:,
-        utxos:,
-        request: request[0]
-      )
-      log UI.fmt "Step 4/5: {{v}} Signed transaction: #{signed_raw}"
-
-      # step 5: submit transaction
-      r = api_instance.send_safe_transaction(
-        request_id,
-        signed_raw
-      )
-      log UI.fmt "Step 5/5: {{v}} Submit transaction, hash: #{r['data'].first['transaction_hash']}"
-    rescue StandardError => e
-      log UI.fmt "{{x}} #{e.inspect}"
+      emit_transfer_result(res)
+    rescue MixinBot::Error => e
+      abort_with_error(e.message, exception: e)
+    end
+
+    def emit_transfer_result(res)
+      data = res['data'] if res.respond_to?(:[])
+      tx_hash = data.is_a?(Array) ? data.first&.dig('transaction_hash') : nil
+      snapshot_id = res['snapshot_id'] if res.respond_to?(:[])
+
+      if tx_hash.present?
+        payload = { 'transaction_hash' => tx_hash }
+        emit_info("Submitted: transaction_hash=#{tx_hash}")
+        emit_success(payload, command: current_command_name)
+      elsif snapshot_id.present?
+        url = "https://mixin.one/snapshots/#{snapshot_id}"
+        emit_info("Finished: #{url}")
+        emit_success({ 'snapshot_id' => snapshot_id, 'url' => url }, command: current_command_name)
+      else
+        print_result(res, command: current_command_name)
+      end
     end
   end
 end

data/lib/mixin_bot/cli/base.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module MixinBot
+  ##
+  # Registry and predicates for mixinbot `call` / `list` commands.
+  #
+  module CLIHelpers
+    API_EXCLUDED_METHODS = %i[
+      initialize
+      client
+      config
+      utils
+      client_id
+      access_token
+      sign_authentication_token
+      sign_authentication_token_without_body
+      sign_authentication_token_with_request_id
+      encode_raw_transaction
+      decode_raw_transaction
+      generate_trace_from_hash
+      encode_raw_transaction_native
+      decode_raw_transaction_native
+      warn_legacy_mixin_api!
+      ensure_mixin_command_exist
+      command?
+    ].freeze
+
+    INTERACTIVE_API_METHODS = %i[
+      start_blaze_connect
+      blaze
+      upload_attachment
+    ].freeze
+
+    module_function
+
+    def api_callable_methods
+      methods = MixinBot::API.instance_methods(false)
+      MixinBot::API.included_modules.each do |mod|
+        next unless mod.name&.start_with?('MixinBot::API::')
+
+        methods.concat(mod.instance_methods(false))
+      end
+
+      methods
+        .map(&:to_sym)
+        .uniq
+        .select { |m| api_method_callable?(m) }
+        .sort
+    end
+
+    def api_method_callable?(method_name)
+      sym = method_name.to_sym
+      return false if API_EXCLUDED_METHODS.include?(sym)
+      return false if INTERACTIVE_API_METHODS.include?(sym)
+
+      MixinBot::API.method_defined?(sym) &&
+        !sym.to_s.start_with?('_')
+    end
+
+    def utils_callable_methods
+      MixinBot::Utils.singleton_methods(false).sort
+    end
+
+    def api_method_owner(method_name)
+      sym = method_name.to_sym
+      return 'MixinBot::API' if MixinBot::API.method_defined?(sym, false)
+
+      MixinBot::API.included_modules.find do |mod|
+        mod.name&.start_with?('MixinBot::API::') && mod.method_defined?(sym, false)
+      end&.name || 'MixinBot::API'
+    end
+
+    def grouped_api_methods
+      api_callable_methods.group_by { |m| api_method_owner(m) }.sort_by { |k, _| k }
+    end
+  end
+end

data/lib/mixin_bot/cli/call.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module MixinBot
+  class CLI
+    desc 'call METHOD', 'Invoke a MixinBot::API method with JSON keyword arguments'
+    long_desc <<-LONGDESC
+      Invoke any public API method (see `mixinbot list`).
+
+      Examples:
+
+        $ mixinbot call me -k ~/.mixinbot/keystore.json
+        $ mixinbot call safe_outputs -k keystore.json -d '{"asset":"...","state":"unspent","limit":10}'
+        $ mixinbot call user USER_ID -k keystore.json
+        $ mixinbot call create_transfer -k keystore.json -d '{"members":"uuid","asset_id":"...","amount":"0.01"}'
+    LONGDESC
+    option :keystore, type: :string, aliases: '-k', desc: 'keystore JSON file path or inline JSON'
+    option :data, type: :string, aliases: '-d', default: '{}', desc: 'JSON object of keyword arguments'
+    option :data_only, type: :boolean, default: false, desc: 'Print only the data field of API responses'
+    def call(method_name, *positional)
+      with_command_name('call') do
+        setup_api_instance!
+        kwargs = parse_json_data(options[:data])
+        result = invoke_api(method_name, kwargs:, positional:)
+        print_result(result, data_only: options[:data_only], command: 'call')
+      end
+    end
+
+    desc 'list [FILTER]', 'List callable MixinBot::API methods (optional substring filter)'
+    option :limit, type: :numeric, default: 100, desc: 'Maximum items to return'
+    option :offset, type: :numeric, default: 0, desc: 'Number of items to skip'
+    option :fields, type: :string, desc: 'Comma-separated fields for JSON output (name,owner)'
+    def list(filter = nil)
+      with_command_name('list') do
+        methods = CLIHelpers.api_callable_methods
+        if filter.present?
+          needle = filter.downcase
+          methods = methods.select { |m| m.to_s.downcase.include?(needle) }
+        end
+
+        items = methods.map do |name|
+          { 'name' => name.to_s, 'owner' => CLIHelpers.api_method_owner(name) }
+        end
+        items = items.sort_by { |item| [item['owner'], item['name']] }
+
+        page, total, limit, offset = paginate_items(items, limit: options[:limit], offset: options[:offset])
+        page = select_fields(page, options[:fields])
+
+        if structured_output?
+          emit_list(items: page, total:, limit:, offset:, command: 'list')
+        else
+          print_pretty_list(page, total, limit, offset)
+        end
+      end
+    end
+
+    private
+
+    def print_pretty_list(items, total, limit, offset)
+      grouped = items.group_by { |item| item['owner'] }
+      grouped.sort_by { |owner, _| owner }.each do |owner, names|
+        puts "#{owner}:"
+        names.sort_by { |n| n['name'] }.each { |n| puts "  #{n['name']}" }
+        puts
+      end
+
+      return unless total > limit || offset.positive?
+
+      emit_info("Showing #{items.size} of #{total} (limit=#{limit}, offset=#{offset})")
+    end
+  end
+end

data/lib/mixin_bot/cli/errors.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module MixinBot
+  ##
+  # Maps exceptions and messages to clispec error kinds for structured CLI output.
+  #
+  module CLIErrors
+    ERROR_KINDS = {
+      invalid_args: { retryable: false, description: 'Invalid or missing arguments' },
+      auth: { retryable: false, description: 'Authentication or authorization failed' },
+      not_found: { retryable: false, description: 'Requested resource was not found' },
+      api_error: { retryable: false, description: 'Mixin API returned an error' },
+      unsupported: { retryable: false, description: 'Operation is not supported in this context' },
+      conflict: { retryable: false, description: 'Resource exists with incompatible configuration' },
+      internal: { retryable: false, description: 'Unexpected internal error' }
+    }.freeze
+
+    module_function
+
+    def schema_errors
+      ERROR_KINDS.map do |kind, meta|
+        {
+          'kind' => kind.to_s,
+          'retryable' => meta[:retryable],
+          'description' => meta[:description]
+        }
+      end
+    end
+
+    def kind_for_exception(error)
+      case error
+      when MixinBot::ArgumentError, ::ArgumentError
+        :invalid_args
+      when UnauthorizedError, ForbiddenError, PinError, ConfigurationNotValidError
+        :auth
+      when NotFoundError, UserNotFoundError
+        :not_found
+      when ResponseError, RequestError, HttpError,
+           InsufficientBalanceError, UtxoInsufficientError, InsufficientPoolError
+        :api_error
+      else
+        :internal
+      end
+    end
+
+    def kind_for_message(message)
+      msg = message.to_s.downcase
+      return :auth if msg.include?('unauthorized') || msg.include?('authentication')
+      return :not_found if msg.include?('not found') || msg.include?('404')
+      return :unsupported if msg.include?('unsupported') || msg.include?('not supported')
+      return :invalid_args if msg.include?('invalid') || msg.include?('unknown')
+
+      :internal
+    end
+  end
+end