privy_ruby 0.0.2 → 0.2.0

data/lib/privy/public_api/services/wallets.rb

@@ -5,9 +5,13 @@ module Privy
     class Wallets < Privy::Resources::Wallets
       attr_reader :privy_client
 
+      # @return [Privy::Services::Earn]
+      attr_reader :earn
+
       def initialize(client:, privy_client:)
         super(client: client)
         @privy_client = privy_client
+        @earn = Privy::Services::Earn.new(client: client, privy_client: privy_client)
       end
 
       # Create a new wallet on the requested chain and for the requested owner.
@@ -39,6 +43,74 @@ module Privy
         super(combined_params)
       end
 
+      # Import an externally generated wallet by encrypting its entropy with HPKE.
+      #
+      # @param wallet [Hash] Import wallet parameters plus :private_key entropy.
+      # @option wallet [String] :private_key Private key or seed phrase entropy to import.
+      # @option wallet [String, Symbol] :entropy_type "hd" or "private-key".
+      # @option wallet [String, Symbol] :chain_type "ethereum" or "solana".
+      # @param request_options [Privy::RequestOptions, Hash, nil] Transport-level config (timeouts, retries).
+      #
+      # @return [Privy::Models::Wallet]
+      def import(
+        wallet:,
+        additional_signers: nil,
+        display_name: nil,
+        external_id: nil,
+        owner: nil,
+        owner_id: nil,
+        policy_ids: nil,
+        request_options: nil
+      )
+        import_wallet = wallet.transform_keys { |key| key.respond_to?(:to_sym) ? key.to_sym : key }
+        private_key = import_wallet.delete(:private_key)
+        raise Privy::Errors::Error, "wallet.private_key is required" if private_key.nil?
+        if import_wallet.key?(:hpke_config)
+          raise Privy::Errors::Error,
+                "wallet.hpke_config is not supported: encryption parameters are fixed by the SDK"
+        end
+
+        private_key_bytes = Privy::WalletEntropy.entropy_to_bytes(
+          entropy: private_key,
+          entropy_type: import_wallet.fetch(:entropy_type),
+          chain_type: import_wallet.fetch(:chain_type)
+        )
+
+        init_response = _init_import(
+          body: import_wallet.merge(encryption_type: "HPKE"),
+          request_options: request_options
+        )
+        unless init_response.encryption_type.to_s == "HPKE"
+          raise Privy::Errors::Error, "Invalid encryption type: #{init_response.encryption_type}"
+        end
+
+        encrypted = Privy::Cryptography::HpkeSender.new.encrypt(
+          Base64.strict_decode64(init_response.encryption_public_key),
+          private_key_bytes
+        )
+
+        submit_params = {
+          wallet: import_wallet.merge(
+            encryption_type: "HPKE",
+            encapsulated_key: Base64.strict_encode64(encrypted.encapsulated_key),
+            ciphertext: Base64.strict_encode64(encrypted.ciphertext)
+          ),
+          request_options: request_options
+        }
+        {
+          additional_signers: additional_signers,
+          display_name: display_name,
+          external_id: external_id,
+          owner: owner,
+          owner_id: owner_id,
+          policy_ids: policy_ids
+        }.each do |key, value|
+          submit_params[key] = value unless value.nil?
+        end
+
+        _submit_import(submit_params)
+      end
+
       # Update a wallet's policies or authorization key configuration.
       #
       # @example Update wallet policies
@@ -60,7 +132,13 @@ module Privy
       # @param request_options [Privy::RequestOptions, Hash, nil] Transport-level config (timeouts, retries).
       #
       # @return [Privy::Models::Wallet]
-      def update(wallet_id, wallet_update_params:, authorization_context: nil, request_expiry: nil, request_options: nil)
+      def update(
+        wallet_id,
+        wallet_update_params:,
+        authorization_context: nil,
+        request_expiry: nil,
+        request_options: nil
+      )
         prepared = Privy::Authorization.prepare_request(
           privy_client,
           method: :patch,
@@ -221,6 +299,80 @@ module Privy
         Privy::Authorization.merge_prepared_headers!(combined_params, prepared.headers)
         _transfer(wallet_id, combined_params)
       end
+
+      # Export a wallet's private key or seed phrase via HPKE.
+      #
+      # @param wallet_id [String] ID of the wallet to export.
+      # @param export_seed_phrase [Boolean, nil] Whether to export the seed phrase instead of the private key.
+      # @param authorization_context [Privy::Authorization::AuthorizationContext, nil] Authorization context for owned wallets.
+      # @param request_expiry [Integer, nil] Absolute Unix-ms timestamp at which the request expires.
+      # @param request_options [Privy::RequestOptions, Hash, nil] Transport-level config (timeouts, retries).
+      #
+      # @return [Hash] {private_key: String}
+      def export(
+        wallet_id,
+        export_seed_phrase: nil,
+        authorization_context: nil,
+        request_expiry: nil,
+        request_options: nil
+      )
+        recipient = Privy::Cryptography::HpkeRecipient.new
+        export_params = {
+          encryption_type: "HPKE",
+          recipient_public_key: Base64.strict_encode64(recipient.public_key_spki)
+        }
+        export_params[:export_seed_phrase] = export_seed_phrase unless export_seed_phrase.nil?
+
+        prepared = Privy::Authorization.prepare_request(
+          privy_client,
+          method: :post,
+          url: Privy::Authorization.signed_url(privy_client, "v1/wallets/#{wallet_id}/export"),
+          body: export_params,
+          authorization_context: authorization_context,
+          request_expiry: privy_client.compute_request_expiry(request_expiry)
+        )
+        combined_params = export_params.merge(request_options: request_options)
+        Privy::Authorization.merge_prepared_headers!(combined_params, prepared.headers)
+
+        response = super(wallet_id, combined_params)
+        unless response.encryption_type.to_s == "HPKE"
+          raise Privy::Errors::Error, "Invalid encryption type: #{response.encryption_type}"
+        end
+
+        private_key = recipient.decrypt(
+          Base64.strict_decode64(response.encapsulated_key),
+          Base64.strict_decode64(response.ciphertext)
+        )
+
+        {private_key: private_key.force_encoding(Encoding::UTF_8)}
+      end
+
+      # Export a wallet's private key via HPKE.
+      #
+      # @return [Hash] {private_key: String}
+      def export_private_key(wallet_id, authorization_context: nil, request_expiry: nil, request_options: nil)
+        export(
+          wallet_id,
+          export_seed_phrase: false,
+          authorization_context: authorization_context,
+          request_expiry: request_expiry,
+          request_options: request_options
+        )
+      end
+
+      # Export a wallet's seed phrase via HPKE.
+      #
+      # @return [Hash] {seed_phrase: String}
+      def export_seed_phrase(wallet_id, authorization_context: nil, request_expiry: nil, request_options: nil)
+        exported = export(
+          wallet_id,
+          export_seed_phrase: true,
+          authorization_context: authorization_context,
+          request_expiry: request_expiry,
+          request_options: request_options
+        )
+        {seed_phrase: exported.fetch(:private_key)}
+      end
     end
   end
 end

data/lib/privy/resources/intents.rb

@@ -2,6 +2,7 @@
 
 module Privy
   module Resources
+    # Operations related to authorization intents for wallet actions
     class Intents
       # List intents for an app. Returns a paginated list of intents with their current
       # status and details.
@@ -66,7 +67,7 @@ module Privy
       #
       # @param request_options [Privy::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Privy::Models::RuleIntentResponse]
+      # @return [Privy::Models::RuleMutateIntentResponse]
       #
       # @see Privy::Models::IntentCreatePolicyRuleParams
       def create_policy_rule(policy_id, params)
@@ -77,7 +78,7 @@ module Privy
           path: ["v1/intents/policies/%1$s/rules", policy_id],
           headers: parsed.slice(*header_params.keys).transform_keys(header_params),
           body: parsed.except(*header_params.keys),
-          model: Privy::RuleIntentResponse,
+          model: Privy::RuleMutateIntentResponse,
           options: options
         )
       end
@@ -98,7 +99,7 @@ module Privy
       #
       # @param request_options [Privy::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Privy::Models::RuleIntentResponse]
+      # @return [Privy::Models::RuleDeleteIntentResponse]
       #
       # @see Privy::Models::IntentDeletePolicyRuleParams
       def delete_policy_rule(rule_id, params)
@@ -111,7 +112,7 @@ module Privy
           method: :delete,
           path: ["v1/intents/policies/%1$s/rules/%2$s", policy_id, rule_id],
           headers: parsed.transform_keys(privy_request_expiry: "privy-request-expiry"),
-          model: Privy::RuleIntentResponse,
+          model: Privy::RuleDeleteIntentResponse,
           options: options
         )
       end
@@ -186,7 +187,7 @@ module Privy
       #
       # @param fee_configuration [Privy::Models::FeeConfiguration] Body param: Total fees assessed on a transfer, in BPS
       #
-      # @param slippage_bps [Integer] Body param: Maximum allowed slippage in basis points (1 bps = 0.01%).
+      # @param slippage_bps [Integer] Body param: Maximum allowed slippage in basis points (1 bps = 0.01%). Only appli
       #
       # @param privy_request_expiry [String] Header param: Request expiry. Value is a Unix timestamp in milliseconds represen
       #
@@ -310,7 +311,7 @@ module Privy
       #
       # @param request_options [Privy::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Privy::Models::RuleIntentResponse]
+      # @return [Privy::Models::RuleMutateIntentResponse]
       #
       # @see Privy::Models::IntentUpdatePolicyRuleParams
       def update_policy_rule(rule_id, params)
@@ -325,7 +326,7 @@ module Privy
           path: ["v1/intents/policies/%1$s/rules/%2$s", policy_id, rule_id],
           headers: parsed.slice(*header_params.keys).transform_keys(header_params),
           body: parsed.except(*header_params.keys),
-          model: Privy::RuleIntentResponse,
+          model: Privy::RuleMutateIntentResponse,
           options: options
         )
       end

data/lib/privy/resources/oauth.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Privy
+  module Resources
+    class OAuth
+      # @api private
+      #
+      # @param client [Privy::Client]
+      def initialize(client:)
+        @client = client
+      end
+    end
+  end
+end

data/lib/privy/resources/onramps.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Privy
+  module Resources
+    class Onramps
+      # @api private
+      #
+      # @param client [Privy::Client]
+      def initialize(client:)
+        @client = client
+      end
+    end
+  end
+end

data/lib/privy/resources/wallets/swap.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Privy
+  module Resources
+    class Wallets
+      # Operations for swapping tokens within wallets
+      class Swap
+        # Some parameter documentations has been truncated, see
+        # {Privy::Models::Wallets::SwapExecuteParams} for more details.
+        #
+        # Execute a token swap within a wallet.
+        #
+        # @overload execute(wallet_id, base_amount:, destination:, source:, amount_type: nil, fee_configuration: nil, slippage_bps: nil, privy_authorization_signature: nil, privy_idempotency_key: nil, request_options: {})
+        #
+        # @param wallet_id [String] Path param: ID of the wallet.
+        #
+        # @param base_amount [String] Body param: Amount in base units (e.g., wei for ETH). Must be a non-negative int
+        #
+        # @param destination [Privy::Models::SwapDestination] Body param: The output side of a swap execution request.
+        #
+        # @param source [Privy::Models::SwapSource] Body param: The input side of a swap request, including token and chain.
+        #
+        # @param amount_type [Symbol, Privy::Models::AmountType] Body param: Whether the amount refers to the input token or output token.
+        #
+        # @param fee_configuration [Privy::Models::FeeConfiguration] Body param: Total fees assessed on a transfer, in BPS
+        #
+        # @param slippage_bps [Integer] Body param: Maximum slippage tolerance in basis points (e.g., 50 for 0.5%).
+        #
+        # @param privy_authorization_signature [String] Header param: Request authorization signature. If multiple signatures are requir
+        #
+        # @param privy_idempotency_key [String] Header param: Idempotency keys ensure API requests are executed only once within
+        #
+        # @param request_options [Privy::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Privy::Models::SwapActionResponse]
+        #
+        # @see Privy::Models::Wallets::SwapExecuteParams
+        def execute(wallet_id, params)
+          parsed, options = Privy::Wallets::SwapExecuteParams.dump_request(params)
+          header_params =
+            {
+              privy_authorization_signature: "privy-authorization-signature",
+              privy_idempotency_key: "privy-idempotency-key"
+            }
+          @client.request(
+            method: :post,
+            path: ["v1/wallets/%1$s/swap", wallet_id],
+            headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+            body: parsed.except(*header_params.keys),
+            model: Privy::SwapActionResponse,
+            options: options
+          )
+        end
+
+        # Some parameter documentations has been truncated, see
+        # {Privy::Models::Wallets::SwapQuoteParams} for more details.
+        #
+        # Get a price quote for swapping tokens within a wallet.
+        #
+        # @overload quote(wallet_id, base_amount:, destination:, source:, amount_type: nil, fee_configuration: nil, slippage_bps: nil, privy_authorization_signature: nil, request_options: {})
+        #
+        # @param wallet_id [String] Path param: ID of the wallet.
+        #
+        # @param base_amount [String] Body param: Amount in base units (e.g., wei for ETH). Must be a non-negative int
+        #
+        # @param destination [Privy::Models::SwapQuoteDestination] Body param: The output side of a swap quote request.
+        #
+        # @param source [Privy::Models::SwapSource] Body param: The input side of a swap request, including token and chain.
+        #
+        # @param amount_type [Symbol, Privy::Models::AmountType] Body param: Whether the amount refers to the input token or output token.
+        #
+        # @param fee_configuration [Privy::Models::FeeConfiguration] Body param: Total fees assessed on a transfer, in BPS
+        #
+        # @param slippage_bps [Integer] Body param: Maximum slippage tolerance in basis points (e.g., 50 for 0.5%). If o
+        #
+        # @param privy_authorization_signature [String] Header param: Request authorization signature. If multiple signatures are requir
+        #
+        # @param request_options [Privy::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Privy::Models::SwapQuoteResponse]
+        #
+        # @see Privy::Models::Wallets::SwapQuoteParams
+        def quote(wallet_id, params)
+          parsed, options = Privy::Wallets::SwapQuoteParams.dump_request(params)
+          header_params = {privy_authorization_signature: "privy-authorization-signature"}
+          @client.request(
+            method: :post,
+            path: ["v1/wallets/%1$s/swap/quote", wallet_id],
+            headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+            body: parsed.except(*header_params.keys),
+            model: Privy::SwapQuoteResponse,
+            options: options
+          )
+        end
+
+        # @api private
+        #
+        # @param client [Privy::Client]
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end

data/lib/privy/resources/wallets.rb

@@ -14,6 +14,10 @@ module Privy
       # @return [Privy::Resources::Wallets::Balance]
       attr_reader :balance
 
+      # Operations for swapping tokens within wallets
+      # @return [Privy::Resources::Wallets::Swap]
+      attr_reader :swap
+
       # Some parameter documentations has been truncated, see
       # {Privy::Models::WalletCreateParams} for more details.
       #
@@ -213,7 +217,7 @@ module Privy
       #
       # @param fee_configuration [Privy::Models::FeeConfiguration] Body param: Total fees assessed on a transfer, in BPS
       #
-      # @param slippage_bps [Integer] Body param: Maximum allowed slippage in basis points (1 bps = 0.01%).
+      # @param slippage_bps [Integer] Body param: Maximum allowed slippage in basis points (1 bps = 0.01%). Only appli
       #
       # @param privy_authorization_signature [String] Header param: Request authorization signature. If multiple signatures are requir
       #
@@ -247,7 +251,8 @@ module Privy
       # Some parameter documentations has been truncated, see
       # {Privy::Models::WalletAuthenticateWithJwtParams} for more details.
       #
-      # Obtain a session key to enable wallet access.
+      # Exchange a user JWT for a session key authorized to act on the user's wallets.
+      # Returns the encrypted authorization key and the list of wallets it can access.
       #
       # @overload authenticate_with_jwt(encryption_type:, recipient_public_key:, user_jwt:, request_options: {})
       #
@@ -273,9 +278,35 @@ module Privy
         )
       end
 
+      # Creates multiple wallets in a single request. Each wallet creation is
+      # independent; failures for one wallet do not affect others. Maximum batch size is
+      # 100 wallets.
+      #
+      # @overload create_batch(wallets:, request_options: {})
+      #
+      # @param wallets [Array<Privy::Models::WalletBatchItemInput>] Array of wallet creation requests. Minimum 1, maximum 100.
+      #
+      # @param request_options [Privy::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Privy::Models::WalletBatchCreateResponse]
+      #
+      # @see Privy::Models::WalletCreateBatchParams
+      def create_batch(params)
+        parsed, options = Privy::WalletCreateBatchParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: "v1/wallets/batch",
+          body: parsed,
+          model: Privy::WalletBatchCreateResponse,
+          options: options
+        )
+      end
+
       # @deprecated
       #
-      # Create wallets with an associated recovery user.
+      # Create one or more wallets associated with a recovery user, so the user can
+      # later regain wallet access via the linked accounts. Deprecated; prefer the
+      # standard wallet creation flow combined with a separate recovery setup.
       #
       # @overload create_wallets_with_recovery(primary_signer:, recovery_user:, wallets:, request_options: {})
       #
@@ -467,6 +498,7 @@ module Privy
         @earn = Privy::Resources::Wallets::Earn.new(client: client)
         @transactions = Privy::Resources::Wallets::Transactions.new(client: client)
         @balance = Privy::Resources::Wallets::Balance.new(client: client)
+        @swap = Privy::Resources::Wallets::Swap.new(client: client)
       end
     end
   end

data/lib/privy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Privy
-  VERSION = "0.0.2"
+  VERSION = "0.2.0"
 end

data/lib/privy/wallet_entropy.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "base58"
+
+module Privy
+  module WalletEntropy
+    SECP256K1_ORDER = 0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141
+
+    module_function
+
+    def entropy_to_bytes(entropy:, entropy_type:, chain_type:)
+      case entropy_type.to_s
+      when "hd"
+        entropy.to_s.encode(Encoding::UTF_8).b
+      when "private-key"
+        private_key_to_bytes(entropy.to_s, chain_type.to_s)
+      else
+        raise Privy::Errors::Error, "Invalid entropy type: #{entropy_type}"
+      end
+    end
+
+    def private_key_to_bytes(entropy, chain_type)
+      case chain_type
+      when "ethereum"
+        ethereum_private_key_to_bytes(entropy)
+      when "solana"
+        solana_private_key_to_bytes(entropy)
+      else
+        raise Privy::Errors::Error, "Invalid chain type for imports: #{chain_type}"
+      end
+    end
+
+    def ethereum_private_key_to_bytes(entropy)
+      hex = entropy.start_with?("0x") ? entropy[2..] : entropy
+      unless hex.match?(/\A[0-9a-fA-F]{64}\z/)
+        raise Privy::Errors::Error,
+              "Invalid private key: Ethereum entropy must be 64 hex characters (32 bytes)"
+      end
+
+      scalar = hex.to_i(16)
+      if scalar.zero? || scalar >= SECP256K1_ORDER
+        raise Privy::Errors::Error,
+              "Invalid private key: Ethereum entropy must be in range [1, secp256k1 order)"
+      end
+
+      [hex].pack("H*")
+    end
+
+    def solana_private_key_to_bytes(entropy)
+      if entropy.empty?
+        raise Privy::Errors::Error,
+              "Invalid private key: Solana entropy must be base58 encoded"
+      end
+
+      Privy::Base58.decode(entropy)
+    rescue ArgumentError
+      raise Privy::Errors::Error, "Invalid private key: Solana entropy must be base58 encoded"
+    end
+  end
+end