mpp-rb 0.1.5 → 0.1.7

data/lib/mpp/server/mpp_handler.rb

@@ -10,7 +10,7 @@ module Mpp
     class MppHandler
       extend T::Sig
 
-      REQUEST_OPTION_KEYS = [:body, :url, :payment_signature, :accept_payment, :http_method].freeze
+      REQUEST_OPTION_KEYS = [:body, :url, :payment_signature, :accept_payment, :http_method, :payment_authorization].freeze
 
       sig { returns(T.untyped) }
       attr_reader :method
@@ -27,6 +27,12 @@ module Mpp
       sig { returns(T::Hash[String, T.untyped]) }
       attr_reader :defaults
 
+      sig { returns(T::Boolean) }
+      attr_reader :requires_auth
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :credential_header
+
       sig do
         params(
           realm: String,
@@ -34,16 +40,21 @@ module Mpp
           method: T.untyped,
           methods: T.nilable(T::Array[T.untyped]),
           defaults: T.nilable(T::Hash[String, T.untyped]),
-          events: T.nilable(Mpp::Events::Dispatcher)
+          events: T.nilable(Mpp::Events::Dispatcher),
+          requires_auth: T::Boolean
         ).void
       end
-      def initialize(realm:, secret_key:, method: nil, methods: nil, defaults: nil, events: nil)
+      def initialize(realm:, secret_key:, method: nil, methods: nil, defaults: nil, events: nil, requires_auth: false)
         @methods = T.let(normalize_methods(method, methods), T::Array[T.untyped])
         @method = T.let(@methods.first, T.untyped)
         @realm = T.let(realm, String)
         @secret_key = T.let(secret_key, String)
         @defaults = T.let(defaults || {}, T::Hash[String, T.untyped])
         @events = T.let(events || Mpp::Events.server_dispatcher, Mpp::Events::Dispatcher)
+        @method_hook_events = T.let(Mpp::Events.server_dispatcher, Mpp::Events::Dispatcher)
+        @requires_auth = T.let(requires_auth, T::Boolean)
+        @credential_header = T.let(requires_auth ? Mpp::PAYMENT_AUTHORIZATION_HEADER : nil, T.nilable(String))
+        register_method_payment_success
       end
 
       # Create with auto-detected realm and secret_key.
@@ -53,16 +64,18 @@ module Mpp
           methods: T.nilable(T::Array[T.untyped]),
           realm: T.untyped,
           secret_key: T.untyped,
-          events: T.nilable(Mpp::Events::Dispatcher)
+          events: T.nilable(Mpp::Events::Dispatcher),
+          requires_auth: T::Boolean
         ).returns(T.attached_class)
       end
-      def self.create(method: nil, methods: nil, realm: nil, secret_key: nil, events: nil)
+      def self.create(method: nil, methods: nil, realm: nil, secret_key: nil, events: nil, requires_auth: false)
         new(
           method: method,
           methods: methods,
           realm: realm || Defaults.detect_realm,
           secret_key: secret_key || Defaults.detect_secret_key,
-          events: events
+          events: events,
+          requires_auth: requires_auth
         )
       end
 
@@ -86,6 +99,14 @@ module Mpp
         on(Mpp::Events::PAYMENT_SUCCESS, handler, &block)
       end
 
+      # Select the HTTP header value that carries the Payment credential.
+      # When requires_auth is true, Payment credentials ride in
+      # Payment-Authorization so Authorization can hold application auth.
+      sig { params(authorization: T.nilable(String), payment_authorization: T.nilable(String)).returns(T.nilable(String)) }
+      def payment_credential_value(authorization, payment_authorization = nil)
+        @requires_auth ? payment_authorization : authorization
+      end
+
       # Combine method offers into a single callable that presents every method.
       sig { params(entries: T.untyped).returns(ComposedHandler) }
       def compose(*entries)
@@ -109,9 +130,10 @@ module Mpp
 
       # Handle a charge intent.
       #
-      # With a single registered charge method this returns Challenge or
-      # [Credential, Receipt]. With multiple charge methods it implicitly
-      # composes them and returns a ComposedResult.
+      # With a single registered charge method offering a single currency this
+      # returns Challenge or [Credential, Receipt]. With multiple charge methods,
+      # or a method accepting several currencies, it implicitly composes one
+      # offer per method and currency and returns a ComposedResult.
       sig { params(authorization: T.nilable(String), amount: String, kwargs: T.untyped).returns(T.untyped) }
       def charge(authorization, amount, **kwargs)
         charge_methods = @methods.select { |candidate| candidate.intents.key?("charge") }
@@ -119,11 +141,12 @@ module Mpp
 
         request_opts = kwargs.slice(*REQUEST_OPTION_KEYS)
         offer_opts = kwargs.except(*REQUEST_OPTION_KEYS)
+        payment = payment_credential_value(authorization, request_opts[:payment_authorization])
 
-        if charge_methods.length == 1
+        if charge_methods.length == 1 && MethodHelper.offer_currencies(charge_methods.first, offer_opts).nil?
           return charge_one(
             charge_methods.first,
-            authorization,
+            payment,
             amount,
             **request_opts,
             **offer_opts
@@ -133,6 +156,7 @@ module Mpp
         entries = charge_methods.map { |candidate| [candidate, offer_opts.merge(amount: amount)] }
         ComposedHandler.from_entries(self, entries).call(
           authorization: authorization,
+          payment_authorization: request_opts[:payment_authorization],
           payment_signature: request_opts[:payment_signature],
           body: request_opts[:body],
           url: request_opts[:url],
@@ -142,8 +166,10 @@ module Mpp
       end
 
       # Verify or challenge a single method. Used by compose and charge.
-      sig { params(method: T.untyped, authorization: T.nilable(String), amount: String, kwargs: T.untyped).returns(T.untyped) }
-      def charge_one(method, authorization, amount, **kwargs)
+      # The optional request guard can omit an offer after its canonical request
+      # is built, ensuring the guard and challenge use the exact same request.
+      sig { params(method: T.untyped, authorization: T.nilable(String), amount: String, kwargs: T.untyped, request_guard: T.nilable(T.proc.params(request: T::Hash[String, T.untyped]).returns(T::Boolean))).returns(T.untyped) }
+      def charge_one(method, authorization, amount, **kwargs, &request_guard)
         intent = method.intents["charge"]
         raise ArgumentError, "Method #{method.name} does not support charge intent" unless intent
 
@@ -151,7 +177,9 @@ module Mpp
         url = kwargs[:url]
         payment_signature = kwargs[:payment_signature]
         offer_opts = kwargs.except(*REQUEST_OPTION_KEYS)
+        intent, offer_opts = Mpp::Server::MethodHelper.prepare_intent(method, intent, offer_opts)
         request = build_charge_request(method, amount, **offer_opts)
+        return nil if request_guard && !request_guard.call(request)
 
         if payment_signature && method.respond_to?(:bind_x402_credential)
           return verify_x402(
@@ -177,7 +205,9 @@ module Mpp
           description: offer_opts[:description],
           expires: offer_opts[:expires],
           events: @events,
-          body: body
+          method_hook_events: @method_hook_events,
+          body: body,
+          header: @credential_header
         )
       end
 
@@ -187,7 +217,6 @@ module Mpp
         currency = kwargs[:currency]
         recipient = kwargs[:recipient]
         external_id = kwargs[:external_id]
-        memo = kwargs[:memo]
         fee_payer = if kwargs.key?(:fee_payer)
           kwargs[:fee_payer]
         else
@@ -197,7 +226,7 @@ module Mpp
         extra = kwargs[:extra]
         mppx_scope = kwargs[:mppx_scope]
 
-        resolved_currency = currency || (method.respond_to?(:currency) ? method.currency : nil)
+        resolved_currency = currency || primary_currency(method)
         resolved_recipient = recipient || (method.respond_to?(:recipient) ? method.recipient : nil)
         raise ArgumentError, "currency must be set on the method or passed to charge()" unless resolved_currency
         raise ArgumentError, "recipient must be set on the method or passed to charge()" unless resolved_recipient
@@ -228,10 +257,9 @@ module Mpp
         resolved_chain_id = chain_id
         resolved_chain_id ||= method.chain_id if method.respond_to?(:chain_id)
 
-        if memo || fee_payer || !resolved_chain_id.nil?
+        if fee_payer || !resolved_chain_id.nil?
           method_details = {}
           method_details["chainId"] = resolved_chain_id unless resolved_chain_id.nil?
-          method_details["memo"] = memo if memo
           method_details["feePayer"] = true if fee_payer
           request["methodDetails"] = method_details
         end
@@ -268,6 +296,15 @@ module Mpp
         list
       end
 
+      # A method's first accepted currency, else its singular currency.
+      sig { params(method: T.untyped).returns(T.untyped) }
+      def primary_currency(method)
+        currencies = method.respond_to?(:currencies) ? method.currencies : nil
+        return currencies.first if currencies.is_a?(Array) && !currencies.empty?
+
+        method.respond_to?(:currency) ? method.currency : nil
+      end
+
       sig { params(key: String).returns(T.untyped) }
       def resolve_method_key(key)
         name, intent = key.split("/", 2)
@@ -304,7 +341,8 @@ module Mpp
           description,
           nil,
           expires,
-          body
+          body,
+          @credential_header
         )
         method_context = {name: method.name, intent: intent.name}
 
@@ -317,7 +355,7 @@ module Mpp
             body: body,
             http_method: http_method
           )
-          receipt = intent.verify(credential, challenge.request)
+          receipt = IntentLifecycle.call(intent, credential, challenge.request)
         rescue => error
           if @events.has_handlers?(Mpp::Events::PAYMENT_FAILED)
             Verify.emit_payment_failed(
@@ -330,6 +368,9 @@ module Mpp
               retry_challenge: challenge
             )
           end
+          if error.is_a?(Mpp::PaymentError) && error.status != 402
+            raise
+          end
           if error.is_a?(Mpp::ParseError) || error.is_a?(Mpp::VerificationError) || error.is_a?(Mpp::PaymentError)
             if @events.has_handlers?(Mpp::Events::CHALLENGE_CREATED)
               Verify.emit_challenge_created(
@@ -346,9 +387,10 @@ module Mpp
           raise
         end
 
-        if @events.has_handlers?(Mpp::Events::PAYMENT_SUCCESS)
+        if @events.has_handlers?(Mpp::Events::PAYMENT_SUCCESS) || @method_hook_events.has_handlers?(Mpp::Events::PAYMENT_SUCCESS)
           Verify.emit_payment_success(
             dispatcher: @events,
+            method_hook_dispatcher: @method_hook_events,
             challenge: challenge,
             credential: credential,
             method: method_context,
@@ -358,6 +400,30 @@ module Mpp
         end
         [credential, receipt]
       end
+
+      private
+
+      sig { void }
+      def register_method_payment_success
+        @methods.each do |payment_method|
+          next unless payment_method.respond_to?(:on_payment_success)
+
+          hook = payment_method.on_payment_success
+          next if hook.nil?
+          raise ArgumentError, "on_payment_success must be callable" unless hook.respond_to?(:call)
+
+          method_name = payment_method.name
+          intent_names = payment_method.intents.each_value.map { |intent| intent.name }
+          @method_hook_events.on(Mpp::Events::PAYMENT_SUCCESS) do |payload|
+            event_method = payload[:method]
+            next unless event_method.is_a?(Hash)
+            next unless event_method[:name] == method_name
+            next unless intent_names.include?(event_method[:intent])
+
+            hook.call(payload)
+          end
+        end
+      end
     end
   end
 end

data/lib/mpp/server/verify.rb

@@ -15,17 +15,17 @@ module Mpp
       # Verify a payment credential or generate a new challenge.
       #
       # Returns Challenge (payment required) or [Credential, Receipt] (verified).
-      sig { params(authorization: T.nilable(String), intent: T.untyped, request: T::Hash[String, T.untyped], realm: String, secret_key: String, method: T.nilable(String), description: T.nilable(String), meta: T.nilable(T::Hash[String, T.untyped]), expires: T.nilable(String), events: T.nilable(Mpp::Events::Dispatcher), body: T.untyped).returns(T.untyped) }
+      sig { params(authorization: T.nilable(String), intent: T.untyped, request: T::Hash[String, T.untyped], realm: String, secret_key: String, method: T.nilable(String), description: T.nilable(String), meta: T.nilable(T::Hash[String, T.untyped]), expires: T.nilable(String), events: T.nilable(Mpp::Events::Dispatcher), method_hook_events: T.nilable(Mpp::Events::Dispatcher), body: T.untyped, header: T.nilable(String)).returns(T.untyped) }
       def verify_or_challenge(authorization:, intent:, request:, realm:, secret_key:,
-        method: nil, description: nil, meta: nil, expires: nil, events: nil, body: nil)
+        method: nil, description: nil, meta: nil, expires: nil, events: nil, method_hook_events: nil, body: nil, header: nil)
         method_name = method || "tempo"
         request = Mpp::Units.transform_units(request)
         dispatcher = events
-        events_enabled = dispatcher&.has_handlers?
+        events_enabled = dispatcher&.has_handlers? || method_hook_events&.has_handlers?
         method_context = events_enabled ? {name: method_name, intent: intent.name} : nil
 
         new_challenge = Kernel.lambda { |credential = nil, error = nil, submitted_challenge = nil|
-          challenge = create_challenge(method_name, intent.name, request, realm, secret_key, description, meta, expires, body)
+          challenge = create_challenge(method_name, intent.name, request, realm, secret_key, description, meta, expires, body, header)
           if error && dispatcher&.has_handlers?(Mpp::Events::PAYMENT_FAILED)
             emit_payment_failed(
               dispatcher: dispatcher,
@@ -79,7 +79,8 @@ module Mpp
           request: echo_request,
           expires: echo.expires,
           digest: echo.digest,
-          opaque: echo_opaque
+          opaque: echo_opaque,
+          header: echo.header
         )
         unless Mpp.secure_compare(echo.id, expected_id)
           return new_challenge.call(
@@ -157,7 +158,7 @@ module Mpp
         end
 
         begin
-          receipt = intent.verify(credential, request)
+          receipt = IntentLifecycle.call(intent, credential, request)
         rescue => e
           if dispatcher&.has_handlers?(Mpp::Events::PAYMENT_FAILED)
             emit_payment_failed(
@@ -172,9 +173,10 @@ module Mpp
           end
           Kernel.raise
         end
-        if dispatcher&.has_handlers?(Mpp::Events::PAYMENT_SUCCESS)
+        if dispatcher&.has_handlers?(Mpp::Events::PAYMENT_SUCCESS) || method_hook_events&.has_handlers?(Mpp::Events::PAYMENT_SUCCESS)
           emit_payment_success(
             dispatcher: dispatcher,
+            method_hook_dispatcher: method_hook_events,
             challenge: echo,
             credential: credential,
             method: T.must(method_context),
@@ -185,9 +187,9 @@ module Mpp
         [credential, receipt]
       end
 
-      sig { params(method: String, intent_name: String, request: T::Hash[String, T.untyped], realm: String, secret_key: String, description: T.nilable(String), meta: T.nilable(T::Hash[String, T.untyped]), expires: T.nilable(String), body: T.untyped).returns(Mpp::Challenge) }
+      sig { params(method: String, intent_name: String, request: T::Hash[String, T.untyped], realm: String, secret_key: String, description: T.nilable(String), meta: T.nilable(T::Hash[String, T.untyped]), expires: T.nilable(String), body: T.untyped, header: T.nilable(String)).returns(Mpp::Challenge) }
       def create_challenge(method, intent_name, request, realm, secret_key,
-        description = nil, meta = nil, expires = nil, body = nil)
+        description = nil, meta = nil, expires = nil, body = nil, header = nil)
         expires = nil if expires && !expires.is_a?(String)
 
         if expires.nil?
@@ -205,7 +207,8 @@ module Mpp
           expires: expires,
           digest: digest,
           description: description,
-          meta: meta
+          meta: meta,
+          header: header
         )
       end
 
@@ -258,17 +261,24 @@ module Mpp
         dispatcher.emit(Mpp::Events::PAYMENT_FAILED, payload)
       end
 
-      sig { params(dispatcher: Mpp::Events::Dispatcher, challenge: T.untyped, credential: T.untyped, method: T::Hash[Symbol, T.untyped], receipt: T.untyped, request: T::Hash[String, T.untyped]).void }
-      def emit_payment_success(dispatcher:, challenge:, credential:, method:, receipt:, request:)
-        return unless dispatcher.has_handlers?(Mpp::Events::PAYMENT_SUCCESS)
+      # Method hooks are owned by a handler, while `dispatcher` may be shared
+      # by many handlers. Emit the same payload to each without exposing that
+      # handler ownership in the public event payload.
+      sig { params(dispatcher: T.nilable(Mpp::Events::Dispatcher), challenge: T.untyped, credential: T.untyped, method: T::Hash[Symbol, T.untyped], receipt: T.untyped, request: T::Hash[String, T.untyped], method_hook_dispatcher: T.nilable(Mpp::Events::Dispatcher)).void }
+      def emit_payment_success(dispatcher:, challenge:, credential:, method:, receipt:, request:, method_hook_dispatcher: nil)
+        public_handlers = dispatcher&.has_handlers?(Mpp::Events::PAYMENT_SUCCESS)
+        hook_handlers = method_hook_dispatcher&.has_handlers?(Mpp::Events::PAYMENT_SUCCESS)
+        return unless public_handlers || hook_handlers
 
-        dispatcher.emit(Mpp::Events::PAYMENT_SUCCESS, {
+        payload = {
           challenge: challenge,
           credential: credential,
           method: method,
           receipt: receipt,
           request: request
-        })
+        }
+        dispatcher.emit(Mpp::Events::PAYMENT_SUCCESS, payload) if public_handlers
+        method_hook_dispatcher.emit(Mpp::Events::PAYMENT_SUCCESS, payload) if hook_handlers && method_hook_dispatcher != dispatcher
       end
     end
   end

data/lib/mpp/server.rb

@@ -6,6 +6,7 @@ module Mpp
     autoload :Defaults, "mpp/server/defaults"
     autoload :Intent, "mpp/server/intent"
     autoload :FunctionalIntent, "mpp/server/intent"
+    autoload :IntentLifecycle, "mpp/server/intent_lifecycle"
     autoload :Method, "mpp/server/method"
     autoload :Verify, "mpp/server/verify"
     autoload :MppHandler, "mpp/server/mpp_handler"

data/lib/mpp/validation.rb

@@ -0,0 +1,27 @@
+# typed: true
+# frozen_string_literal: true
+
+module Mpp
+  # Non-mutating validation result, matching mppx's Method.Validation fields.
+  # Details are method-specific, not a receipt or a guarantee of settlement.
+  # Challenge issuance and route binding are checked by the server, not by
+  # constructing this record or calling a rail's validate method directly.
+  Validation = Data.define(:challenge, :credential, :intent, :method, :request, :details, :source) do
+    extend T::Sig
+
+    sig do
+      params(
+        challenge: Mpp::ChallengeEcho,
+        credential: Mpp::Credential,
+        intent: String,
+        method: String,
+        request: T::Hash[String, T.untyped],
+        details: T.untyped,
+        source: T.nilable(String)
+      ).void
+    end
+    def initialize(challenge:, credential:, intent:, method:, request:, details:, source: nil)
+      super
+    end
+  end
+end

data/lib/mpp/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module Mpp
-  VERSION = "0.1.5"
+  VERSION = "0.1.7"
 end

data/lib/mpp.rb

@@ -11,10 +11,14 @@ require_relative "mpp/secure_compare"
 module Mpp
   extend T::Sig
 
+  AUTHORIZATION_HEADER = T.let("Authorization", String)
+  PAYMENT_AUTHORIZATION_HEADER = T.let("Payment-Authorization", String)
+
   autoload :Challenge, "mpp/challenge"
   autoload :ChallengeEcho, "mpp/challenge_echo"
   autoload :Credential, "mpp/credential"
   autoload :Receipt, "mpp/receipt"
+  autoload :Validation, "mpp/validation"
   autoload :Parsing, "mpp/parsing"
   autoload :Json, "mpp/json"
   autoload :BodyDigest, "mpp/body_digest"
@@ -43,9 +47,16 @@ module Mpp
     autoload :MCP, "mpp/extensions/mcp"
   end
 
-  sig { params(method: T.untyped, methods: T.nilable(T::Array[T.untyped]), realm: T.untyped, secret_key: T.untyped, events: T.nilable(Mpp::Events::Dispatcher)).returns(T.untyped) }
-  def self.create(method: nil, methods: nil, realm: nil, secret_key: nil, events: nil)
-    Server::MppHandler.create(method: method, methods: methods, realm: realm, secret_key: secret_key, events: events)
+  sig { params(method: T.untyped, methods: T.nilable(T::Array[T.untyped]), realm: T.untyped, secret_key: T.untyped, events: T.nilable(Mpp::Events::Dispatcher), requires_auth: T::Boolean).returns(T.untyped) }
+  def self.create(method: nil, methods: nil, realm: nil, secret_key: nil, events: nil, requires_auth: false)
+    Server::MppHandler.create(
+      method: method,
+      methods: methods,
+      realm: realm,
+      secret_key: secret_key,
+      events: events,
+      requires_auth: requires_auth
+    )
   end
 
   # Error hierarchy

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mpp-rb
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.7
 platform: ruby
 authors:
 - Stripe
@@ -37,6 +37,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: sorbet-runtime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Ruby SDK for the Machine Payments Protocol (MPP) — an HTTP 402 Payment
   Authentication scheme.
 executables: []
@@ -73,9 +87,14 @@ files:
 - lib/mpp/methods/evm/charge_intent.rb
 - lib/mpp/methods/evm/evm_method.rb
 - lib/mpp/methods/stripe.rb
+- lib/mpp/methods/stripe/analytics_metadata.rb
 - lib/mpp/methods/stripe/charge_intent.rb
 - lib/mpp/methods/stripe/client_method.rb
+- lib/mpp/methods/stripe/crypto_payment_recorder.rb
 - lib/mpp/methods/stripe/defaults.rb
+- lib/mpp/methods/stripe/machine_payments.rb
+- lib/mpp/methods/stripe/payment_intent_method.rb
+- lib/mpp/methods/stripe/payment_intent_options.rb
 - lib/mpp/methods/stripe/stripe_method.rb
 - lib/mpp/methods/tempo.rb
 - lib/mpp/methods/tempo/account.rb
@@ -101,6 +120,7 @@ files:
 - lib/mpp/server/decorator.rb
 - lib/mpp/server/defaults.rb
 - lib/mpp/server/intent.rb
+- lib/mpp/server/intent_lifecycle.rb
 - lib/mpp/server/method.rb
 - lib/mpp/server/middleware.rb
 - lib/mpp/server/mpp_handler.rb
@@ -108,6 +128,7 @@ files:
 - lib/mpp/server/verify.rb
 - lib/mpp/store.rb
 - lib/mpp/units.rb
+- lib/mpp/validation.rb
 - lib/mpp/version.rb
 - lib/mpp/x402.rb
 - lib/mpp/x402/facilitator.rb