bml_connect 0.2.0 → 0.3.0

data/lib/bml_connect/models/status_change_result.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module BMLConnect
+  module Models
+    # What BMLConnect::Webhooks#handle returns: the authoritative outcome of one
+    # inbound transaction-status notification (feature 005, FR-004).
+    #
+    # The important thing about this class is what it does NOT expose. There is no
+    # +payload+, +body+, +headers+ or +raw+ reader, and there never should be
+    # (FR-004a, SC-008i). A payload-shaped object here would invite
+    # <tt>result.payload[:state]</tt> — a status read from an unauthenticated
+    # source — which defeats the entire point of verify-by-fetch. The missing
+    # accessor IS the control; a test asserts it stays missing.
+    #
+    # Payload-derived information is limited to individually named fields: the
+    # masked +claimed_status+, the +disagreed?+ flag, and the masked
+    # +event_type+. None of them is ever the reported status. The raw body
+    # remains available for diagnosis where forensic detail belongs — in the
+    # masked audit record (FR-004b).
+    class StatusChangeResult
+      # Whitelisted view, in a stable order.
+      ATTRIBUTES = %i[
+        transaction_id status changed_at claimed_status event_type
+        disagreed rechecked advisory_http_status transaction
+      ].freeze
+
+      # The transaction identifier read from the payload (FR-002) — the one field
+      # taken from the untrusted delivery and acted on.
+      attr_reader :transaction_id
+
+      # The authoritative record retrieved from BML (feature 003's model).
+      attr_reader :transaction
+
+      # What the payload claimed, masked. DIAGNOSTIC ONLY: never act on it.
+      attr_reader :claimed_status
+
+      # Which category of notification the payload says this is, masked — BML's
+      # portal registers a hook per category ("Transaction change",
+      # "Tokenisation status") and the delivery names one in +eventType+.
+      #
+      # ROUTING ONLY, and the distinction matters: a category selects WHICH
+      # handler runs, never WHAT it believes. A forged category can therefore
+      # only send a delivery to the wrong handler, where the authoritative
+      # record still has to bear it out. A handler that acted on this field as
+      # though it were a fact would reintroduce exactly the trust this class
+      # exists to refuse.
+      attr_reader :event_type
+
+      # What the host application SHOULD return to BML. Advice, not control
+      # (FR-016b).
+      attr_reader :advisory_http_status
+
+      def initialize(transaction_id:, transaction:, claimed_status: nil, event_type: nil,
+                     disagreed: false, rechecked: false, advisory_http_status: 200)
+        @transaction_id = transaction_id
+        @transaction = transaction
+        @claimed_status = claimed_status.nil? ? nil : Masking.scrub(claimed_status.to_s)
+        @event_type = event_type.nil? ? nil : Masking.scrub(event_type.to_s)
+        @disagreed = disagreed ? true : false
+        @rechecked = rechecked ? true : false
+        @advisory_http_status = advisory_http_status
+      end
+
+      # The authoritative status, verbatim (FR-005). Treat it as
+      # current-as-of-retrieve, not as final.
+      def status
+        transaction&.state
+      end
+
+      # When the authoritative record last changed (FR-004).
+      def changed_at
+        transaction&.updated
+      end
+
+      # True when the payload's claim disagreed with the authoritative status.
+      # The signature of a forgery attempt or a stale replay — worth recording,
+      # never worth reporting as a status.
+      def disagreed?
+        @disagreed
+      end
+
+      # True when the single delayed re-check ran (FR-010).
+      def rechecked?
+        @rechecked
+      end
+
+      def to_h
+        {
+          transaction_id: transaction_id,
+          status: status,
+          changed_at: changed_at,
+          claimed_status: claimed_status,
+          event_type: event_type,
+          disagreed: disagreed?,
+          rechecked: rechecked?,
+          advisory_http_status: advisory_http_status,
+          transaction: transaction&.to_h
+        }
+      end
+
+      def ==(other)
+        other.is_a?(StatusChangeResult) && to_h == other.to_h
+      end
+      alias eql? ==
+
+      def hash
+        to_h.hash
+      end
+
+      # Limited to the whitelist, so a result is always safe to log — there is no
+      # raw body on it to leak.
+      def inspect
+        summary = {
+          transaction_id: transaction_id,
+          status: status,
+          claimed_status: claimed_status,
+          event_type: event_type,
+          disagreed: disagreed?,
+          rechecked: rechecked?,
+          advisory_http_status: advisory_http_status
+        }
+        "#<BMLConnect::Models::StatusChangeResult #{summary.inspect}>"
+      end
+    end
+  end
+end

data/lib/bml_connect/models/token.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module BMLConnect
+  module Models
+    # A read-only value object for a BML stored-card token (BML's CustomerTokens
+    # schema).
+    #
+    # Attributes are whitelisted: only the fields below are pulled from a BML
+    # response, so an unexpected key — a full card number above all — cannot
+    # reach the object, a log line, or an audit record (Constitution I,
+    # FR-007/FR-009). The library mirrors BML's own field names verbatim and
+    # invents no `last_four`/`scheme` alias (research R7).
+    class Token
+      ATTRIBUTES = %i[
+        id brand provider token tokenType deleted tokenProvider
+        tokenAgreementId tokenAgreementType tokenExpiryMonth tokenExpiryYear
+        paddedCardNumber customerId companyId created updated
+      ].freeze
+
+      ATTRIBUTES.each { |attribute| attr_reader attribute }
+
+      def initialize(data = {})
+        source = data || {}
+        ATTRIBUTES.each do |attribute|
+          value = source.key?(attribute) ? source[attribute] : source[attribute.to_s]
+          instance_variable_set("@#{attribute}", value)
+        end
+      end
+
+      def deleted?
+        deleted == true
+      end
+
+      # True for a token backed by a recurring/unscheduled agreement, which BML
+      # signals by populating `tokenAgreementId`.
+      def recurring?
+        !blank?(tokenAgreementId)
+      end
+
+      def to_h
+        ATTRIBUTES.each_with_object({}) do |attribute, hash|
+          hash[attribute] = public_send(attribute)
+        end
+      end
+
+      def ==(other)
+        other.is_a?(Token) && to_h == other.to_h
+      end
+      alias eql? ==
+
+      def hash
+        to_h.hash
+      end
+
+      # Limited to the whitelist, so a token is always safe to log.
+      def inspect
+        present = to_h.reject { |_, value| value.nil? }
+        "#<BMLConnect::Models::Token #{present.inspect}>"
+      end
+
+      private
+
+      def blank?(value)
+        value.nil? || (value.is_a?(String) && value.strip.empty?)
+      end
+    end
+  end
+end

data/lib/bml_connect/models/token_list.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module BMLConnect
+  module Models
+    # A customer's stored-card tokens, exposed as an Enumerable over Token
+    # value objects.
+    #
+    # The list response shape is [UNVERIFIED] (research R4): the published
+    # contract attaches the token array to the operation's `requestBody` rather
+    # than to a response, so BML may send either a bare JSON array or a
+    # `{ count, items }` envelope (the shape /public-customers uses). This parser
+    # tolerates both and never raises on a surprising top-level type.
+    class TokenList
+      include Enumerable
+
+      attr_reader :count, :items
+
+      def initialize(data = {})
+        raw_items = extract_items(data)
+        @items = raw_items.map { |item| Token.new(item) }
+        @count = coerce_count(count_hint(data))
+      end
+
+      def each(&block)
+        items.each(&block)
+      end
+
+      def size
+        items.size
+      end
+
+      def empty?
+        items.empty?
+      end
+
+      # The subset that has not been (soft-)deleted.
+      def active
+        items.reject(&:deleted?)
+      end
+
+      private
+
+      def extract_items(data)
+        return data if data.is_a?(Array)
+        return [] unless data.is_a?(Hash)
+
+        data[:items] || data["items"] || []
+      end
+
+      def count_hint(data)
+        return data.size if data.is_a?(Array)
+        return nil unless data.is_a?(Hash)
+
+        data[:count] || data["count"]
+      end
+
+      def coerce_count(raw)
+        Integer(raw)
+      rescue ArgumentError, TypeError
+        items.size
+      end
+    end
+  end
+end

data/lib/bml_connect/models/tokenization_details.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "date"
+
+module BMLConnect
+  module Models
+    # Input-only value object for the `tokenizationDetails` sub-object on a v2
+    # create body. Never returned by BML; its presence is what instructs BML to
+    # store the card (FR-003). Constructing one validates it locally — every
+    # rule below runs before any remote call is made.
+    #
+    # The allowed `paymentType` and `recurringFrequency` values come from BML's
+    # prose descriptions, not a JSON enum (the document declares none), so an
+    # unrecognized value is rejected with a message quoting the documented set.
+    class TokenizationDetails
+      PAYMENT_TYPES = %w[RECURRING UNSCHEDULED].freeze
+      RECURRING_FREQUENCIES = %w[
+        DAILY WEEKLY BIWEEKLY FORTNIGHTLY MONTHLY QUARTERLY YEARLY AD_HOC
+      ].freeze
+      EXPIRY_FORMAT = /\A\d{4}-\d{2}-\d{2}\z/.freeze
+
+      # The documented keys, in serialization order. Readers are defined and
+      # instance variables set by iterating this constant (as Token/Customer do),
+      # so rubocop never sees the camelCase names as literals.
+      FIELDS = %i[tokenize paymentType recurringFrequency expiryDate].freeze
+
+      FIELDS.each { |field| attr_reader field }
+
+      # +today+ is injectable so the future-date rule is testable without
+      # stubbing the clock.
+      def initialize(fields, today: nil)
+        @today = today
+        source = symbolize(fields)
+        FIELDS.each { |field| instance_variable_set("@#{field}", source[field]) }
+        validate!
+      end
+
+      # Serializes to exactly the documented keys, omitting any not supplied.
+      def to_h
+        FIELDS.each_with_object({}) { |field, hash| hash[field] = public_send(field) }
+              .reject { |_, value| value.nil? }
+      end
+
+      private
+
+      def validate!
+        validate_tokenize!
+        validate_payment_type!
+        require_recurring_fields! if paymentType == "RECURRING"
+
+        # FR-004: whenever expiryDate is supplied (RECURRING or not), it must be a
+        # future date in yyyy-mm-dd form.
+        validate_expiry! unless blank?(expiryDate)
+      end
+
+      def validate_tokenize!
+        raise ValidationError.new("tokenize is required in tokenizationDetails", field: :tokenize) if tokenize.nil?
+        return if [true, false].include?(tokenize)
+
+        raise ValidationError.new("tokenize must be true or false", field: :tokenize)
+      end
+
+      def validate_payment_type!
+        if blank?(paymentType)
+          raise ValidationError.new("paymentType is required in tokenizationDetails", field: :paymentType)
+        end
+        return if PAYMENT_TYPES.include?(paymentType)
+
+        raise ValidationError.new("paymentType must be one of #{PAYMENT_TYPES.join(", ")}", field: :paymentType)
+      end
+
+      def require_recurring_fields!
+        if blank?(recurringFrequency)
+          raise ValidationError.new("recurringFrequency is required when paymentType is RECURRING",
+                                    field: :recurringFrequency)
+        end
+        unless RECURRING_FREQUENCIES.include?(recurringFrequency)
+          raise ValidationError.new("recurringFrequency must be one of #{RECURRING_FREQUENCIES.join(", ")}",
+                                    field: :recurringFrequency)
+        end
+        return unless blank?(expiryDate)
+
+        raise ValidationError.new("expiryDate is required when paymentType is RECURRING", field: :expiryDate)
+      end
+
+      def validate_expiry!
+        unless expiryDate.is_a?(String) && expiryDate =~ EXPIRY_FORMAT
+          raise ValidationError.new("expiryDate must be in yyyy-mm-dd form", field: :expiryDate)
+        end
+
+        parsed =
+          begin
+            Date.iso8601(expiryDate)
+          rescue ArgumentError
+            raise ValidationError.new("expiryDate is not a valid date", field: :expiryDate)
+          end
+
+        reference = @today || Date.today
+        raise ValidationError.new("expiryDate must be in the future", field: :expiryDate) unless parsed > reference
+      end
+
+      def symbolize(fields)
+        unless fields.respond_to?(:each_pair)
+          raise ValidationError.new("tokenizationDetails must be an object", field: :tokenizationDetails)
+        end
+
+        fields.transform_keys(&:to_sym)
+      end
+
+      def blank?(value)
+        value.nil? || (value.is_a?(String) && value.strip.empty?)
+      end
+    end
+  end
+end

data/lib/bml_connect/models/transaction.rb

@@ -14,7 +14,12 @@ module BMLConnect
       
       def initialize(fields)
         # check for required fields
-        raise ArgumentError.new("Missing Required Fields: [#{REQUIRED_FIELDS.join(', ')}]") unless REQUIRED_FIELDS.subset?(fields.keys.to_set)
+        # `REQUIRED_FIELDS.to_a.join` — NOT `REQUIRED_FIELDS.join`: Set#join was
+        # added in Ruby 3.0 but the gemspec floor is 2.3, so on Ruby 2.7 (which
+        # msgowl/website runs) a bare Set#join raised NoMethodError instead of the
+        # intended ArgumentError. Bug fix, not a behavior change — it makes this
+        # path do what spec/transaction_spec.rb already asserts (research R11).
+        raise ArgumentError.new("Missing Required Fields: [#{REQUIRED_FIELDS.to_a.join(', ')}]") unless REQUIRED_FIELDS.subset?(fields.keys.to_set)
 
         #initialize transaction props
         fields.each { |k,v| public_send("#{k}=", v) }

data/lib/bml_connect/models/transaction_record.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module BMLConnect
+  module Models
+    # A read-only value object for a BML transaction (the v2 create/retrieve
+    # response). Named +TransactionRecord+, not +Transaction+, because the latter
+    # is already the v1 *request* builder that `transactions.create` depends on
+    # (research R9); renaming it would break a released method.
+    #
+    # Attributes are whitelisted: only the fields below are pulled from a BML
+    # response, so an unexpected key — a card number above all — cannot reach the
+    # object, a log line, or an audit record (Constitution I, FR-014).
+    class TransactionRecord
+      ATTRIBUTES = %i[
+        id created updated amount currency payCurrency merchantId
+        provider providerHistory state accountingState qr securityWord
+        canRefundIfConfirmed externalImport externalId localId paymentToken
+        history appVersion apiVersion redirectUrl costStructure
+        providerDisplayName paddedCardNumber customerId
+        customerReference localData pnr tokenizationDetails
+      ].freeze
+
+      # Fields that may carry the hosted payment link, in resolution order. `url`
+      # is the v1 field, absent from the v2 schema ([UNVERIFIED] #1); `redirectUrl`
+      # and `qr.url` are the documented v2 fields. `url` is deliberately NOT in
+      # ATTRIBUTES: the hosted payment page is a completion secret (FR-015), so it
+      # is never whitelisted, never in #to_h, and never in #inspect. It is
+      # reachable only through the explicit #payment_url accessor.
+      PAYMENT_URL_KEYS = %i[url redirectUrl].freeze
+
+      # Not whitelisted, for the same reason `url` is not: it completes a
+      # payment. Reachable only through #next_action.
+      CHALLENGE_KEY = :nextAction
+
+      # Fields in which BML reports what it DID about tokenization, as opposed
+      # to +tokenizationDetails+, which is the request WE sent and which BML
+      # echoes back — an echo says only that we asked. `tokenize` and
+      # `tokenizationMethod` are the documented Transaction fields; the rest
+      # were observed on live UAT notifications (2026-10-21) and appear in no
+      # published schema.
+      #
+      # Whitelisted separately and reachable only through #tokenization_report:
+      # they exist to be logged while diagnosing a card that was not stored, so
+      # they do not belong in #to_h or #inspect, and keeping them a whitelist
+      # preserves the rule that no unexpected key can reach a log line.
+      TOKENIZATION_FIELDS = %i[
+        tokenize tokenizationMethod tokenisationStatus tokenizationStatus
+        token clientSideTokenId initiator
+      ].freeze
+
+      ATTRIBUTES.each { |attribute| attr_reader attribute }
+
+      def initialize(data = {})
+        @source = normalize(data || {})
+        ATTRIBUTES.each do |attribute|
+          instance_variable_set("@#{attribute}", @source[attribute])
+        end
+      end
+
+      # The hosted payment URL to send the cardholder to. Reads the first present
+      # of `url`, `redirectUrl`, `qr.url`. RAISES rather than returning nil when
+      # none is present: a nil here would surface as a blank redirect in checkout,
+      # a silent failure in a money path (research R7). Resolving which field is
+      # authoritative on v2 is [UNVERIFIED] #1 (T021).
+      def payment_url
+        candidate = PAYMENT_URL_KEYS.map { |key| @source[key] }.find { |value| !blank?(value) }
+        candidate = qr_url if blank?(candidate)
+
+        if blank?(candidate)
+          raise UnverifiedFieldError,
+                "no hosted payment URL present in the transaction response " \
+                "(see contracts/bml-remote.md [UNVERIFIED] #1)"
+        end
+
+        candidate
+      end
+
+      # BML's Transaction schema: "Returns a URL when 3DS authentication is
+      # required; this URL must be opened to complete the 3DS challenge."
+      def next_action
+        presence(@source[CHALLENGE_KEY])
+      end
+
+      # Whether the gateway kept the card. It echoes `tokenizationDetails` back
+      # with the outcome, which is the only field that says so.
+      #
+      # NOT `paymentToken`: that is the acquirer's authorisation code — the
+      # trailing six digits of `externalId` — and is present on any authorised
+      # payment, tokenized or not (observed in UAT 2026-10-21).
+      def tokenized?
+        tokenization_detail("tokenize") == true
+      end
+
+      # The token this transaction created, as listed under the customer.
+      # `tokenId` and `tokenObjectId` carry the same value; both are read so a
+      # response that drops one still resolves.
+      def stored_token_id
+        return nil unless tokenized?
+
+        id = tokenization_detail("tokenId")
+        blank?(id) ? presence(tokenization_detail("tokenObjectId")) : id
+      end
+
+      # What the gateway said about tokenization, for a log line. Present keys
+      # only: an empty hash means BML reported nothing at all about the card,
+      # which is itself the answer when a tokenizing transaction stored none.
+      #
+      # Every string is scrubbed, because these fields are undocumented and a
+      # diagnostic must not be the one place a card number reaches a log.
+      def tokenization_report
+        report = TOKENIZATION_FIELDS.each_with_object({}) do |key, hash|
+          value = @source[key]
+          hash[key] = value.is_a?(String) ? Masking.scrub(value) : value unless blank?(value)
+        end
+        report[:tokenizationDetails] = scrub_details if tokenizationDetails.respond_to?(:each_pair)
+        report
+      end
+
+      # Whitelisted view. The hosted payment `url` is never included (FR-015).
+      def to_h
+        ATTRIBUTES.each_with_object({}) do |attribute, hash|
+          hash[attribute] = public_send(attribute)
+        end
+      end
+
+      def ==(other)
+        other.is_a?(TransactionRecord) && to_h == other.to_h
+      end
+      alias eql? ==
+
+      def hash
+        to_h.hash
+      end
+
+      # Limited to the whitelist, so a record is always safe to log — the hosted
+      # payment `url` never appears here.
+      def inspect
+        present = to_h.reject { |_, value| value.nil? }
+        "#<BMLConnect::Models::TransactionRecord #{present.inspect}>"
+      end
+
+      private
+
+      def tokenization_detail(key)
+        details = tokenizationDetails
+        return nil unless details.respond_to?(:[])
+
+        details[key].nil? ? details[key.to_sym] : details[key]
+      end
+
+      def scrub_details
+        tokenizationDetails.each_with_object({}) do |(key, value), hash|
+          hash[key.to_sym] = value.is_a?(String) ? Masking.scrub(value) : value
+        end
+      end
+
+      def presence(value)
+        blank?(value) ? nil : value
+      end
+
+      def qr_url
+        return nil unless qr.is_a?(Hash)
+
+        qr[:url] || qr["url"]
+      end
+
+      # Symbol-first access with a string fallback, over every key we might read
+      # (whitelist, plus the payment-URL candidates and the tokenization
+      # diagnostics).
+      def normalize(source)
+        keys = ATTRIBUTES + PAYMENT_URL_KEYS + TOKENIZATION_FIELDS + [CHALLENGE_KEY]
+        keys.each_with_object({}) do |key, hash|
+          hash[key] = source.key?(key) ? source[key] : source[key.to_s]
+        end
+      end
+
+      def blank?(value)
+        value.nil? || (value.is_a?(String) && value.strip.empty?)
+      end
+    end
+  end
+end

data/lib/bml_connect/models.rb

@@ -1,6 +1,13 @@
 # frozen_string_literal: true
 
 require 'bml_connect/models/transaction'
+require 'bml_connect/models/transaction_record'
+require 'bml_connect/models/tokenization_details'
+require 'bml_connect/models/customer'
+require 'bml_connect/models/customer_list'
+require 'bml_connect/models/token'
+require 'bml_connect/models/token_list'
+require "bml_connect/models/status_change_result"
 
 module BMLConnect
   module Models