mixin_bot 1.4.0 → 2.0.0

data/lib/mixin_bot/api.rb

@@ -8,10 +8,16 @@ require_relative 'api/asset'
 require_relative 'api/attachment'
 require_relative 'api/auth'
 require_relative 'api/blaze'
+require_relative 'api/chain'
+require_relative 'api/code'
+require_relative 'api/computer_api'
 require_relative 'api/conversation'
+require_relative 'api/deposit'
 require_relative 'api/encrypted_message'
+require_relative 'api/fiat'
 require_relative 'api/inscription'
 require_relative 'api/legacy_collectible'
+require_relative 'api/legacy_user'
 require_relative 'api/legacy_multisig'
 require_relative 'api/legacy_output'
 require_relative 'api/legacy_payment'
@@ -21,21 +27,155 @@ require_relative 'api/legacy_transfer'
 require_relative 'api/me'
 require_relative 'api/message'
 require_relative 'api/multisig'
+require_relative 'api/network'
+require_relative 'api/network_asset'
 require_relative 'api/output'
 require_relative 'api/payment'
+require_relative 'api/pin_payload'
 require_relative 'api/pin'
 require_relative 'api/rpc'
+require_relative 'api/session'
 require_relative 'api/snapshot'
 require_relative 'api/tip'
 require_relative 'api/transaction'
 require_relative 'api/transfer'
+require_relative 'api/turn'
 require_relative 'api/user'
 require_relative 'api/withdraw'
 
 module MixinBot
+  ##
+  # Main API interface for interacting with Mixin Network.
+  #
+  # The API class provides access to all Mixin Network endpoints including:
+  # - User and bot profile management
+  # - Asset management (read assets, check balances)
+  # - Transfers and payments (Safe API and legacy)
+  # - Messaging (send/receive messages via Blaze)
+  # - Conversations and encrypted messages
+  # - Multisig operations
+  # - NFT and collectible operations
+  # - Transaction building and signing
+  # - Withdrawal operations
+  #
+  # == Usage
+  #
+  # === Using Global Configuration
+  #
+  #   MixinBot.configure do
+  #     self.app_id = 'your-app-id'
+  #     self.session_id = 'your-session-id'
+  #     self.session_private_key = 'your-private-key'
+  #     self.server_public_key = 'server-public-key'
+  #   end
+  #
+  #   # Access via global instance
+  #   MixinBot.api.me
+  #   MixinBot.api.assets
+  #
+  # === Creating Dedicated Instances
+  #
+  #   api = MixinBot::API.new(
+  #     app_id: 'your-app-id',
+  #     session_id: 'your-session-id',
+  #     session_private_key: 'your-private-key',
+  #     server_public_key: 'server-public-key'
+  #   )
+  #
+  #   api.me
+  #   api.assets
+  #
+  # == API Categories
+  #
+  # === Profile & Users
+  # - me, safe_me, update_me - Bot profile operations
+  # - read_user, read_users, search_user - User lookup
+  # - friends - List bot friends
+  #
+  # === Assets & Balance
+  # - assets, asset - Read asset information
+  # - ticker - Get asset ticker data
+  # - safe_assets - Read Safe API assets
+  #
+  # === Transfers & Payments
+  # - create_transfer, create_safe_transfer - Send payments
+  # - build_safe_transaction - Build raw transactions
+  # - sign_safe_transaction - Sign transactions
+  # - send_safe_transaction - Submit signed transactions
+  #
+  # === Messaging
+  # - start_blaze_connect - Connect to Blaze WebSocket
+  # - send_message - Send text/data messages
+  # - send_encrypted_messages - Send encrypted messages
+  #
+  # === Multisig & UTXOs
+  # - safe_outputs - Read unspent outputs
+  # - multisig_payments - Multisig payment operations
+  # - safe_ghost_keys - Generate ghost keys
+  #
+  # === NFT & Collectibles
+  # - create_collectible_request - Create NFT requests
+  # - read_collectibles - Read collectible tokens
+  # - inscriptions - Inscription operations
+  #
+  # == Examples
+  #
+  # Get bot information:
+  #
+  #   profile = MixinBot.api.me
+  #   puts profile['full_name']
+  #
+  # Read assets:
+  #
+  #   assets = MixinBot.api.assets
+  #   assets.each do |asset|
+  #     puts "#{asset['symbol']}: #{asset['balance']}"
+  #   end
+  #
+  # Send a transfer:
+  #
+  #   result = MixinBot.api.create_transfer(
+  #     members: ['recipient-user-id'],
+  #     threshold: 1,
+  #     asset_id: 'asset-uuid',
+  #     amount: '0.01',
+  #     memo: 'Payment for services',
+  #     trace_id: SecureRandom.uuid
+  #   )
+  #
   class API
-    attr_reader :config, :client
+    ##
+    # @return [MixinBot::Configuration] the configuration for this API instance
+    attr_reader :config
 
+    ##
+    # @return [MixinBot::Client] the HTTP client for making API requests
+    attr_reader :client
+
+    ##
+    # Initializes a new API instance.
+    #
+    # If no parameters are provided, uses the global MixinBot configuration.
+    # Otherwise, creates a new configuration with the provided parameters.
+    #
+    # @param kwargs [Hash] configuration options (see Configuration#initialize)
+    # @option kwargs [String] :app_id the application ID
+    # @option kwargs [String] :session_id the session ID
+    # @option kwargs [String] :session_private_key the session private key
+    # @option kwargs [String] :server_public_key the server public key
+    # @option kwargs [String] :spend_key the spend private key (for Safe API)
+    #
+    # @example Using global configuration
+    #   api = MixinBot::API.new
+    #
+    # @example With custom configuration
+    #   api = MixinBot::API.new(
+    #     app_id: 'your-app-id',
+    #     session_id: 'your-session-id',
+    #     session_private_key: 'your-private-key',
+    #     server_public_key: 'server-public-key'
+    #   )
+    #
     def initialize(**kwargs)
       @config =
         if kwargs.present?
@@ -47,14 +187,42 @@ module MixinBot
       @client = Client.new(@config)
     end
 
+    ##
+    # Provides access to utility methods.
+    #
+    # @return [Module] the Utils module
+    #
     def utils
       MixinBot::Utils
     end
 
+    ##
+    # Returns the client ID (same as app_id).
+    #
+    # @return [String] the client ID
+    #
     def client_id
       config.app_id
     end
 
+    ##
+    # Generates an access token for API authentication.
+    #
+    # Creates a JWT token signed with the bot's private key for authenticating
+    # API requests. The token includes request details and has a limited lifetime.
+    #
+    # @param method [String] the HTTP method (GET, POST, etc.)
+    # @param uri [String] the request URI path
+    # @param body [String] the request body
+    # @param kwargs [Hash] additional options
+    # @option kwargs [Integer] :exp_in (600) token expiration time in seconds
+    # @option kwargs [String] :scp ('FULL') token scope
+    #
+    # @return [String] the JWT access token
+    #
+    # @example
+    #   token = api.access_token('GET', '/me', '')
+    #
     def access_token(method, uri, body, **kwargs)
       utils.access_token(
         method,
@@ -67,20 +235,71 @@ module MixinBot
         private_key: config.session_private_key
       )
     end
+    alias sign_authentication_token access_token
+    alias sign_authentication_token_without_body access_token
+    alias sign_authentication_token_with_request_id access_token
 
+    ##
+    # Encodes a transaction hash to raw transaction format.
+    #
+    # @param txn [Hash] the transaction hash with keys: version, asset, inputs, outputs, extra
+    # @return [String] the hex-encoded raw transaction
+    #
+    # @example
+    #   raw = api.encode_raw_transaction(
+    #     version: 5,
+    #     asset: 'asset-id',
+    #     inputs: [...],
+    #     outputs: [...],
+    #     extra: 'memo'
+    #   )
+    #
     def encode_raw_transaction(txn)
       utils.encode_raw_transaction txn
     end
 
+    ##
+    # Decodes a raw transaction to a hash.
+    #
+    # @param raw [String] the hex-encoded raw transaction
+    # @return [Hash] the decoded transaction
+    #
+    # @example
+    #   txn = api.decode_raw_transaction(raw_hex)
+    #   puts txn['asset']
+    #   puts txn['inputs']
+    #
     def decode_raw_transaction(raw)
       utils.decode_raw_transaction raw
     end
 
+    ##
+    # Generates a trace ID from a transaction hash.
+    #
+    # Creates a deterministic UUID trace ID from a transaction hash,
+    # useful for tracking outputs from a transaction.
+    #
+    # @param hash [String] the transaction hash
+    # @param output_index [Integer] the output index (default: 0)
+    # @return [String] the generated trace UUID
+    #
+    # @example
+    #   trace_id = api.generate_trace_from_hash(tx_hash, 0)
+    #
     def generate_trace_from_hash(hash, output_index = 0)
       utils.generate_trace_from_hash hash, output_index
     end
 
-    # Use a mixin software to implement transaction build
+    ##
+    # Encodes a raw transaction using native mixin command-line tool.
+    #
+    # Requires the 'mixin' command to be installed and available in PATH.
+    # This is an alternative to the Ruby implementation.
+    #
+    # @param json [String] the transaction JSON
+    # @return [String] the encoded raw transaction
+    # @raise [RuntimeError] if mixin command is not available
+    #
     def encode_raw_transaction_native(json)
       ensure_mixin_command_exist
       command = format("mixin signrawtransaction --raw '%<arg>s'", arg: json)
@@ -91,7 +310,16 @@ module MixinBot
       output.chomp
     end
 
-    # Use a mixin software to implement transaction build
+    ##
+    # Decodes a raw transaction using native mixin command-line tool.
+    #
+    # Requires the 'mixin' command to be installed and available in PATH.
+    # This is an alternative to the Ruby implementation.
+    #
+    # @param raw [String] the hex-encoded raw transaction
+    # @return [Hash] the decoded transaction
+    # @raise [RuntimeError] if mixin command is not available
+    #
     def decode_raw_transaction_native(raw)
       ensure_mixin_command_exist
       command = format("mixin decoderawtransaction --raw '%<arg>s'", arg: raw)
@@ -108,10 +336,16 @@ module MixinBot
     include MixinBot::API::Attachment
     include MixinBot::API::Auth
     include MixinBot::API::Blaze
+    include MixinBot::API::Chain
+    include MixinBot::API::Code
+    include MixinBot::API::ComputerApi
     include MixinBot::API::Conversation
+    include MixinBot::API::Deposit
     include MixinBot::API::EncryptedMessage
+    include MixinBot::API::Fiat
     include MixinBot::API::Inscription
     include MixinBot::API::LegacyCollectible
+    include MixinBot::API::LegacyUser
     include MixinBot::API::LegacyMultisig
     include MixinBot::API::LegacyOutput
     include MixinBot::API::LegacyPayment
@@ -121,19 +355,30 @@ module MixinBot
     include MixinBot::API::Me
     include MixinBot::API::Message
     include MixinBot::API::Multisig
+    include MixinBot::API::Network
+    include MixinBot::API::NetworkAsset
     include MixinBot::API::Output
     include MixinBot::API::Payment
     include MixinBot::API::Pin
     include MixinBot::API::Rpc
+    include MixinBot::API::Session
     include MixinBot::API::Snapshot
     include MixinBot::API::Tip
+    include MixinBot::API::PinPayload
     include MixinBot::API::Transaction
     include MixinBot::API::Transfer
+    include MixinBot::API::Turn
     include MixinBot::API::User
     include MixinBot::API::Withdraw
 
     private
 
+    def warn_legacy_mixin_api!(api_label)
+      MixinBot.deprecator.warn(
+        "MixinBot legacy API #{api_label} is deprecated; migrate to the Safe API. See CHANGELOG for 2.0.0."
+      )
+    end
+
     def ensure_mixin_command_exist
       return if command?('mixin')
 

data/lib/mixin_bot/bot_auth.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module MixinBot
+  # Bot platform request signing (parity with Go BotAuthClient).
+  class BotAuth
+    class MapCache
+      def initialize
+        @store = {}
+      end
+
+      def get(key)
+        @store[key]
+      end
+
+      def put(key, value)
+        @store[key] = value
+      end
+
+      def delete(key)
+        @store.delete(key)
+      end
+    end
+
+    class Client
+      PLATFORM_PREFIX = 'up_'
+
+      def initialize(api, cache: MapCache.new)
+        @api = api
+        @cache = cache
+      end
+
+      def sign_request(timestamp, bot_user_id, method, uri, body = nil)
+        shared_key = shared_key_for(bot_user_id)
+        data = "#{timestamp}#{method}#{uri}"
+        data += body.to_s if body.present?
+        digest = OpenSSL::HMAC.digest('SHA256', shared_key, data)
+        Base64.urlsafe_encode64(@api.config.app_id.b + digest, padding: false)
+      end
+
+      private
+
+      def shared_key_for(user_id)
+        cached = @cache.get(user_id)
+        return cached if cached.present? && cached.bytesize >= 32
+
+        sessions = @api.fetch_user_sessions([user_id])['data']
+        session = Array(sessions).first
+        raise MixinBot::NotFoundError, "no session for #{user_id}" if session.nil?
+
+        u_pk = Base64.urlsafe_decode64(session['public_key'])
+        sk = @api.config.session_private_key_curve25519
+        shared = JOSE::JWA::X25519.x25519(sk, u_pk[0, 32])
+        @cache.put(user_id, shared)
+        @cache.put("#{PLATFORM_PREFIX}#{user_id}", session['platform'].to_s.b) if session['platform']
+        shared
+      end
+    end
+
+    def self.new_map_cache
+      MapCache.new
+    end
+
+    def self.new_client(api, cache: MapCache.new)
+      Client.new(api, cache:)
+    end
+
+    def self.new_default_client(api, cache: MapCache.new)
+      new_client(api, cache:)
+    end
+  end
+end