wfirma 0.1.0

data/lib/wfirma/drivers/fake.rb

@@ -0,0 +1,254 @@
+module Wfirma
+  module Drivers
+    # Dev/test driver - no HTTP at all. Returns realistic wFirma-shaped
+    # responses so the full payload-mapping and Result-parsing code paths
+    # run exactly as in production.
+    #
+    # It keeps an in-memory contractor catalogue, so the find -> add/edit flow
+    # behaves in dev the way it does against the real CRM: the same customer
+    # resolves to one record across invoices.
+    #
+    # Failure simulation:
+    # - Magic contractor NIPs (Stripe-test-card style) drive scenarios from
+    #   the UI or system tests; all-zeros NIPs are checksum-invalid so no
+    #   real customer can trigger them. They apply to any call carrying a
+    #   contractor (invoices/add, contractors/add, contractors/edit).
+    # - Polish postal codes are validated the way wFirma validates them, so
+    #   the malformed-zip rejection can be exercised without a network.
+    # - fail_next!/fail_always! for unit tests and console; these apply to
+    #   every action, download included.
+    class Fake
+      include DeepDup
+
+      Request = Struct.new(:module_name, :action, :payload, :params, :id)
+
+      MAGIC_NIPS = {
+        "0000000000" => :validation_error,
+        "0000000001" => :auth_error,
+        "0000000002" => :connection_error
+      }.freeze
+
+      PL_ZIP = /\A\d{2}-\d{3}\z/
+
+      # wFirma accepts Polish postal codes only as XX-XXX and rejects the
+      # whole contractor otherwise. Message and field taken from a rejection
+      # observed in the reference integration.
+      ZIP_ERROR = { "field" => "zip", "message" => "Niepoprawny format kodu pocztowego." }.freeze
+
+      MAGIC_NIP_ERROR = {
+        "field" => "nip",
+        "message" => "Symulowany błąd walidacji (magic NIP 0000000000)"
+      }.freeze
+
+      # Smallest thing that still passes a "%PDF-" magic-bytes check.
+      FAKE_PDF = "%PDF-1.4\n% Wfirma::Drivers::Fake\n%%EOF\n".b.freeze
+
+      attr_reader :requests
+
+      def initialize
+        reset!
+      end
+
+      def reset!
+        @requests = []
+        @next_id = 0
+        @next_contractor_id = 0
+        @fail_next = nil
+        @fail_always = nil
+        @contractors = Catalogue.new
+      end
+
+      def fail_next!(code: "ERROR", errors: [])
+        @fail_next = { code: code, errors: errors }
+      end
+
+      def fail_always!(code: "ERROR", errors: [])
+        @fail_always = { code: code, errors: errors }
+      end
+
+      def call(module_name, action, payload, params = {}, id = nil)
+        record(module_name, action, payload, params, id)
+
+        failure = consume_failure
+        return simulate_failure(failure, payload) if failure
+
+        raise_magic_nip_error(payload)
+        rejection = contractor_rejection(payload)
+        return rejection if rejection
+
+        return contractors_response(action, payload, id) if module_name == "contractors"
+
+        ok_response(payload)
+      end
+
+      # Mirrors Drivers::Http#download: raw bytes on success, an exception
+      # otherwise - a fake PDF is enough to exercise storage/serving code.
+      def download(module_name, action, payload, params = {}, id = nil)
+        record(module_name, action, payload, params, id)
+
+        failure = consume_failure
+        simulate_download_failure(failure) if failure
+
+        FAKE_PDF.dup
+      end
+
+      private
+
+      def record(module_name, action, payload, params, id)
+        @requests << Request.new(module_name, action, deep_dup(payload), deep_dup(params), id)
+      end
+
+      def consume_failure
+        failure = @fail_next || @fail_always
+        @fail_next = nil
+        failure
+      end
+
+      # The buyer, wherever this payload carries them.
+      def contractor_from(payload)
+        inline = invoice_from(payload)["contractor"]
+        return inline if inline.is_a?(Hash)
+
+        own = payload.dig("contractors", "contractor") if payload.is_a?(Hash)
+        own.is_a?(Hash) ? own : {}
+      end
+
+      def raise_magic_nip_error(payload)
+        case MAGIC_NIPS[contractor_from(payload)["nip"].to_s]
+        when :auth_error
+          raise AuthError, "wFirma authentication failed (simulated by magic NIP 0000000001)"
+        when :connection_error
+          raise ConnectionError, "wFirma connection failed (simulated by magic NIP 0000000002)"
+        end
+      end
+
+      # Validation wFirma performs on write, in the order it would reject.
+      def contractor_rejection(payload)
+        contractor = contractor_from(payload)
+        return nil if contractor.empty?
+
+        if MAGIC_NIPS[contractor["nip"].to_s] == :validation_error
+          return validation_error_response(payload, [MAGIC_NIP_ERROR])
+        end
+
+        invalid_zip?(contractor) ? validation_error_response(payload, [ZIP_ERROR]) : nil
+      end
+
+      def invalid_zip?(contractor)
+        zip = contractor["zip"].to_s
+        country = contractor["country"].to_s
+        return false if zip.empty?
+        return false unless country.empty? || country.casecmp("PL").zero?
+
+        !zip.match?(PL_ZIP)
+      end
+
+      # An armed code that aborts the request raises here exactly as it does
+      # over HTTP, so arming one exercises the path production takes.
+      def armed_error(failure)
+        Status.error_for(failure[:code], message: "simulated", errors: failure[:errors])
+      end
+
+      def simulate_failure(failure, payload)
+        error = armed_error(failure)
+        raise error if error
+
+        nodes = failure[:errors].map { |message| { "message" => message } }
+        error_response(payload, nodes, code: failure[:code])
+      end
+
+      def simulate_download_failure(failure)
+        error = armed_error(failure)
+        raise error if error
+
+        raise ApiError.new(
+          "wFirma returned no PDF (simulated, status #{failure[:code]}): #{failure[:errors].join("; ")}",
+          status_code: failure[:code], errors: failure[:errors]
+        )
+      end
+
+      def contractors_response(action, payload, id)
+        case action
+        when "find" then found_contractors(payload)
+        when "add" then collection_response("contractors", "contractor", @contractors.add(contractor_from(payload)))
+        when "edit" then edited_contractor(id, contractor_from(payload))
+        else status_response("OK")
+        end
+      end
+
+      def found_contractors(payload)
+        condition = payload.dig("contractors", "parameters", "conditions", "condition") || {}
+        { "contractors" => @contractors.find(condition), "status" => { "code" => "OK" } }
+      end
+
+      def edited_contractor(id, attrs)
+        edited = @contractors.edit(id, attrs)
+        return status_response("NOT FOUND", message: "Nie znaleziono kontrahenta #{id}") unless edited
+
+        collection_response("contractors", "contractor", edited)
+      end
+
+      def ok_response(payload)
+        return status_response("OK") unless invoice_payload?(payload)
+
+        invoice = invoice_from(payload).merge(
+          "id" => (@next_id += 1),
+          "fullnumber" => "FV #{@next_id}/#{Time.now.year}"
+        )
+        collection_response("invoices", "invoice", invoice)
+      end
+
+      def error_response(payload, error_nodes, code: "ERROR")
+        unless invoice_payload?(payload)
+          messages = error_nodes.filter_map { |node| node["message"] }
+          return status_response(code, message: messages.join("; "))
+        end
+
+        invoice = invoice_from(payload).merge("errors" => wrap_errors(error_nodes))
+        collection_response("invoices", "invoice", invoice, code)
+      end
+
+      # Verified against the live API: wFirma reports a rejected buyer under
+      # the contractor that failed, not at the top of the document. Mirror
+      # that, so the Result parsing exercised in dev is the one production
+      # hits - on an invoice the errors nest under invoice.contractor, on a
+      # contractors call they sit on the contractor record itself.
+      def validation_error_response(payload, error_nodes, code: "ERROR")
+        contractor = contractor_from(payload).merge("errors" => wrap_errors(error_nodes))
+
+        if invoice_payload?(payload)
+          invoice = invoice_from(payload).merge("contractor" => contractor)
+          collection_response("invoices", "invoice", invoice, code)
+        else
+          collection_response("contractors", "contractor", contractor, code)
+        end
+      end
+
+      def wrap_errors(error_nodes)
+        error_nodes.map { |node| { "error" => node } }
+      end
+
+      def collection_response(collection, entity, record, code = "OK")
+        { collection => { "0" => { entity => record } },
+          "status" => { "code" => code } }
+      end
+
+      # Actions without a record body (invoices/send) answer with the bare
+      # status envelope, so there is nothing to echo back.
+      def status_response(code, message: nil)
+        status = { "code" => code }
+        status["message"] = message unless message.to_s.empty?
+        { "status" => status }
+      end
+
+      def invoice_payload?(payload)
+        payload.is_a?(Hash) && payload.dig("invoices", "invoice").is_a?(Hash)
+      end
+
+      def invoice_from(payload)
+        invoice = payload.dig("invoices", "invoice") if payload.is_a?(Hash)
+        invoice.is_a?(Hash) ? deep_dup(invoice) : {}
+      end
+    end
+  end
+end

data/lib/wfirma/drivers/http.rb

@@ -0,0 +1,111 @@
+require "net/http"
+require "uri"
+require "json"
+
+module Wfirma
+  module Drivers
+    # Real transport. POSTs JSON to api2.wfirma.pl with API Key auth
+    # headers (accessKey / secretKey / appKey) and parses the response.
+    class Http
+      DEFAULT_BASE_URL = "https://api2.wfirma.pl".freeze
+      PDF_MAGIC = "%PDF-".freeze
+
+      def initialize(access_key:, secret_key:, app_key:, company_id:,
+                     base_url: DEFAULT_BASE_URL, open_timeout: 5, read_timeout: 30)
+        @access_key = access_key
+        @secret_key = secret_key
+        @app_key = app_key
+        @company_id = company_id
+        @base_url = base_url
+        @open_timeout = open_timeout
+        @read_timeout = read_timeout
+      end
+
+      # id appends a record id to the path, as required by the per-record
+      # actions (invoices/send/123, invoices/download/123, invoices/get/123).
+      def call(module_name, action, payload, params = {}, id = nil)
+        uri = build_uri(module_name, action, params, id)
+        parse(perform(uri, payload))
+      end
+
+      # Binary actions (invoices/download) answer with the raw file; only
+      # failures come back as JSON. Returns the file bytes as a binary String.
+      def download(module_name, action, payload, params = {}, id = nil)
+        uri = build_uri(module_name, action, params, id)
+        response = perform(uri, payload, accept: "application/pdf")
+        body = response.body.to_s.dup.force_encoding(Encoding::BINARY)
+        return body if body.start_with?(PDF_MAGIC)
+
+        raise_download_error(body, response)
+      end
+
+      private
+
+      def build_uri(module_name, action, params, id = nil)
+        path = [module_name, action, id].compact.join("/")
+        uri = URI.parse("#{@base_url}/#{path}")
+        query = {
+          "inputFormat" => "json",
+          "outputFormat" => "json",
+          "company_id" => @company_id
+        }.merge(params)
+        uri.query = URI.encode_www_form(query)
+        uri
+      end
+
+      def perform(uri, payload, accept: "application/json")
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = @open_timeout
+        http.read_timeout = @read_timeout
+
+        request = Net::HTTP::Post.new(uri)
+        request["accessKey"] = @access_key
+        request["secretKey"] = @secret_key
+        request["appKey"] = @app_key
+        request["Content-Type"] = "application/json"
+        request["Accept"] = accept
+        request.body = JSON.generate(payload) if payload
+
+        http.request(request)
+      rescue Timeout::Error, SystemCallError, SocketError, IOError,
+             OpenSSL::SSL::SSLError => e
+        raise ConnectionError, "wFirma request failed: #{e.class}: #{e.message}"
+      end
+
+      def parse(response)
+        body = JSON.parse(response.body)
+        unless body.is_a?(Hash)
+          raise ConnectionError, "wFirma returned an unexpected JSON shape (HTTP #{response.code})"
+        end
+
+        error = Status.error_for(body.dig("status", "code"), message: body.dig("status", "message"))
+        raise error if error
+
+        body
+      rescue JSON::ParserError
+        raise ConnectionError, "wFirma returned a non-JSON response (HTTP #{response.code})"
+      end
+
+      def raise_download_error(body, response)
+        parsed = JSON.parse(body)
+        unless parsed.is_a?(Hash)
+          raise ConnectionError, "wFirma returned an unexpected JSON shape (HTTP #{response.code})"
+        end
+
+        result = Result.new(parsed)
+        error = Status.error_for(result.status_code, message: result.message, errors: result.errors)
+        raise error if error
+
+        # A record-level code (ERROR, NOT FOUND): the reason is on the record,
+        # but there is still no file to hand back.
+        raise ApiError.new(
+          "wFirma returned no PDF (status #{result.status_code || "?"}): #{result.errors.join("; ")}",
+          status_code: result.status_code, errors: result.errors
+        )
+      rescue JSON::ParserError
+        raise ConnectionError, "wFirma returned neither a PDF nor JSON (HTTP #{response.code})"
+      end
+    end
+  end
+end

data/lib/wfirma/errors.rb

@@ -0,0 +1,42 @@
+module Wfirma
+  class Error < StandardError; end
+
+  # Network failure, timeout, or a response that is not parseable at all.
+  class ConnectionError < Error; end
+
+  # A wFirma status code that aborts the request, and the answer a binary
+  # action (invoices/download) gives when it returns a JSON error instead of
+  # the file. Record-level outcomes flow into Result instead - see Status.
+  class ApiError < Error
+    attr_reader :status_code, :errors
+
+    def initialize(message, status_code: nil, errors: [])
+      super(message)
+      @status_code = status_code
+      @errors = errors
+    end
+  end
+
+  # AUTH, AUTH FAILED LIMIT WAIT 5 MINUTES. The keys are missing, wrong, or
+  # locked out after too many failed attempts.
+  class AuthError < ApiError; end
+
+  # ACCESS DENIED, DENIED SCOPE REQUESTED. The keys are accepted, but this
+  # account - or this OAuth scope - may not perform the action.
+  class AccessDeniedError < ApiError; end
+
+  # ACTION NOT FOUND, COMPANY ID REQUIRED, INPUT ERROR. The request itself is
+  # wrong; sending it again unchanged fails the same way.
+  class RequestError < ApiError; end
+
+  # TOTAL REQUESTS LIMIT EXCEEDED, TOTAL EXECUTION TIME LIMIT EXCEEDED. The
+  # limits move with wFirma's load, so this says back off, not stop.
+  class RateLimitError < ApiError; end
+
+  # OUT OF SERVICE, SNAPSHOT LOCK. wFirma is temporarily unavailable - an
+  # update, or a company restoring from backup - and will be back.
+  class ServiceUnavailableError < ApiError; end
+
+  # FATAL. An internal wFirma error; their docs say it should not happen.
+  class ServerError < ApiError; end
+end

data/lib/wfirma/invoices.rb

@@ -0,0 +1,96 @@
+module Wfirma
+  # Invoices resource. Maps a simple attrs hash to wFirma's invoices/add
+  # payload format and wraps the response in a Result.
+  class Invoices
+    KEY_MAP = {
+      payment_method: "paymentmethod",
+      payment_date: "paymentdate"
+    }.freeze
+
+    # Defaults for the download/send print options; see #pdf and #send_email.
+    PDF_OPTIONS = {
+      "page" => "invoice", "address" => 0, "leaflet" => 0, "duplicate" => 0
+    }.freeze
+    SEND_OPTIONS = {
+      "page" => "invoice", "leaflet" => 0, "duplicate" => 0
+    }.freeze
+
+    def initialize(client)
+      @client = client
+    end
+
+    # attrs: `{contractor: {...}, items: [{...}], payment_method: "transfer", ...}`
+    # draft: true creates a "normal_draft" document (no book number, not
+    # sent to KSeF) - the safe way to test against the real API.
+    def create(attrs, draft: false)
+      payload = { "invoices" => { "invoice" => build_invoice(attrs, draft: draft) } }
+      Result.new(@client.call("invoices", "add", payload))
+    end
+
+    # PDF printout of an invoice, returned as raw bytes (binary String).
+    # Raises Wfirma::ApiError when wFirma answers with an error instead.
+    # Options (all optional, PDF_OPTIONS otherwise):
+    #
+    #   page:      "invoice" (original), "invoicecopy" (copy), "all" (both)
+    #   address:   1 prints the buyer's address on the back of the original
+    #   leaflet:   1 adds a transfer form (transfer payments in PLN only)
+    #   duplicate: 1 marks the printout as a duplicate
+    def pdf(invoice_id, **options)
+      payload = parameters_payload(PDF_OPTIONS, options)
+      @client.download("invoices", "download", payload, {}, invoice_id)
+    end
+
+    # Asks wFirma to email the invoice PDF to the customer. Options:
+    #
+    #   email:            recipient; omitted falls back to the contractor record
+    #   subject: / body:  omitted falls back to wFirma's email template
+    #   page / leaflet / duplicate: as in #pdf
+    def send_email(invoice_id, **options)
+      payload = parameters_payload(SEND_OPTIONS, options)
+      Result.new(@client.call("invoices", "send", payload, {}, invoice_id))
+    end
+
+    private
+
+    def build_invoice(attrs, draft:)
+      invoice = { "type" => draft ? "normal_draft" : "normal" }
+      attrs.each do |key, value|
+        case key.to_sym
+        when :items
+          invoice["invoicecontents"] = build_invoicecontents(value)
+        when :contractor
+          invoice["contractor"] = stringify_keys(value)
+        else
+          invoice[KEY_MAP.fetch(key.to_sym, key.to_s)] = value
+        end
+      end
+      invoice
+    end
+
+    # wFirma requires line items as a numeric-string-keyed map:
+    # {"0" => {"invoicecontent" => {...}}, "1" => ...}
+    def build_invoicecontents(items)
+      items.each_with_index.to_h do |item, index|
+        [index.to_s, { "invoicecontent" => stringify_keys(item) }]
+      end
+    end
+
+    # The download/send actions take their options as repeated <parameter>
+    # nodes. Over JSON those must be a numeric-string-keyed map, the same
+    # shape as invoicecontents - given a plain array wFirma silently ignores
+    # the options and falls back to its defaults. Nil options are dropped so
+    # wFirma applies its own default for them.
+    def parameters_payload(defaults, options)
+      parameters = defaults.merge(stringify_keys(options))
+                           .reject { |_name, value| value.nil? }
+                           .each_with_index.to_h do |(name, value), index|
+        [index.to_s, { "parameter" => { "name" => name.to_s, "value" => value.to_s } }]
+      end
+      { "invoices" => { "parameters" => parameters } }
+    end
+
+    def stringify_keys(hash)
+      hash.to_h { |key, value| [key.to_s, value] }
+    end
+  end
+end

data/lib/wfirma/result.rb

@@ -0,0 +1,122 @@
+module Wfirma
+  # Wraps a parsed wFirma API response. wFirma answers HTTP 200 even for
+  # failures - the real outcome lives in status.code, and validation errors
+  # are nested inside the returned objects.
+  #
+  # Responses are shaped <collection>.<index>.<entity>, e.g. invoices.0.invoice
+  # or contractors.0.contractor.
+  #
+  # collection/entity are positional on purpose: `Result.new("status" => …)`
+  # with a brace-less hash would otherwise be parsed as keyword arguments.
+  class Result
+    attr_reader :raw
+
+    def initialize(raw, collection = "invoices", entity = "invoice")
+      @raw = raw || {}
+      @collection = collection
+      @entity = entity
+    end
+
+    def success?
+      status_code == "OK"
+    end
+
+    def status_code
+      dig_hash(raw, "status", "code")
+    end
+
+    # The object wFirma returned, from <collection>.<index>.<entity>.
+    def record
+      entries = raw[@collection]
+      return nil unless entries.is_a?(Hash)
+
+      entries.each do |key, value|
+        next unless key.to_s.match?(/\A\d+\z/) && value.is_a?(Hash)
+
+        found = value[@entity]
+        return found if found.is_a?(Hash)
+      end
+      nil
+    end
+
+    def record_id
+      id = record && record["id"]
+      id&.to_i
+    end
+
+    alias invoice record
+    alias invoice_id record_id
+
+    # Top-level failure text. Actions that answer without a record body
+    # (invoices/send) report the reason here rather than as field errors.
+    def message
+      dig_hash(raw, "status", "message")
+    end
+
+    def errors
+      @errors ||= field_errors.empty? ? Array(message_error) : field_errors
+    end
+
+    private
+
+    def field_errors
+      @field_errors ||= collect_errors(record, [])
+    end
+
+    # wFirma attaches validation errors to whichever object failed, which is
+    # often a nested one rather than the record itself: a rejected contractor
+    # on an invoice reports under invoice.contractor.errors, a bad line item
+    # under its own invoicecontent. Walk the whole record so those are not
+    # read as "no errors", and prefix each field with where it was found.
+    def collect_errors(node, path)
+      case node
+      when Array
+        node.each_with_index.flat_map { |item, index| collect_errors(item, path + [index.to_s]) }
+      when Hash
+        node.flat_map do |key, value|
+          next error_nodes(value).filter_map { |detail| format_error(detail, path) } if key == "errors"
+
+          collect_errors(value, path + [key.to_s])
+        end
+      else
+        []
+      end
+    end
+
+    def format_error(node, path)
+      node_message = node["message"]
+      return unless node_message
+
+      field = (path + [node["field"]]).compact.reject(&:empty?).join(".")
+      field.empty? ? node_message.to_s : "#{field}: #{node_message}"
+    end
+
+    def message_error
+      message if message.is_a?(String) && !message.empty?
+    end
+
+    # wFirma nests errors in several shapes: an array of {"error" => {...}}
+    # nodes, a single {"error" => {...}} hash, or a numeric-keyed hash of
+    # them. Normalize all of these to a flat array of error-detail hashes.
+    def error_nodes(container)
+      case container
+      when Array
+        container.flat_map { |item| error_nodes(item) }
+      when Hash
+        if container.key?("error")
+          error_nodes(container["error"])
+        elsif container.keys.all? { |key| key.to_s.match?(/\A\d+\z/) }
+          container.values.flat_map { |item| error_nodes(item) }
+        else
+          [container]
+        end
+      else
+        []
+      end
+    end
+
+    def dig_hash(hash, *keys)
+      hash.is_a?(Hash) ? hash.dig(*keys) : nil
+    end
+  end
+end

data/lib/wfirma/status.rb

@@ -0,0 +1,60 @@
+module Wfirma
+  # wFirma answers HTTP 200 for everything, so the top-level status code is
+  # the real outcome. This is the whole documented set (doc.wfirma.pl,
+  # "Komunikaty błędów"), split by what the caller can do about it.
+  #
+  # A code that describes the *record* reaches the caller as a Result. A code
+  # that aborts the *request* is raised: there is no record to report on, so a
+  # Result would carry an empty error list and the reason would be lost.
+  module Status
+    OK = "OK".freeze
+
+    # NOT FOUND is grouped with the aborting codes in wFirma's docs, but it
+    # answers a record the caller named - an edit of an id that is gone, a
+    # lookup that matched nothing - so it is an outcome, not a transport
+    # failure, and it stays a Result.
+    RESULT_CODES = [OK, "ERROR", "NOT FOUND"].freeze
+
+    ABORTING = {
+      "AUTH" => [AuthError, "authentication failed - check accessKey/secretKey/appKey"],
+      "AUTH FAILED LIMIT WAIT 5 MINUTES" =>
+        [AuthError, "too many failed authentication attempts - wait 5 minutes"],
+      "ACCESS DENIED" => [AccessDeniedError, "this account may not perform that action"],
+      "DENIED SCOPE REQUESTED" =>
+        [AccessDeniedError, "the OAuth authorization does not cover that scope"],
+      "ACTION NOT FOUND" => [RequestError, "no such action - check the module and action names"],
+      "COMPANY ID REQUIRED" =>
+        [RequestError, "the account holds several companies - pass company_id"],
+      "INPUT ERROR" => [RequestError, "wFirma could not read the request body"],
+      "TOTAL REQUESTS LIMIT EXCEEDED" => [RateLimitError, "request limit exceeded"],
+      "TOTAL EXECUTION TIME LIMIT EXCEEDED" => [RateLimitError, "execution time limit exceeded"],
+      "OUT OF SERVICE" => [ServiceUnavailableError, "the API is temporarily out of service"],
+      "SNAPSHOT LOCK" => [ServiceUnavailableError, "the company is being restored from a backup"],
+      "FATAL" => [ServerError, "internal wFirma error"]
+    }.freeze
+
+    UNKNOWN = [ApiError, "unrecognised status code"].freeze
+
+    module_function
+
+    # The exception for this status code, or nil when the code belongs in a
+    # Result. An unrecognised code is raised rather than passed through: this
+    # exists so a failure is never silent, and wFirma may add codes.
+    def error_for(code, message: nil, errors: [])
+      code = code.to_s
+      return nil if RESULT_CODES.include?(code)
+
+      error_class, explanation = ABORTING.fetch(code, UNKNOWN)
+      error_class.new(
+        message_for(code, explanation, message, errors),
+        status_code: code, errors: errors
+      )
+    end
+
+    def message_for(code, explanation, message, errors)
+      detail = message.to_s.empty? ? Array(errors).join("; ") : message.to_s
+      text = "wFirma: #{explanation} (status #{code.empty? ? "missing" : code})"
+      detail.empty? ? text : "#{text}: #{detail}"
+    end
+  end
+end

data/lib/wfirma/version.rb

@@ -0,0 +1,3 @@
+module Wfirma
+  VERSION = "0.1.0".freeze
+end