bml_connect 0.2.0 → 0.3.0

data/lib/bml_connect/resource.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+require "faraday"
+
+module BMLConnect
+  # Shared transport base for the value-object resources (Customers, and the
+  # token/charge resources that follow in features 002/004).
+  #
+  # Responsibilities: build the request URL from the client's base URL, dispatch
+  # over the client's Faraday connection, apply bounded retry with backoff on
+  # transient failures, and map HTTP status codes to the library error
+  # hierarchy. Value-object construction, validation, and auditing live in the
+  # concrete resource, not here.
+  class Resource
+    def initialize(client)
+      @client = client
+    end
+
+    private
+
+    attr_reader :client
+
+    # Dispatch +method+ to +path+ (a host-root path like "/public-customers").
+    # Returns the Faraday response on 2xx; raises a mapped error otherwise.
+    #
+    # +retries+ defaults to true (bounded retry with backoff on transient
+    # failures). Pass +retries: false+ for money-moving calls that MUST make
+    # exactly one attempt — transaction create and capture (FR-016): retry there
+    # risks a double charge, and no server-side idempotency key is documented.
+    def request(method, path, body: nil, retries: true)
+      url = request_url(path)
+
+      dispatch = lambda do
+        client.http_client.public_send(method, url) do |req|
+          req.body = JSON.generate(body) if body
+        end
+      end
+
+      response = retries ? with_retries(&dispatch) : single_attempt(&dispatch)
+
+      handle(response)
+    end
+
+    # Exactly one attempt, no retry. A transport failure becomes an
+    # AvailabilityError immediately so the caller can reconcile rather than
+    # blindly re-send (FR-016, SC-007).
+    def single_attempt
+      yield
+    rescue Faraday::TimeoutError, Faraday::ConnectionFailed => e
+      raise AvailabilityError, e.message
+    end
+
+    # Customer paths live at the host root ("/public-customers"), NOT under the
+    # "/public/" prefix the transaction endpoints use. URI.join with an absolute
+    # path replaces base_url's path while keeping its scheme+host, so the URL is
+    # still derived from the client (no hardcoded host) per constitution/R10.
+    def request_url(path)
+      URI.join(client.base_url, path).to_s
+    end
+
+    def handle(response)
+      return response if (200..299).cover?(response.status)
+
+      raise map_error(response)
+    end
+
+    def with_retries(&block)
+      attempts = 0
+
+      loop do
+        begin
+          response = block.call
+        rescue Faraday::TimeoutError, Faraday::ConnectionFailed => e
+          raise AvailabilityError, e.message if attempts >= max_retries
+
+          attempts += 1
+          backoff(attempts)
+          next
+        end
+
+        if retryable_status?(response.status) && attempts < max_retries
+          attempts += 1
+          backoff(attempts)
+          next
+        end
+
+        return response
+      end
+    end
+
+    # Transient statuses worth retrying (FR-013a): request timeout, rate limit,
+    # and any 5xx. A 429 that survives the retries is still surfaced as a
+    # RateLimitError by map_error, carrying BML's Retry-After hint for the
+    # caller — the internal wait stays governed by the client's bounded backoff,
+    # not by an arbitrary server-supplied delay.
+    def retryable_status?(status)
+      status == 408 || status == 429 || (500..599).cover?(status)
+    end
+
+    def backoff(attempts)
+      seconds = retry_backoff * attempts
+      sleep(seconds) if seconds.positive?
+    end
+
+    def max_retries
+      client.respond_to?(:max_retries) && client.max_retries ? client.max_retries : 2
+    end
+
+    def retry_backoff
+      value = client.respond_to?(:retry_backoff) ? client.retry_backoff : nil
+      value.to_f
+    end
+
+    def map_error(response)
+      status = response.status
+      body = response.body
+      # Masked at the source: BML's own error text is data we did not author, and
+      # a card-like value in it must never reach an error message, a log, or an
+      # audit record (Constitution I; feature 005 FR-011).
+      message = Masking.scrub(extract_message(body) || "BML request failed with status #{status}")
+
+      case status
+      when 400, 422 then ValidationError.new(message)
+      when 401, 403 then AuthenticationError.new(message)
+      when 404      then NotFoundError.new(message)
+      when 409      then ConflictError.new(message, body: body)
+      when 429      then RateLimitError.new(message, retry_after: retry_after(response))
+      else               AvailabilityError.new(message)
+      end
+    end
+
+    def extract_message(body)
+      return nil unless body.is_a?(Hash)
+
+      body[:message] || body["message"] || body[:error] || body["error"]
+    end
+
+    def retry_after(response)
+      headers = response.respond_to?(:headers) ? response.headers : nil
+      headers && (headers["Retry-After"] || headers["retry-after"])
+    end
+  end
+end

data/lib/bml_connect/tokens.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module BMLConnect
+  # Stored-card tokens: list, retrieve, and delete a customer's saved cards,
+  # all nested under /public-customers/{customerId}/tokens.
+  #
+  # Read-and-delete ONLY, by contract. BML publishes no endpoint that creates a
+  # token — a token is a side effect of a tokenizing transaction (feature 003),
+  # completed by the cardholder on BML's hosted page. This resource therefore
+  # exposes no create/tokenize/store/detokenize method, and its absence is
+  # deliberate and test-enforced (FR-005/FR-008, SC-006). No operation here
+  # accepts a card number, security code, or capture handle (FR-006).
+  #
+  # Reached through a configured client as `client.tokens`, mirroring
+  # `client.customers`. Returns whitelisted value objects and raises the
+  # library's error hierarchy on failure. Transient failures are retried by the
+  # shared transport (research R9); only delete is audited (FR-014).
+  class Tokens < Resource
+    PATH = "/public-customers/%<customer_id>s/tokens"
+
+    # List a customer's stored cards. Returns a Models::TokenList (Enumerable).
+    # An empty collection is an empty list, never an error, and an auth failure
+    # is never swallowed into one (FR-016, research R6). Not audited (read).
+    def list(customer_id, actor: nil)
+      require_customer_id!(customer_id)
+      screen_actor!(actor)
+
+      response = request(:get, collection_path(customer_id))
+      Models::TokenList.new(response.body)
+    end
+
+    # Retrieve one stored card by id. Raises NotFoundError for an unknown token
+    # or one belonging to another customer (tokens are scoped to their
+    # customer). Not audited (read).
+    def retrieve(customer_id, token_id, actor: nil)
+      require_customer_id!(customer_id)
+      require_token_id!(token_id)
+      screen_actor!(actor)
+
+      response = request(:get, member_path(customer_id, token_id))
+      Models::Token.new(response.body)
+    end
+
+    # Delete (soft-delete) a stored card. Returns true on 204. Emits exactly one
+    # audit record, written after the request settles — including after any
+    # transient retries — so a retried delete is audited once, capturing the
+    # final outcome (FR-013a x FR-014). The optional `actor` names who initiated
+    # the deletion for the audit "who"; it must not carry cardholder data.
+    def delete(customer_id, token_id, actor: nil)
+      require_customer_id!(customer_id)
+      require_token_id!(token_id)
+      screen_actor!(actor)
+
+      request(:delete, member_path(customer_id, token_id))
+      audit(:delete, actor: actor, subject: { customer_id: customer_id, token_id: token_id })
+      true
+    end
+
+    private
+
+    def collection_path(customer_id)
+      format(PATH, customer_id: customer_id)
+    end
+
+    def member_path(customer_id, token_id)
+      "#{collection_path(customer_id)}/#{token_id}"
+    end
+
+    def require_customer_id!(customer_id)
+      return unless blank?(customer_id)
+
+      raise ValidationError.new("customer_id is required", field: :customer_id)
+    end
+
+    def require_token_id!(token_id)
+      return unless blank?(token_id)
+
+      raise ValidationError.new("token_id is required", field: :token_id)
+    end
+
+    # The actor reference is the only caller-supplied string this resource takes.
+    # Screen it for card data so nothing PAN-like can reach an audit record.
+    def screen_actor!(actor)
+      return if actor.nil?
+      return unless actor.is_a?(String)
+      return unless Masking.looks_like_pan?(actor)
+
+      raise ValidationError.new("actor must not contain card data", field: :actor)
+    end
+
+    def audit(action, actor:, subject:)
+      Audit.emit_event(client, action: action, actor: actor, outcome: :success, subject: subject)
+    end
+
+    def blank?(value)
+      value.nil? || (value.is_a?(String) && value.strip.empty?)
+    end
+  end
+end

data/lib/bml_connect/transactions.rb

@@ -1,18 +1,62 @@
 # frozen_string_literal: true
 
-require 'json'
+require "json"
 
-require 'deep_merge/rails_compat'
+require "deep_merge/rails_compat"
 
 module BMLConnect
-  class Transactions
-    END_POINT = 'transactions'
+  # The transactions resource.
+  #
+  # This resource straddles two eras. The v1 methods — #create, #get, #list —
+  # are RELEASED and depended on by six call sites in msgowl/website; they return
+  # raw Faraday::Response objects and MUST NOT change behavior, signature, or
+  # return type (FR-010). #create still posts to the undocumented-but-live
+  # /public/transactions with the SHA1 signature, and is deprecated (FR-011).
+  #
+  # The v2 methods — #create_v2, #retrieve, #update, #capture, #cancel — are
+  # additive. They speak the documented endpoints, return whitelisted
+  # TransactionRecord value objects, raise the library's error hierarchy, and
+  # emit audit records on state change (FR-019). They send no signature until UAT
+  # observation settles whether v2 accepts one (FR-012).
+  class Transactions < Resource
+    END_POINT = "transactions"
 
-    def initialize(client)
-      @client = client
+    # Documented v2 create endpoint (FR-001).
+    V2_CREATE_PATH = "/public/v2/transactions"
+    # Shared retrieve/update/capture/cancel base (FR-006/007/008/009). The v1
+    # retrieve path too, so a v1-created transaction is retrievable here.
+    BASE_PATH = "/public/transactions"
+
+    # Fields accepted on a v2 create body (variants 3 and 4 — direct amount, with
+    # an existing customerId or an inline customer). Variants 1/2 (shop orders)
+    # and 5 (foreign exchange) are out of scope and rejected by name (FR-020).
+    CREATE_V2_FIELDS = %i[
+      amount currency redirectUrl webhook localId customerReference
+      customerId customer expires tokenizationDetails
+    ].freeze
+
+    # Presence of any of these signals an unsupported create variant.
+    UNSUPPORTED_VARIANT_KEYS = %i[order fxQuoteId].freeze
+
+    # Fields amendable via #update; only supplied keys are sent (FR-007).
+    UPDATE_FIELDS = %i[customerReference localData pnr].freeze
+
+    # Process-wide guard so the v1 deprecation warning fires at most once per
+    # process (FR-011). Resettable so tests can assert the once-only behavior.
+    class << self
+      attr_accessor :v1_deprecation_warned
     end
 
+    # Construction is inherited from Resource (which stores the client); no
+    # override needed. @client is available to every method below.
+
+    # --- v1, released surface (UNCHANGED behavior) --------------------------
+
+    # Deprecated. Posts the signed body to the undocumented-but-live v1 endpoint
+    # and returns a Faraday::Response, exactly as before. Emits a one-time
+    # deprecation warning (FR-011) that does not alter behavior or return value.
     def create(params)
+      warn_v1_deprecation
       transaction = BMLConnect::Models::Transaction.new(params)
       # generate signature
       transaction.sign(@client.api_key)
@@ -26,5 +70,245 @@ module BMLConnect
     def list(params = {})
       @client.get(END_POINT, params)
     end
+
+    # --- v2, additive value-object surface ----------------------------------
+
+    # Create a transaction on the documented v2 endpoint. Validates locally
+    # (amount is a positive Integer in minor units; currency present; customer
+    # variant; tokenization rules; PAN screen) before any remote call. NEVER
+    # auto-retried (FR-016): a timeout raises AvailabilityError after exactly one
+    # attempt. Returns a TransactionRecord and emits a create audit record.
+    def create_v2(details, actor: nil)
+      attributes = symbolize(details)
+      reject_unsupported_variants!(attributes)
+      validate_amount!(attributes[:amount])
+      require_present!(attributes, :currency)
+      validate_customer_variant!(attributes)
+      tokenization = build_tokenization(attributes)
+      warn_tokenization_without_customer(attributes, tokenization)
+      screen_for_pan!(attributes)
+      screen_actor!(actor)
+
+      body = build_create_body(attributes, tokenization)
+      response = request(:post, V2_CREATE_PATH, body: body, retries: false)
+      record = Models::TransactionRecord.new(response.body)
+      audit(:create, actor: actor, subject: { transaction_id: record.id })
+      record
+    end
+
+    # Retrieve a transaction by id. Value-object counterpart to #get, which
+    # remains available. `state` is passed through verbatim (research R8). Not
+    # audited (read). MAY retry (FR-016) — hence `retries: true` by default,
+    # which is feature 003's released behavior, unchanged.
+    #
+    # Pass `retries: false` when the CALLER must bound the number of HTTP calls
+    # rather than the transport. The webhook handler (feature 005) does exactly
+    # that: FR-009 caps a notification at two retrieves counted in HTTP calls, so
+    # with retry left on, one delivery arriving while BML is flaky would make up
+    # to six requests and a forger could use a wobbly BML to triple their
+    # amplification (005 research R3). A transport failure then raises
+    # AvailabilityError after exactly one attempt.
+    def retrieve(id, actor: nil, retries: true)
+      require_id!(id)
+      screen_actor!(actor)
+
+      response = request(:get, "#{BASE_PATH}/#{id}", retries: retries)
+      Models::TransactionRecord.new(response.body)
+    end
+
+    # Partially amend a transaction. Sends only the supplied keys among
+    # customerReference/localData/pnr; never serializes an unset field as null.
+    # Rejects an empty change set locally. Emits an update audit record (FR-017).
+    def update(id, changes, actor: nil)
+      require_id!(id)
+      attributes = symbolize(changes)
+      raise ValidationError.new("no changes supplied", field: :changes) if attributes.empty?
+
+      screen_for_pan!(attributes)
+      screen_actor!(actor)
+
+      body = attributes.select { |key, _| UPDATE_FIELDS.include?(key) }
+      raise ValidationError.new("no updatable fields supplied", field: :changes) if body.empty?
+
+      response = request(:patch, "#{BASE_PATH}/#{id}", body: body)
+      record = Models::TransactionRecord.new(response.body)
+      audit(:update, actor: actor, subject: { transaction_id: id })
+      record
+    end
+
+    # Capture a pre-authorized amount. `amount` obeys the same rule as create
+    # (FR-008): a positive Integer in minor units. Money-moving, so NEVER
+    # auto-retried (FR-016). Emits a capture audit record.
+    def capture(id, amount:, actor: nil)
+      require_id!(id)
+      validate_amount!(amount)
+      screen_actor!(actor)
+
+      body = { id: id, amount: amount }
+      response = request(:post, "#{BASE_PATH}/#{id}/capture", body: body, retries: false)
+      record = Models::TransactionRecord.new(response.body)
+      audit(:capture, actor: actor, subject: { transaction_id: id })
+      record
+    end
+
+    # Cancel a transaction. Emits a cancel audit record. MAY retry (FR-016):
+    # cancellation is not money-moving and is safe to re-send.
+    def cancel(id, actor: nil)
+      require_id!(id)
+      screen_actor!(actor)
+
+      response = request(:post, "#{BASE_PATH}/#{id}/cancel")
+      record = Models::TransactionRecord.new(response.body)
+      audit(:cancel, actor: actor, subject: { transaction_id: id })
+      record
+    end
+
+    private
+
+    # Diagnostic-only: send a minimal v2 create and return the RAW Faraday
+    # response, for the UAT probe that resolves which field carries the hosted
+    # payment URL ([UNVERIFIED] #1 / T021). Not part of the public surface.
+    def raw_create_v2(details)
+      attributes = symbolize(details)
+      validate_amount!(attributes[:amount])
+      require_present!(attributes, :currency)
+      body = build_create_body(attributes, build_tokenization(attributes))
+      request(:post, V2_CREATE_PATH, body: body, retries: false)
+    end
+
+    def build_create_body(attributes, tokenization)
+      body = attributes.select { |key, _| CREATE_V2_FIELDS.include?(key) }
+      body[:tokenizationDetails] = tokenization.to_h if tokenization
+      body
+    end
+
+    # Validation object if tokenizationDetails supplied (validates on construct,
+    # before any remote call); nil otherwise.
+    def build_tokenization(attributes)
+      return nil unless attributes.key?(:tokenizationDetails)
+
+      Models::TokenizationDetails.new(attributes[:tokenizationDetails])
+    end
+
+    # Edge case: tokenization with no customer to attach the token to is
+    # [UNVERIFIED] (#5). The library WARNS and forwards rather than blocking,
+    # pending observation — it does not invent a rule BML has not stated.
+    def warn_tokenization_without_customer(attributes, tokenization)
+      return unless tokenization
+      return unless blank?(attributes[:customerId]) && attributes[:customer].nil?
+
+      logger = @client.respond_to?(:logger) ? @client.logger : nil
+      logger&.warn(
+        "[bml_connect] tokenizationDetails supplied without a customerId; " \
+        "whether BML stores a token with no customer to attach it to is unverified"
+      )
+    end
+
+    def reject_unsupported_variants!(attributes)
+      UNSUPPORTED_VARIANT_KEYS.each do |key|
+        next unless attributes.key?(key)
+
+        raise ValidationError.new(
+          "create variant using `#{key}` is not supported; use amount/currency (variant 3 or 4)",
+          field: key
+        )
+      end
+    end
+
+    # FR-005/FR-008: a positive Integer in minor units. A Float, a String, zero,
+    # a negative, or a boolean is rejected by name with no remote call. Never
+    # coerced — guessing on a money field is unacceptable (research R5).
+    def validate_amount!(amount)
+      raise ValidationError.new("amount is required", field: :amount) if amount.nil?
+      unless amount.is_a?(Integer)
+        raise ValidationError.new("amount must be an Integer in minor units, not #{amount.class}", field: :amount)
+      end
+      return if amount.positive?
+
+      raise ValidationError.new("amount must be a positive number of minor units", field: :amount)
+    end
+
+    def validate_customer_variant!(attributes)
+      customer = attributes[:customer]
+      if !blank?(attributes[:customerId]) && !customer.nil?
+        raise ValidationError.new("customerId and inline customer are mutually exclusive", field: :customerId)
+      end
+
+      validate_inline_customer!(customer) unless customer.nil?
+    end
+
+    def validate_inline_customer!(customer)
+      unless customer.respond_to?(:each_pair)
+        raise ValidationError.new("customer must be an object with name and email", field: :customer)
+      end
+
+      inline = customer.transform_keys(&:to_sym)
+      raise ValidationError.new("customer.name is required", field: :customer) if blank?(inline[:name])
+      raise ValidationError.new("customer.email is required", field: :customer) if blank?(inline[:email])
+    end
+
+    def warn_v1_deprecation
+      return if self.class.v1_deprecation_warned
+
+      self.class.v1_deprecation_warned = true
+      logger = @client.respond_to?(:logger) ? @client.logger : nil
+      logger&.warn(
+        "[bml_connect] transactions.create (legacy v1 POST /public/transactions) is deprecated; " \
+        "migrate to transactions.create_v2 (POST /public/v2/transactions)"
+      )
+    end
+
+    # --- shared local helpers (mirror the Customers resource) ---------------
+
+    def symbolize(attributes)
+      raise ValidationError, "expected a hash of attributes" unless attributes.respond_to?(:each_pair)
+
+      attributes.transform_keys(&:to_sym)
+    end
+
+    def require_present!(attributes, field)
+      return unless blank?(attributes[field])
+
+      raise ValidationError.new("#{field} is required", field: field)
+    end
+
+    def require_id!(id)
+      return unless blank?(id)
+
+      raise ValidationError.new("transaction id is required", field: :id)
+    end
+
+    # Screen every caller-supplied string value for card data (FR-014): no field
+    # is exempt. Recurses into nested hashes (inline customer, tokenization) and
+    # arrays so a PAN cannot hide one level down.
+    def screen_for_pan!(value, field: nil)
+      case value
+      when String then reject_pan_string!(value, field)
+      when Hash   then value.each { |key, nested| screen_for_pan!(nested, field: field || key) }
+      when Array  then value.each { |nested| screen_for_pan!(nested, field: field) }
+      end
+    end
+
+    def reject_pan_string!(value, field)
+      return unless Masking.looks_like_pan?(value)
+
+      raise ValidationError.new("#{field} contains data that looks like a card number", field: field)
+    end
+
+    def screen_actor!(actor)
+      return if actor.nil?
+      return unless actor.is_a?(String)
+      return unless Masking.looks_like_pan?(actor)
+
+      raise ValidationError.new("actor must not contain card data", field: :actor)
+    end
+
+    def audit(action, actor:, subject:)
+      Audit.emit_event(@client, action: action, actor: actor, outcome: :success, subject: subject)
+    end
+
+    def blank?(value)
+      value.nil? || (value.is_a?(String) && value.strip.empty?)
+    end
   end
 end

data/lib/bml_connect/version.rb

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

data/lib/bml_connect/webhooks/router.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module BMLConnect
+  class Webhooks
+    # Sends a verified status change to the handler that owns it.
+    #
+    # A merchant registers ONE hook in BML's portal, so a single endpoint
+    # receives notifications for every transaction the merchant creates —
+    # enrolments, settlement charges, interactive payments, top-ups. BML's
+    # payload is [UNVERIFIED] and in any case cannot say which of the
+    # consumer's flows a transaction belongs to; only the consumer knows that.
+    # So the resolver is supplied by the consumer and this class stays ignorant
+    # of what the names mean.
+    #
+    #   router = BMLConnect::Webhooks::Router.new
+    #   router.resolve { |result| Ownership.of(result.transaction_id) }
+    #   router.on(:enrolment)  { |result| ... }
+    #   router.on(:settlement) { |result| ... }
+    #   router.otherwise       { |result| ... }
+    #
+    #   client.webhooks.handle(body: body, headers: headers, router: router)
+    class Router
+      class UnroutableError < BMLConnect::Error; end
+
+      def initialize
+        @handlers = {}
+        @resolver = nil
+        @fallback = nil
+      end
+
+      def resolve(&block)
+        raise ArgumentError, "resolve requires a block" unless block
+
+        @resolver = block
+        self
+      end
+
+      # Registering twice is a mistake rather than an override: silently
+      # replacing a handler hides the duplicate until a delivery goes to the
+      # wrong place.
+      def on(name, &block)
+        raise ArgumentError, "a handler for #{name} is already registered" if @handlers.key?(key(name))
+        raise ArgumentError, "on(#{name}) requires a block" unless block
+
+        @handlers[key(name)] = block
+        self
+      end
+
+      def otherwise(&block)
+        raise ArgumentError, "otherwise requires a block" unless block
+
+        @fallback = block
+        self
+      end
+
+      def dispatch(result)
+        raise UnroutableError, "no resolver registered" if @resolver.nil?
+
+        name = @resolver.call(result)
+        return handler_for!(name, result).call(result) unless name.nil?
+
+        unless @fallback
+          raise UnroutableError,
+                "nothing owns transaction #{result.transaction_id} and no fallback is registered"
+        end
+
+        @fallback.call(result)
+      end
+
+      private
+
+      def handler_for!(name, result)
+        @handlers.fetch(key(name)) do
+          raise UnroutableError,
+                "resolver named #{name} for transaction #{result.transaction_id}, " \
+                "but no handler is registered under it"
+        end
+      end
+
+      def key(name)
+        name.to_sym
+      end
+    end
+  end
+end