mpp-rb 0.1.3 → 0.1.5

data/lib/mpp/methods/tempo/relay.rb

@@ -0,0 +1,257 @@
+# typed: false
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require "net/http"
+require "time"
+require "uri"
+require_relative "../../http/headers"
+require_relative "attribution"
+
+module Mpp
+  module Methods
+    module Tempo
+      # HTTP client for a Tempo API-compatible MPP relay.
+      #
+      # `resolve` accepts:
+      #   * a URL string (unauthenticated relay)
+      #   * a config hash (`url:` plus optional `headers:`, or mppx-style
+      #     `api_base_url:` / `api_key:`)
+      #   * any object that responds to `#validate` and `#broadcast`
+      class Relay
+        DEFAULT_API_BASE_URL = "https://api.tempo.xyz"
+        VALIDATE_PATH = "/v1/mpp/validate"
+        BROADCAST_PATH = "/v1/mpp/broadcast"
+        DEFAULT_TIMEOUT = Rpc::DEFAULT_TIMEOUT
+
+        ERROR_CODES = %w[
+          already_used
+          broadcast_failed
+          expired
+          invalid_payment
+          insufficient_funds
+          policy_denied
+          screen_rejected
+          simulation_failed
+          temporarily_unavailable
+          unsupported
+          unknown
+        ].freeze
+
+        attr_reader :base_url
+
+        def initialize(url, headers: nil)
+          @base_url = Mpp::Http::Headers.normalize_base_url(url)
+          raise ArgumentError, "relay url is required" if @base_url.empty?
+
+          @headers = headers
+        end
+
+        def self.resolve_optional(relay)
+          return if relay.nil? || relay == false
+
+          resolve(relay)
+        end
+
+        def self.resolve(relay)
+          return relay if relay.is_a?(Relay)
+          return new(relay) if relay.is_a?(String) && !relay.empty?
+          return from_config(relay) if relay.is_a?(Hash)
+          return relay if duck_type?(relay)
+
+          raise ArgumentError, "relay must be a URL, {url:, headers:}, or an object that implements #validate and #broadcast"
+        end
+
+        def self.from_config(config)
+          cfg = Mpp::Http::Headers.symbolize(config)
+          url = cfg[:url] || cfg[:api_base_url] || cfg[:apiBaseUrl] || cfg[:base_url] || cfg[:baseUrl]
+          url = DEFAULT_API_BASE_URL if url.nil? || url.to_s.empty?
+          headers = merge_api_key_headers(cfg[:headers], cfg[:api_key] || cfg[:apiKey])
+          new(url.to_s, headers: headers)
+        end
+
+        def self.duck_type?(relay)
+          !relay.nil? && relay.respond_to?(:validate) && relay.respond_to?(:broadcast)
+        end
+
+        def self.merge_api_key_headers(headers, api_key)
+          return headers if api_key.nil? || api_key.to_s.empty?
+
+          defaults = {"tempo-api-key" => api_key.to_s}
+          return defaults if headers.nil?
+
+          if headers.respond_to?(:call)
+            original = headers
+            ->(path) {
+              extra = (original.arity == 0) ? original.call : original.call(path)
+              extra = {} unless extra.is_a?(Hash)
+              defaults.merge(Mpp::Http::Headers.stringify(extra))
+            }
+          elsif headers.is_a?(Hash)
+            defaults.merge(Mpp::Http::Headers.stringify(headers))
+          else
+            defaults
+          end
+        end
+        private_class_method :merge_api_key_headers
+
+        def verify(credential, _request = nil)
+          input = to_relay_input(credential)
+          validate(input)
+          broadcast(input)
+        end
+
+        def validate(input)
+          response = post(VALIDATE_PATH, input)
+          raise failure(response) unless success?(response)
+
+          true
+        end
+
+        def broadcast(input)
+          response = post(BROADCAST_PATH, input, extra_headers: {
+            "Idempotency-Key" => idempotency_key(input)
+          })
+          raise failure(response) unless broadcast_success?(response)
+
+          to_receipt(response.fetch("receipt"))
+        end
+
+        private
+
+        def post(path, input, extra_headers: {})
+          uri = URI.parse("#{@base_url}#{path}")
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = uri.scheme == "https"
+          http.read_timeout = DEFAULT_TIMEOUT
+
+          request = Net::HTTP::Post.new(uri)
+          request["Accept"] = "application/json"
+          request["Content-Type"] = "application/json"
+          Mpp::Http::Headers.resolve(@headers, path).each { |key, value| request[key] = value }
+          extra_headers.each { |key, value| request[key] = value }
+          request.body = JSON.generate(input)
+
+          response = http.request(request)
+          unless response.is_a?(Net::HTTPSuccess)
+            raise Mpp::VerificationFailedError.new(reason: "relay #{path} returned HTTP #{response.code}")
+          end
+
+          body = response.body.to_s
+          if body.empty?
+            raise Mpp::VerificationFailedError.new(reason: "relay #{path} returned an empty body")
+          end
+
+          parsed = JSON.parse(body)
+          unless parsed.is_a?(Hash)
+            raise Mpp::VerificationFailedError.new(reason: "relay #{path} returned JSON that is not an object")
+          end
+
+          parsed
+        rescue JSON::ParserError
+          raise Mpp::VerificationFailedError.new(reason: "relay #{path} returned invalid JSON")
+        rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::ETIMEDOUT, Net::OpenTimeout, Net::ReadTimeout, SocketError => e
+          raise Mpp::VerificationFailedError.new(reason: "relay request failed: #{e.message}")
+        end
+
+        def to_relay_input(credential)
+          echo = credential.challenge
+          challenge = {
+            "id" => echo.id,
+            "realm" => echo.realm,
+            "method" => echo.method,
+            "intent" => echo.intent,
+            "request" => decode_request(echo.request)
+          }
+          challenge["expires"] = echo.expires if echo.expires
+          challenge["digest"] = echo.digest if echo.digest
+          challenge["opaque"] = echo.opaque if echo.opaque
+
+          input = {
+            "challenge" => challenge,
+            "payload" => credential.payload
+          }
+          input["source"] = credential.source if credential.source
+          input
+        end
+
+        def decode_request(request)
+          return request if request.is_a?(Hash)
+          return request unless request.is_a?(String) && !request.empty?
+
+          Mpp::Parsing.b64_decode(request)
+        rescue Mpp::ParseError
+          request
+        end
+
+        def idempotency_key(input)
+          payload = input["payload"]
+          if payload.is_a?(Hash) && payload["type"] == "transaction" && payload["signature"].is_a?(String)
+            hex = payload["signature"].delete_prefix("0x")
+            if hex.match?(/\A[0-9a-fA-F]+\z/) && hex.length.even?
+              hash = Attribution.keccak256([hex].pack("H*"))
+              return "mpp_0x#{hash.unpack1("H*")}"
+            end
+          end
+
+          digest = Digest::SHA256.hexdigest(Mpp::Json.compact_encode(input))
+          "mpp_0x#{digest}"
+        end
+
+        def success?(response)
+          response.is_a?(Hash) && response["success"] == true
+        end
+
+        def broadcast_success?(response)
+          success?(response) && relay_receipt?(response["receipt"])
+        end
+
+        def relay_receipt?(value)
+          value.is_a?(Hash) &&
+            value["method"].is_a?(String) &&
+            value["reference"].is_a?(String) &&
+            value["timestamp"].is_a?(String) &&
+            (value["externalId"].nil? || value["externalId"].is_a?(String))
+        end
+
+        def to_receipt(receipt)
+          timestamp = begin
+            Time.iso8601(receipt["timestamp"].to_s.gsub("Z", "+00:00"))
+          rescue ArgumentError
+            raise failure
+          end
+
+          Mpp::Receipt.success(
+            receipt["reference"],
+            timestamp: timestamp,
+            method: receipt["method"],
+            external_id: receipt["externalId"]
+          )
+        end
+
+        def failure(response = nil)
+          code = relay_error_code(response)
+          return Mpp::PaymentExpiredError.new if code == "expired"
+
+          reason = case code
+          when "already_used", "broadcast_failed", "insufficient_funds", "invalid_payment",
+            "simulation_failed", "unsupported", "temporarily_unavailable"
+            code.tr("_", " ")
+          end
+          Mpp::VerificationFailedError.new(reason: reason)
+        end
+
+        def relay_error_code(value)
+          return unless value.is_a?(Hash)
+
+          error = value["error"]
+          return unless error.is_a?(Hash)
+
+          code = error["code"]
+          code if ERROR_CODES.include?(code)
+        end
+      end
+    end
+  end
+end

data/lib/mpp/methods/tempo.rb

@@ -11,6 +11,8 @@ module Mpp
       autoload :Rpc, "mpp/methods/tempo/rpc"
       autoload :Transaction, "mpp/methods/tempo/transaction"
       autoload :FeePayerPolicy, "mpp/methods/tempo/fee_payer_policy"
+      autoload :FeePayerClient, "mpp/methods/tempo/fee_payer_client"
+      autoload :Relay, "mpp/methods/tempo/relay"
       autoload :Schemas, "mpp/methods/tempo/schemas"
       # Eagerly require client_method so the Tempo.tempo factory method is available
       require_relative "tempo/client_method"

data/lib/mpp/parsing.rb

@@ -235,6 +235,7 @@ module Mpp
         reference: data["reference"].to_s,
         method: method,
         external_id: data["externalId"]&.to_s,
+        subscription_id: data["subscriptionId"]&.to_s,
         extra: extra
       )
     end
@@ -256,6 +257,7 @@ module Mpp
         "timestamp" => timestamp_str
       }
       payload["externalId"] = receipt.external_id if receipt.external_id
+      payload["subscriptionId"] = receipt.subscription_id if receipt.subscription_id
       payload["extra"] = receipt.extra if receipt.extra
 
       b64_encode(payload)

data/lib/mpp/receipt.rb

@@ -2,8 +2,8 @@
 # frozen_string_literal: true
 
 module Mpp
-  Receipt = Data.define(:status, :timestamp, :reference, :method, :external_id, :extra) do
-    def initialize(status:, timestamp:, reference:, method: "", external_id: nil, extra: nil)
+  Receipt = Data.define(:status, :timestamp, :reference, :method, :external_id, :extra, :subscription_id) do
+    def initialize(status:, timestamp:, reference:, method: "", external_id: nil, extra: nil, subscription_id: nil)
       super
     end
 
@@ -18,13 +18,14 @@ module Mpp
     end
 
     # Create a success receipt with current timestamp.
-    def self.success(reference, timestamp: nil, method: "tempo", external_id: nil, extra: nil)
+    def self.success(reference, timestamp: nil, method: "tempo", external_id: nil, extra: nil, subscription_id: nil)
       new(
         status: "success",
         timestamp: timestamp || Time.now.utc,
         reference: reference,
         method: method,
         external_id: external_id,
+        subscription_id: subscription_id,
         extra: extra
       )
     end

data/lib/mpp/server/accept_payment.rb

@@ -0,0 +1,194 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Mpp
+  module Server
+    # Parse, format, and rank the Accept-Payment client-preference header.
+    #
+    # Syntax mirrors HTTP content negotiation: `method/intent[;q=value]`,
+    # comma-separated. Wildcards (`*` / `tempo/*` / `*/charge`) are allowed.
+    # Entries with q=0 are excluded. If the header is empty, invalid, or
+    # filters out every offer, the original offer list is returned.
+    module AcceptPayment
+      extend T::Sig
+
+      TOKEN_RE = /\A(?:\*|[a-z0-9-]+)\z/
+      ENTRY_RE = %r{\A(?<method>[^/;\s]+|\*)\s*/\s*(?<intent>[^/;\s]+|\*)(?<params>(?:\s*;\s*.+)?)\z}
+      PARAM_RE = /\A(?<name>[A-Za-z0-9_-]+)\s*=\s*(?<value>\S+)\z/
+      QVALUE_RE = /\A(?:0(?:\.\d{0,3})?|1(?:\.0{0,3})?)\z/
+
+      Entry = T.type_alias { T::Hash[Symbol, T.untyped] }
+
+      module_function
+
+      # Parse an Accept-Payment header. Raises ArgumentError on malformed input.
+      sig { params(header: String).returns(T::Array[Entry]) }
+      def parse(header)
+        parts = header.split(",").map(&:strip).reject(&:empty?)
+        Kernel.raise ArgumentError, "Accept-Payment header is empty." if parts.empty?
+
+        parts.each_with_index.map { |part, index| parse_entry(part, index) }
+      end
+
+      # Filter and reorder offers by Accept-Payment. Returns `offers` unchanged
+      # when the header is missing, malformed, or matches nothing.
+      sig { params(offers: T::Array[T.untyped], header: T.nilable(String)).returns(T::Array[T.untyped]) }
+      def apply(offers, header)
+        return offers if header.nil? || header.strip.empty?
+
+        begin
+          preferences = parse(header)
+        rescue ArgumentError
+          return offers
+        end
+
+        ranked = rank(offers, preferences)
+        ranked.empty? ? offers : ranked
+      end
+
+      # Order offers by the best matching client preference.
+      # More specific matches win before comparing q-values.
+      sig { params(offers: T::Array[T.untyped], preferences: T::Array[Entry]).returns(T::Array[T.untyped]) }
+      def rank(offers, preferences)
+        scored = []
+        offers.each_with_index do |offer, index|
+          match = best_match(offer, preferences)
+          next unless match && T.unsafe(match[:q]) > 0
+
+          scored << {match: match, offer: offer, index: index}
+        end
+
+        scored.sort_by! { |row| [-T.unsafe(row[:match][:q]), T.unsafe(row[:index])] }
+        scored.map { |row| row[:offer] }
+      end
+
+      sig { params(value: T.untyped).returns(String) }
+      def key_of(value)
+        method, intent = method_intent(value)
+        Kernel.raise ArgumentError, "Missing payment method name." if method.empty?
+
+        "#{method}/#{intent}"
+      end
+
+      sig { params(part: String, index: Integer).returns(Entry) }
+      def parse_entry(part, index)
+        match = ENTRY_RE.match(part)
+        Kernel.raise ArgumentError, "Invalid Accept-Payment entry: #{part}" unless match
+
+        method = T.must(match[:method])
+        intent = T.must(match[:intent])
+        assert_token!(method, "method")
+        assert_token!(intent, "intent")
+
+        q = 1.0
+        split_parameters(match[:params]).each do |param|
+          next if param.empty?
+
+          parameter_match = PARAM_RE.match(param)
+          Kernel.raise ArgumentError, "Invalid Accept-Payment parameter: #{param}" unless parameter_match
+
+          next unless parameter_match[:name] == "q"
+
+          q = parse_header_q(T.must(parameter_match[:value]), %(Accept-Payment entry "#{part}"))
+        end
+
+        {method: method, intent: intent, q: q, index: index}
+      end
+      private_class_method :parse_entry
+
+      sig { params(offer: T.untyped, preferences: T::Array[Entry]).returns(T.nilable(Entry)) }
+      def best_match(offer, preferences)
+        method, intent = method_intent(offer)
+        best = T.let(nil, T.nilable(Entry))
+
+        preferences.each do |preference|
+          next unless matches?(method, intent, preference)
+
+          candidate = preference.merge(specificity: specificity(preference))
+          if better_match?(candidate, best)
+            best = candidate
+          end
+        end
+
+        best
+      end
+      private_class_method :best_match
+
+      sig { params(candidate: Entry, best: T.nilable(Entry)).returns(T::Boolean) }
+      def better_match?(candidate, best)
+        return true if best.nil?
+        return true if T.unsafe(candidate[:specificity]) > T.unsafe(best[:specificity])
+        return true if T.unsafe(candidate[:specificity]) == T.unsafe(best[:specificity]) &&
+          T.unsafe(candidate[:q]) > T.unsafe(best[:q])
+        return true if T.unsafe(candidate[:specificity]) == T.unsafe(best[:specificity]) &&
+          T.unsafe(candidate[:q]) == T.unsafe(best[:q]) &&
+          T.unsafe(candidate[:index]) < T.unsafe(best[:index])
+
+        false
+      end
+      private_class_method :better_match?
+
+      sig { params(method: String, intent: String, preference: Entry).returns(T::Boolean) }
+      def matches?(method, intent, preference)
+        (preference[:method] == "*" || preference[:method] == method) &&
+          (preference[:intent] == "*" || preference[:intent] == intent)
+      end
+      private_class_method :matches?
+
+      sig { params(preference: Entry).returns(Integer) }
+      def specificity(preference)
+        ((preference[:method] == "*") ? 0 : 1) + ((preference[:intent] == "*") ? 0 : 1)
+      end
+      private_class_method :specificity
+
+      sig { params(offer: T.untyped).returns([String, String]) }
+      def method_intent(offer)
+        if offer.is_a?(Hash)
+          [(offer[:method] || offer["method"]).to_s, (offer[:intent] || offer["intent"]).to_s]
+        else
+          [offer.method.to_s, offer.intent.to_s]
+        end
+      end
+      private_class_method :method_intent
+
+      sig { params(value: T.nilable(String)).returns(T::Array[String]) }
+      def split_parameters(value)
+        return [] if value.nil? || value.empty?
+
+        value.split(";").map(&:strip).reject(&:empty?)
+      end
+      private_class_method :split_parameters
+
+      sig { params(value: String, context: String).returns(Float) }
+      def parse_header_q(value, context)
+        unless QVALUE_RE.match?(value)
+          Kernel.raise ArgumentError, "Invalid q-value for #{context}. Expected an HTTP qvalue."
+        end
+
+        assert_q(Kernel.Float(value), context)
+      end
+      private_class_method :parse_header_q
+
+      sig { params(value: Float, context: String).returns(Float) }
+      def assert_q(value, context)
+        Kernel.raise ArgumentError, "Invalid q-value for #{context}. Expected a value between 0 and 1." if value.negative? || value > 1
+
+        rounded = (value * 1000).round
+        if (value * 1000 - rounded).abs > 1e-9
+          Kernel.raise ArgumentError, "Invalid q-value for #{context}. Expected at most 3 decimal places."
+        end
+
+        rounded / 1000.0
+      end
+      private_class_method :assert_q
+
+      sig { params(value: String, label: String).void }
+      def assert_token!(value, label)
+        return if TOKEN_RE.match?(value)
+
+        Kernel.raise ArgumentError, "Invalid Accept-Payment #{label}: #{value}"
+      end
+      private_class_method :assert_token!
+    end
+  end
+end