bml_connect 0.2.0 → 0.3.0

data/lib/bml_connect/client.rb

@@ -3,6 +3,7 @@
 require 'faraday'
 require 'faraday_middleware'
 require 'deep_merge/rails_compat'
+require 'logger'
 
 module BMLConnect
   class Client
@@ -12,16 +13,62 @@ module BMLConnect
     BML_SANDBOX_ENDPOINT = "https://api.uat.merchants.bankofmaldives.com.mv/public/"
     BML_PRODUCTION_ENDPOINT = "https://api.merchants.bankofmaldives.com.mv/public/"
 
-    attr_reader(:api_key, :http_client, :transactions)
+    DEFAULT_TIMEOUT = 30
+    DEFAULT_MAX_RETRIES = 2
+    DEFAULT_RETRY_BACKOFF = 0.5
+
+    # Seconds to wait before the webhook handler's single re-check (feature 005,
+    # FR-010b). Spent INSIDE the caller's request, so an endpoint whose own
+    # response deadline is at or below this MUST set it to 0, which disables the
+    # re-check entirely. A judgment, not an observed figure: see
+    # specs/005-webhook-handler/contracts/bml-remote.md [UNVERIFIED] #4.
+    DEFAULT_WEBHOOK_RECHECK_DELAY = 3
+
+    attr_reader(:api_key, :app_id, :mode, :http_client, :transactions, :logger,
+                :webhook_secret, :webhook_recheck_delay)
+    attr_accessor(:timeout, :max_retries, :retry_backoff)
 
     def initialize(api_key: nil, app_id: nil, mode: nil, options: {})
       @api_key = api_key || (defined?(BML_API_KEY) ? BML_API_KEY : 'not-set')
       @app_id = app_id || (defined?(BML_APP_ID) ? BML_APP_ID : 'not-set')
       @mode = mode || (defined?(BML_MODE) ? BML_MODE : 'production')
-      @http_client = initialize_http_client(options)
+
+      # Pull the customers-resource knobs out of options before the rest is
+      # handed to Faraday, which would reject unknown keys.
+      opts = options.dup
+      @logger = pull_option(opts, :logger) { default_logger }
+      @timeout = pull_option(opts, :timeout) { DEFAULT_TIMEOUT }
+      @max_retries = pull_option(opts, :max_retries) { DEFAULT_MAX_RETRIES }
+      @retry_backoff = pull_option(opts, :retry_backoff) { DEFAULT_RETRY_BACKOFF }
+
+      # Webhook-handler knobs (feature 005). Pulled out for the same reason as the
+      # four above: Faraday rejects keys it does not know. webhook_secret is
+      # configuration supplied by the integrator (typically from the environment)
+      # and MUST NEVER be hardcoded (FR-012).
+      @webhook_secret = pull_option(opts, :webhook_secret) { nil }
+      @webhook_recheck_delay = pull_option(opts, :webhook_recheck_delay) { DEFAULT_WEBHOOK_RECHECK_DELAY }
+
+      @http_client = initialize_http_client(opts)
       @transactions = Transactions.new(self)
     end
 
+    # Memoized customers resource, bound to this client's mode and credentials.
+    def customers
+      @customers ||= Customers.new(self)
+    end
+
+    # Memoized stored-card tokens resource, bound to this client's mode and
+    # credentials. Read-and-delete only — see BMLConnect::Tokens.
+    def tokens
+      @tokens ||= Tokens.new(self)
+    end
+
+    # Memoized inbound notification handler, bound to this client's mode,
+    # credentials, secret and re-check delay. See BMLConnect::Webhooks.
+    def webhooks
+      @webhooks ||= Webhooks.new(self)
+    end
+
     def base_url
       @mode == 'production' ? BML_PRODUCTION_ENDPOINT : BML_SANDBOX_ENDPOINT
     end
@@ -44,6 +91,21 @@ module BMLConnect
     end
 
     private
+
+    # Take +key+ out of the options hash (so Faraday never sees it) and fall back
+    # to the block when the caller did not supply it. An explicit nil is honored.
+    def pull_option(opts, key)
+      opts.key?(key) ? opts.delete(key) : yield
+    end
+
+    # Default audit/diagnostic logger. Emits masked structured lines to stdout;
+    # integrators can inject their own via `options: { logger: ... }`.
+    def default_logger
+      logger = Logger.new($stdout)
+      logger.progname = 'bml_connect'
+      logger
+    end
+
     def initialize_http_client(options)
       defaults = {
         url: base_url,

data/lib/bml_connect/customers.rb

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+
+module BMLConnect
+  # The customers resource: create, retrieve, list, partial-update, archive, and
+  # charge a stored card under the /public-customers path family.
+  #
+  # Reached through a configured client as `client.customers`, mirroring the way
+  # `client.transactions` is already exposed. Unlike transactions (which return
+  # raw Faraday responses), this resource returns whitelisted value objects and
+  # raises the library's error hierarchy on failure.
+  #
+  # `#charge` (feature 004) lives here because its endpoint is
+  # `POST /public-customers/charge` — the customers path family this resource
+  # already owns (FR-001, research R8). It is the only money-moving method on the
+  # resource and is deliberately asymmetric with the others: it never
+  # auto-retries and it audits failures as well as successes.
+  class Customers < Resource
+    PATH = "/public-customers"
+
+    # Fields BML accepts on create (per contracts/bml-remote.md). `currency` and
+    # `paymentDue` are NOT here — they are update-only.
+    CREATE_FIELDS = %i[
+      name email billingEmail billingAddress1 billingAddress2 billingCity
+      billingCountry billingPostCode customerGroup invoicePrefix
+      taxInformation taxId
+    ].freeze
+
+    # Fields BML accepts on update. `customerGroup` is NOT here (create-only);
+    # `currency` and `paymentDue` are (update-only).
+    UPDATE_FIELDS = %i[
+      name email billingEmail billingAddress1 billingAddress2 billingCity
+      billingCountry billingPostCode currency paymentDue invoicePrefix
+      taxInformation taxId
+    ].freeze
+
+    # Fields that get the lightweight email shape check (2026-09-08 clarification).
+    EMAIL_FIELDS = %i[email billingEmail].freeze
+
+    # Create a customer. Requires `name` and `email`; accepts any documented
+    # optional field. Returns a Models::Customer carrying the BML-assigned id.
+    def create(details, actor: nil)
+      attributes = symbolize(details)
+      require_present!(attributes, :name)
+      require_present!(attributes, :email)
+      validate_email_shape!(attributes)
+      screen_for_pan!(attributes)
+      screen_actor!(actor)
+
+      body = attributes.select { |key, _| CREATE_FIELDS.include?(key) }
+      response = request(:post, PATH, body: body)
+      customer = Models::Customer.new(response.body)
+      audit(:create, actor: actor, subject: { customer_id: customer.id })
+      customer
+    end
+
+    # Retrieve a single customer by id. Not audited (read).
+    def retrieve(customer_id, actor: nil)
+      require_id!(customer_id)
+      screen_actor!(actor)
+
+      response = request(:get, "#{PATH}/#{customer_id}")
+      Models::Customer.new(response.body)
+    end
+
+    # List customers under the company. No page parameters are sent — the
+    # contract documents none (research R4). Not audited (read).
+    def list(actor: nil)
+      screen_actor!(actor)
+
+      response = request(:get, PATH)
+      Models::CustomerList.new(response.body)
+    end
+
+    # Partially update a customer. Sends only the keys supplied; never
+    # serializes an unset field as null. Rejects an empty change set locally.
+    def update(customer_id, changes, actor: nil)
+      require_id!(customer_id)
+      attributes = symbolize(changes)
+      raise ValidationError.new("no changes supplied", field: :changes) if attributes.empty?
+
+      validate_email_shape!(attributes)
+      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, "#{PATH}/#{customer_id}", body: body)
+      customer = Models::Customer.new(response.body)
+      audit(:update, actor: actor, subject: { customer_id: customer_id })
+      customer
+    end
+
+    # Archive (soft-delete) a customer. Named `archive`, not `delete`, because
+    # BML retains the record with `deleted: true`. Returns true on 204.
+    def archive(customer_id, actor: nil)
+      require_id!(customer_id)
+      screen_actor!(actor)
+
+      request(:delete, "#{PATH}/#{customer_id}")
+      audit(:archive, actor: actor, subject: { customer_id: customer_id })
+      true
+    end
+
+    # Charge a stored card against an already-created transaction — a
+    # merchant-initiated payment with no cardholder present. Posts the three-key
+    # body to `"#{PATH}/charge"` (POST /public-customers/charge). All three ids
+    # are REQUIRED and validated locally; a missing or blank one is rejected by
+    # name with NO remote call (FR-002). The charge carries no `amount` — the
+    # named transaction supplies it (FR-003); to bill a different amount, create
+    # a different transaction.
+    #
+    # NEVER auto-retried (FR-004): the charge schema carries no idempotency key,
+    # so a retry could take payment twice. Exactly one attempt is made. A timeout
+    # or transport failure raises AvailabilityError whose message names the
+    # `transaction_id` (FR-005) — the only safe recovery is to retrieve the
+    # transaction and reconcile, never to re-charge blindly.
+    #
+    # A returned TransactionRecord is a BUSINESS outcome (BML answered); a raised
+    # error is a TRANSPORT or VALIDATION outcome. The two are never converted
+    # into each other (FR-007). `state` is passed through verbatim. Every charge
+    # — success or failure — emits an audit record (FR-010/FR-011); no card data
+    # ever enters it (FR-008). The charge is applied in the environment the
+    # client is configured for (FR-012), since it rides the same transport.
+    #
+    # `token_id` expects the stored card's `Token#id` — the value used as the
+    # tokenId path parameter in `client.tokens.retrieve`. This is an inference
+    # from consistent path-parameter naming, NOT yet confirmed against a live
+    # environment (contracts/bml-remote.md [UNVERIFIED] #1 / task T001). This
+    # method MUST NOT be relied on in production until it is confirmed (FR-013).
+    def charge(customer_id:, transaction_id:, token_id:, actor: nil)
+      subject = { customer_id: customer_id, transaction_id: transaction_id, token_id: token_id }
+
+      validate_charge!(subject, actor)
+      response = post_charge(subject, actor)
+
+      record = Models::TransactionRecord.new(response.body)
+      charge_audit(actor, subject.merge(state: record.state), :success)
+      record
+    end
+
+    private
+
+    # Local, pre-remote validation for a charge. A failure is audited (FR-011)
+    # and re-raised with NO remote call made (FR-002, US1 scenario 2).
+    def validate_charge!(subject, actor)
+      require_charge_field!(subject[:customer_id], :customer_id)
+      require_charge_field!(subject[:transaction_id], :transaction_id)
+      require_charge_field!(subject[:token_id], :token_id)
+      screen_for_pan!(subject)
+      screen_actor!(actor)
+    rescue ValidationError
+      charge_audit(actor, subject, :validation_error)
+      raise
+    end
+
+    # The single, never-retried remote attempt. Each failure mode is audited
+    # before the error is re-raised so a raise never loses the trail (FR-011).
+    def post_charge(subject, actor)
+      body = {
+        customerId: subject[:customer_id],
+        transactionId: subject[:transaction_id],
+        tokenId: subject[:token_id]
+      }
+      request(:post, "#{PATH}/charge", body: body, retries: false)
+    rescue AvailabilityError => e
+      charge_audit(actor, subject, :error)
+      raise AvailabilityError, reconcile_message(e.message, subject[:transaction_id])
+    rescue ValidationError
+      # A non-2xx business rejection of the charge itself (400/422).
+      charge_audit(actor, subject, :declined)
+      raise
+    rescue Error
+      # Any other mapped failure (auth, not-found, rate limit): the charge did
+      # not go through, but this is not a card decline.
+      charge_audit(actor, subject, :error)
+      raise
+    end
+
+    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)
+      value = attributes[field]
+      return unless blank?(value)
+
+      raise ValidationError.new("#{field} is required", field: field)
+    end
+
+    def require_id!(customer_id)
+      return unless blank?(customer_id)
+
+      raise ValidationError.new("customer_id is required", field: :customer_id)
+    end
+
+    # Per-field presence check for the charge, so the error names exactly which
+    # of the three required ids is missing (FR-002).
+    def require_charge_field!(value, field)
+      return unless blank?(value)
+
+      raise ValidationError.new("#{field} is required", field: field)
+    end
+
+    # Charge auditing is deliberately separate from the shared #audit helper,
+    # which hardcodes outcome: :success. A charge audits failures too (FR-011),
+    # so the real outcome (:success, :declined, :validation_error, :error) is
+    # passed through. Card data is scrubbed by Audit before the line is written.
+    def charge_audit(actor, subject, outcome)
+      Audit.emit_event(client, action: :charge, actor: actor, outcome: outcome, subject: subject)
+    end
+
+    # An AvailabilityError from a charge MUST name the transaction so the caller
+    # can reconcile by retrieving it — the outcome is genuinely unknown (FR-005).
+    def reconcile_message(original, transaction_id)
+      "#{original} (charge outcome for transactionId #{transaction_id} is unknown; " \
+        "retrieve the transaction to reconcile — do NOT re-charge blindly)"
+    end
+
+    # Lightweight shape check only (2026-09-08 clarification / research R11):
+    # the value must contain an @ and a domain part. Not strict RFC validation —
+    # BML remains the authority on acceptance beyond this basic shape.
+    def validate_email_shape!(attributes)
+      EMAIL_FIELDS.each do |field|
+        next unless attributes.key?(field)
+
+        value = attributes[field]
+        next if value.nil?
+        next if valid_email_shape?(value)
+
+        raise ValidationError.new("#{field} is not a valid email address", field: field)
+      end
+    end
+
+    def valid_email_shape?(value)
+      return false unless value.is_a?(String)
+
+      !(value =~ /\A[^@\s]+@[^@\s]+\.[^@\s]+\z/).nil?
+    end
+
+    # Screen every caller-supplied string value for card data (2026-09-08
+    # clarification): no field is exempt.
+    def screen_for_pan!(attributes)
+      attributes.each do |field, value|
+        next unless value.is_a?(String)
+        next unless Masking.looks_like_pan?(value)
+
+        raise ValidationError.new("#{field} contains data that looks like a card number", field: field)
+      end
+    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/errors.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module BMLConnect
+  # Base error for the library. Reopened here (also declared in bml_connect.rb)
+  # so this file is self-contained regardless of require order.
+  class Error < StandardError
+    # The HTTP status a host application SHOULD return to BML when this error
+    # ends the handling of an inbound notification (feature 005, FR-016a).
+    #
+    # It is ADVICE, not control: the library never writes a response and does not
+    # require the caller to honor it (FR-016b). The webhook path tags the error
+    # object before it propagates; nil everywhere else, so no existing raise site
+    # changes behavior. Carried on the base class rather than as a parallel
+    # hierarchy of status-specific classes, which would have broken callers that
+    # match on AvailabilityError.
+    attr_accessor :advisory_http_status
+  end
+
+  # Raised for local validation failures (before any remote call) and for
+  # BML 400/422 responses. Carries the offending field where known.
+  class ValidationError < Error
+    attr_reader :field
+
+    def initialize(message = nil, field: nil)
+      @field = field
+      super(message)
+    end
+  end
+
+  # 401/403 — missing, invalid, or unprovisioned credentials.
+  class AuthenticationError < Error; end
+
+  # 404 — no customer matches the given id.
+  class NotFoundError < Error; end
+
+  # 409 — conflicting state. Carries the parsed response body for inspection.
+  class ConflictError < Error
+    attr_reader :body
+
+    def initialize(message = nil, body: nil)
+      @body = body
+      super(message)
+    end
+  end
+
+  # 429 — rate limited. Carries the Retry-After hint when BML supplies one.
+  class RateLimitError < Error
+    attr_reader :retry_after
+
+    def initialize(message = nil, retry_after: nil)
+      @retry_after = retry_after
+      super(message)
+    end
+  end
+
+  # Timeout, connection failure, 408, or 5xx after bounded retries. Distinct
+  # from every other error so callers can safely retry later.
+  class AvailabilityError < Error; end
+
+  # Raised when an inbound notification fails the optional shared-secret check
+  # (feature 005, FR-009a). A DISTINCT class rather than a ValidationError with a
+  # field, because FR-016/SC-008 require a failed secret check to be observably
+  # distinguishable from a malformed body, and separating a security rejection
+  # only by a `field:` value is too weak for something operators alert on.
+  #
+  # The secret gates SPEND, not trust: this error means no retrieve was spent, and
+  # a matching secret never causes a payload to be believed (FR-009b).
+  class WebhookRejectedError < Error; end
+
+  # Raised when a value the caller asks for depends on a response field that is
+  # not yet verified against a live BML environment. Specifically:
+  # TransactionRecord#payment_url raises this when no hosted-payment-URL field is
+  # present, rather than returning nil and sending a cardholder to a blank page
+  # (contracts/bml-remote.md [UNVERIFIED] #1; research R7).
+  class UnverifiedFieldError < Error; end
+end

data/lib/bml_connect/masking.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module BMLConnect
+  # Detects and redacts card-number-like data. This library never has a
+  # legitimate reason to carry a PAN, so any value that looks like one is
+  # rejected on input and scrubbed from any log output.
+  #
+  # Ported from the retired bml_tokenization gem, whose masking was the one
+  # part of its engineering that was sound.
+  module Masking
+    # 13–19 digits, allowing a single space or dash between digits (the common
+    # ways a PAN gets pasted). Deliberately broad; the Luhn check below removes
+    # the false positives a bare length match would produce.
+    PAN_PATTERN = /\d(?:[ -]?\d){12,18}/.freeze
+
+    REDACTION = "[FILTERED]"
+
+    module_function
+
+    # True when +value+ contains a substring that both matches the PAN shape
+    # and passes the Luhn checksum. The Luhn gate keeps ordinary long numbers
+    # (tax ids, references) from being misread as card numbers.
+    def looks_like_pan?(value)
+      return false unless value.is_a?(String)
+
+      value.scan(PAN_PATTERN).any? { |candidate| luhn_valid?(candidate.gsub(/[ -]/, "")) }
+    end
+
+    # Standard Luhn (mod-10) validation over a digit string.
+    def luhn_valid?(digits)
+      return false unless digits.length.between?(13, 19)
+
+      sum = 0
+      digits.reverse.each_char.each_with_index do |char, index|
+        n = char.to_i
+        if index.odd?
+          n *= 2
+          n -= 9 if n > 9
+        end
+        sum += n
+      end
+      (sum % 10).zero?
+    end
+
+    # Replace any PAN-like substring in +text+ with the redaction marker.
+    # Used to guarantee no card data survives into a log line.
+    def scrub(text)
+      return text unless text.is_a?(String)
+
+      text.gsub(PAN_PATTERN) do |candidate|
+        luhn_valid?(candidate.gsub(/[ -]/, "")) ? REDACTION : candidate
+      end
+    end
+  end
+end

data/lib/bml_connect/models/customer.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module BMLConnect
+  module Models
+    # A read-only value object for a BML customer.
+    #
+    # Attributes are whitelisted: only the fields below are pulled from a BML
+    # response, so an unexpected key (e.g. a card field BML should never return
+    # on a customer) cannot reach the object, a log line, or an audit record.
+    class Customer
+      ATTRIBUTES = %i[
+        id name email companyId currency customerGroupId deleted
+        billingEmail billingAddress1 billingAddress2 billingCity
+        billingCountry billingPostCode invoicePrefix taxInformation taxId
+        createdAt updatedAt
+      ].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
+
+      def to_h
+        ATTRIBUTES.each_with_object({}) do |attribute, hash|
+          hash[attribute] = public_send(attribute)
+        end
+      end
+
+      def ==(other)
+        other.is_a?(Customer) && to_h == other.to_h
+      end
+      alias eql? ==
+
+      def hash
+        to_h.hash
+      end
+
+      def inspect
+        present = to_h.reject { |_, value| value.nil? }
+        "#<BMLConnect::Models::Customer #{present.inspect}>"
+      end
+    end
+  end
+end

data/lib/bml_connect/models/customer_list.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module BMLConnect
+  module Models
+    # BML's list response: a { count, items } envelope, exposed as an
+    # Enumerable over Customer value objects.
+    #
+    # BML types `count` as a string in the published contract. Whether it
+    # arrives as "42" or 42 is unobserved (an [UNVERIFIED] marker), so the count
+    # is coerced to an Integer and falls back to the actual item count if the
+    # value is missing or non-numeric — it can never raise on a surprising type.
+    class CustomerList
+      include Enumerable
+
+      attr_reader :count, :items
+
+      def initialize(data = {})
+        source = data || {}
+        raw_items = source[:items] || source["items"] || []
+        @items = raw_items.map { |item| Customer.new(item) }
+        @count = coerce_count(source[:count] || source["count"])
+      end
+
+      def each(&block)
+        items.each(&block)
+      end
+
+      def size
+        items.size
+      end
+
+      def empty?
+        items.empty?
+      end
+
+      private
+
+      def coerce_count(raw)
+        Integer(raw)
+      rescue ArgumentError, TypeError
+        items.size
+      end
+    end
+  end
+end