wfirma 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 930534cc573b3a0c653e4e9a71c670428f56cb5679855cc6ddc57a07f79bf58b
+  data.tar.gz: 45467f884fffa3503d36e57b5f64ace096ce9ad758207472073cd73ac7b0562f
+SHA512:
+  metadata.gz: 935e0000e190aabc935cb93a1c040a5e92e45dc2ca2ffed592ce662f890f763b3818679aec100a9b6707d041a2d50f8c639fafb19abd030774f8072123a9d993
+  data.tar.gz: 27f6d9046c03b26bcbcce29b3f6cb0228b991da58c3528c4f207f44f3404e4d56bc39bb6f4e656c0147dd0517f59d22dd4b921957ffd37b748a87501e321bd17

data/.yardopts

@@ -0,0 +1,8 @@
+--title "wFirma API client for Ruby"
+--markup markdown
+--readme README.md
+--no-private
+lib/**/*.rb
+-
+CHANGELOG.md
+LICENSE.txt

data/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-08-12
+
+First release as a standalone gem. The library previously lived inside the
+iaml-api-user application as `lib/wfirma`; the entries below are relative to
+that version, for the one consumer upgrading from it.
+
+### Added
+
+- `Wfirma::Client` with `contractors` and `invoices` resources: resolve a
+  customer in the contractor catalogue, issue a VAT invoice, fetch its PDF,
+  and have wFirma email it.
+- `Wfirma::Drivers::Http` (real transport) and `Wfirma::Drivers::Fake`
+  (in-memory, no HTTP) drivers.
+- `Wfirma::Result` for wFirma's HTTP-200-on-failure responses.
+- `Wfirma::Status`, covering wFirma's full documented set of top-level status
+  codes, and an exception per class of failure: `AccessDeniedError`,
+  `RequestError`, `RateLimitError`, `ServiceUnavailableError`, `ServerError`.
+- `Wfirma.configure`, supplying defaults for `Client.new`. They are defaults
+  for building a client, not a singleton the resources read, so several
+  companies can be invoiced in one process and `Client.new(driver:)` still
+  reads no global state.
+- CI across every supported Ruby (3.3, 3.4, 4.0).
+
+### Changed
+
+- Status codes that abort the request are now raised instead of arriving as a
+  `Result` with an empty `errors` list. Previously only `AUTH` raised, so a
+  rate-limit block, an outage or a missing `company_id` all surfaced as
+  "it failed" with no reason attached. `OK`, `ERROR` and `NOT FOUND` still
+  answer with a `Result`; an unrecognised code now raises `ApiError`.
+- `AuthError` is now a subclass of `ApiError` rather than of `Error` directly,
+  so `rescue Wfirma::ApiError` covers every wFirma-reported failure.
+- `Drivers::Fake` raises the same class the real driver does for any armed
+  status code, so failure paths can be exercised offline.
+- `Client.new` with no keys configured or passed now raises `ArgumentError`
+  instead of building a client whose every request failed on authentication.
+- Minimum Ruby is 3.3: 3.2 reached end of life on 2026-03-31.
+
+[Unreleased]: https://github.com/trusive/wfirma/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/trusive/wfirma/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Radosław Woźniak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,287 @@
+# Wfirma
+
+Creating VAT invoices in wFirma: resolve the customer in the contractor
+catalogue, issue the invoice, fetch its PDF, have wFirma email it.
+
+Pure Ruby (stdlib only) — no Rails, no ActiveSupport, no runtime dependencies.
+
+API reference: [doc.wfirma.pl](https://doc.wfirma.pl/).
+
+## Installation
+
+```ruby
+gem "wfirma"
+```
+
+or `gem install wfirma`.
+
+## Building a client
+
+Keys come from the wFirma panel: *Ustawienia → Aplikacje → API*.
+
+```ruby
+require "wfirma"
+
+# Production
+client = Wfirma::Client.new(
+  access_key: ENV.fetch("WFIRMA_ACCESS_KEY"),
+  secret_key: ENV.fetch("WFIRMA_SECRET_KEY"),
+  app_key:    ENV.fetch("WFIRMA_APP_KEY"),
+  company_id: ENV.fetch("WFIRMA_COMPANY_ID")
+)
+
+# Development / tests — no HTTP, no keys
+client = Wfirma::Client.new(driver: Wfirma::Drivers::Fake.new)
+```
+
+To name the keys once instead of at every call site, set them globally — in
+an initializer, say — and build clients with no arguments:
+
+```ruby
+Wfirma.configure do |config|
+  config.access_key = ENV.fetch("WFIRMA_ACCESS_KEY")
+  config.secret_key = ENV.fetch("WFIRMA_SECRET_KEY")
+  config.app_key    = ENV.fetch("WFIRMA_APP_KEY")
+  config.company_id = ENV.fetch("WFIRMA_COMPANY_ID")
+end
+
+Wfirma::Client.new                    # takes all four
+Wfirma::Client.new(company_id: 456)   # overrides one, inherits the rest
+```
+
+`base_url`, `open_timeout` and `read_timeout` can be configured the same way;
+left unset they keep the driver's defaults.
+
+These are defaults for *building* a client, not a singleton the resources read
+on the way out — there is deliberately no `Wfirma.invoices.create`. One wFirma
+account can hold several companies (that is what the `COMPANY ID REQUIRED`
+status code is about), so which company a document lands in stays visible at
+the call site. A second company is a second client, not a global to reassign.
+
+`Wfirma::Client.new(driver:)` reads no configuration at all, so tests on the
+Fake driver need no global state. If a test does set some, `Wfirma.reset_config!`
+puts it back.
+
+## Draft invoices
+
+`draft: true` issues a `normal_draft` document: no book number, not sent to
+KSeF. Everything below uses it. Drop the flag to issue a real VAT invoice.
+
+Note the braces around the invoice attributes: `create` takes them as one
+positional hash followed by `draft:`, so an unbraced hash would be read as
+keyword arguments. `upsert` takes the customer as a bare hash.
+
+## Company with a NIP
+
+```ruby
+customer = client.contractors.upsert(
+  name: "ACME Sp. z o.o.",
+  nip: "1234563218",
+  tax_id_type: "nip",
+  street: "Prosta 1",
+  zip: "00-001",              # Polish codes must be XX-XXX or wFirma refuses
+  city: "Warszawa",
+  country: "PL",
+  email: "faktury@acme.pl"
+)
+
+unless customer.success?
+  # e.g. ["zip: Niepoprawny format kodu pocztowego."]
+  return handle_failure(customer.errors)
+end
+
+invoice = client.invoices.create(
+  {
+    contractor_id: customer.record_id,
+    payment_method: "transfer",         # cash / transfer / compensation / cod / payment_card
+    payment_date: "2026-08-24",         # payment due date
+    items: [
+      { name: "Pakiet AML Premium", count: 1, price: "499.00", vat: 23, unit: "szt." }
+    ]
+  },
+  draft: true
+)
+
+return handle_failure(invoice.errors) unless invoice.success?
+
+invoice.invoice_id                 # => 588425015
+invoice.invoice["fullnumber"]      # => "WRF 6"
+```
+
+The second time this customer buys, `upsert` finds them by NIP and reuses the
+same contractor record instead of creating another. If any field you pass has
+changed, that field is written back to the record; fields you do not pass are
+left alone.
+
+## Person without a NIP
+
+Same call, with `tax_id_type: "none"` and no `nip`. Returning consumers are
+recognised by **email**, so pass one — without it every purchase creates a new
+contractor.
+
+```ruby
+customer = client.contractors.upsert(
+  name: "Jan Kowalski",
+  tax_id_type: "none",
+  email: "jan@example.com",           # how we recognise them next time
+  street: "Prosta 1",
+  zip: "00-001",
+  city: "Warszawa",
+  country: "PL"
+)
+
+return handle_failure(customer.errors) unless customer.success?
+
+invoice = client.invoices.create(
+  {
+    contractor_id: customer.record_id,
+    payment_method: "transfer",
+    items: [
+      { name: "Pakiet AML Standard", count: 1, price: "199.00", vat: 23, unit: "szt." }
+    ]
+  },
+  draft: true
+)
+```
+
+A consumer who gives a **PESEL** needs no special handling — wFirma keeps it in
+the same `nip` field, so they are matched like a company:
+
+```ruby
+client.contractors.upsert(
+  name: "Jan Kowalski", tax_id_type: "pesel", nip: "44051401359",
+  street: "Prosta 1", zip: "00-001", city: "Warszawa", country: "PL"
+)
+```
+
+An email match only ever adopts a record that has no tax id, so someone buying
+privately from the same address as their company will not overwrite the
+company's record.
+
+## PDF and sending
+
+```ruby
+pdf = client.invoices.pdf(invoice.invoice_id)   # binary String, raises on failure
+File.binwrite("faktura.pdf", pdf)
+
+# wFirma emails the PDF itself. Omit email: to use the address on the
+# contractor record, subject:/body: to use wFirma's template.
+sent = client.invoices.send_email(invoice.invoice_id, email: "jan@example.com")
+return handle_failure(sent.errors) unless sent.success?
+```
+
+Print options on both: `page:` (`"invoice"` original, `"invoicecopy"` copy,
+`"all"` both), `duplicate:`, `leaflet:`, and `address:` on `pdf`.
+
+## Results and errors
+
+Every write returns a `Wfirma::Result`. wFirma answers HTTP 200 even for
+failures, so **always check `success?`** — the real outcome is in the status
+code, not the transport.
+
+```ruby
+result.success?      # status.code == "OK"
+result.record_id     # the created/updated object's id (Integer), or nil
+result.record        # the object itself; #invoice / #invoice_id read the same
+result.errors        # ["contractor.nip: …", "invoicecontents.0.invoicecontent.price: …"]
+result.status_code   # "OK", "ERROR", "NOT FOUND", …
+result.raw           # the full parsed response
+```
+
+`errors` reports each failure qualified by where wFirma attached it, including
+errors nested in the contractor or in a single line item.
+
+Only three status codes reach you as a `Result`: `OK`, `ERROR` (validation
+errors on the object) and `NOT FOUND` (a record you named that is not there).
+Every other documented code aborts the request — there is no record for it to
+report on — so it is **raised** rather than folded into a `Result` with an
+empty `errors` list.
+
+| Exception | wFirma status code | What to do |
+|---|---|---|
+| `Wfirma::ConnectionError` | — network failure, timeout, unparseable response | retry |
+| `Wfirma::AuthError` | `AUTH`, `AUTH FAILED LIMIT WAIT 5 MINUTES` | fix the keys; the second is a 5-minute lockout |
+| `Wfirma::AccessDeniedError` | `ACCESS DENIED`, `DENIED SCOPE REQUESTED` | the account or OAuth scope may not do this |
+| `Wfirma::RequestError` | `ACTION NOT FOUND`, `COMPANY ID REQUIRED`, `INPUT ERROR` | the request is wrong; retrying it will not help |
+| `Wfirma::RateLimitError` | `TOTAL REQUESTS LIMIT EXCEEDED`, `TOTAL EXECUTION TIME LIMIT EXCEEDED` | back off and retry later |
+| `Wfirma::ServiceUnavailableError` | `OUT OF SERVICE`, `SNAPSHOT LOCK` | wFirma is down or restoring; retry later |
+| `Wfirma::ServerError` | `FATAL` | wFirma's bug; report it |
+| `Wfirma::ApiError` | any code not listed above | base class of all of these |
+
+All of them are `Wfirma::ApiError` and carry `status_code` and `errors`, so
+`rescue Wfirma::ApiError` catches the lot; `Wfirma::Error` additionally covers
+`ConnectionError`. `pdf` also raises `ApiError` when it gets a JSON error
+instead of a file. An unrecognised code raises `ApiError` rather than passing
+for a soft failure — wFirma may add codes, and a silent one is worse than a
+loud one.
+
+wFirma's limits move with their server load, and their docs recommend batching
+work overnight and avoiding bursts. This library does not retry for you.
+
+## What the library deliberately does not do
+
+- **No postal-code fixing.** Validate the address before this point; a
+  malformed Polish code is reported as a field error on the customer, before
+  any invoice exists.
+- **No VIES handling.** wFirma checks EU VAT ids against VIES live and rejects
+  inactive ones; the rejection is passed straight through.
+- **No defaults for `tax_id_type` or `country`.** Pass them explicitly.
+- **No retries or backoff.** `RateLimitError` and `ServiceUnavailableError`
+  tell you when to back off; the scheduling is yours.
+- **API Key authorization only.** wFirma also documents OAuth 1.0a and OAuth
+  2.0, which reach further than API Keys do. Neither is implemented here.
+
+## Development mode
+
+`Drivers::Fake` runs the whole library — payload mapping, envelopes, `Result`
+parsing — with no HTTP. It keeps an in-memory contractor catalogue, so
+find → add/edit behaves as it does against the real CRM.
+
+```ruby
+fake = Wfirma::Drivers::Fake.new
+client = Wfirma::Client.new(driver: fake)
+
+fake.requests            # every call made, in order
+fake.reset!              # clear recorded calls, stored contractors, failure mode
+```
+
+Failure scenarios, drivable from the UI:
+
+| Contractor NIP | Result |
+|---|---|
+| `0000000000` | validation error on the contractor |
+| `0000000001` | raises `Wfirma::AuthError` |
+| `0000000002` | raises `Wfirma::ConnectionError` |
+
+A Polish `zip` that is not `XX-XXX` is rejected exactly as wFirma rejects it,
+so that path can be exercised offline. All-zeros NIPs are checksum-invalid, so
+no real customer can trigger these by accident.
+
+```ruby
+fake.fail_next!(code: "ERROR", errors: ["contractor.name: nie może być puste"])
+fake.fail_always!(code: "AUTH")
+```
+
+Any documented status code can be armed, and the Fake raises exactly what the
+real driver raises for it — so a rate-limit or outage path can be exercised
+offline:
+
+```ruby
+fake.fail_next!(code: "TOTAL REQUESTS LIMIT EXCEEDED")  # => Wfirma::RateLimitError
+fake.fail_next!(code: "OUT OF SERVICE")                 # => Wfirma::ServiceUnavailableError
+```
+
+## Development
+
+```sh
+bin/setup                  # bundle install
+bundle exec rake           # tests + rubocop
+bundle exec yard server -r # preview the API docs at localhost:8808
+```
+
+Minitest, and the suite runs entirely offline: the Fake driver covers the
+resource layer, webmock covers `Drivers::Http`.
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/lib/wfirma/client.rb

@@ -0,0 +1,54 @@
+module Wfirma
+  # Public entry point.
+  #
+  #   # Production:
+  #   client = Wfirma::Client.new(access_key: "...", secret_key: "...",
+  #                               app_key: "...", company_id: 123)
+  #
+  #   # Or, with Wfirma.configure having named them once:
+  #   client = Wfirma::Client.new
+  #   client = Wfirma::Client.new(company_id: 456)   # a second company
+  #
+  #   # Development (no HTTP, no keys):
+  #   client = Wfirma::Client.new(driver: Wfirma::Drivers::Fake.new)
+  #
+  #   contractor = client.contractors.upsert(name: "ACME", nip: "…", …)
+  #   result = client.invoices.create({ contractor_id: contractor.record_id, … },
+  #                                   draft: true)
+  #   pdf    = client.invoices.pdf(result.invoice_id)
+  #   client.invoices.send_email(result.invoice_id, email: "buyer@example.com")
+  class Client
+    attr_reader :driver
+
+    # Anything passed here wins over Wfirma.configure; anything left out falls
+    # back to it, and then to the driver's own defaults. An injected driver
+    # is used as-is and reads no configuration at all.
+    def initialize(access_key: nil, secret_key: nil, app_key: nil, company_id: nil,
+                   base_url: nil, open_timeout: nil, read_timeout: nil, driver: nil)
+      given = {
+        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
+      }.compact
+
+      @driver = driver || Drivers::Http.new(**Wfirma.config.to_h.merge(given))
+    end
+
+    def call(module_name, action, payload, params = {}, id = nil)
+      driver.call(module_name, action, payload, params, id)
+    end
+
+    # Binary actions (invoices/download); returns raw file bytes.
+    def download(module_name, action, payload, params = {}, id = nil)
+      driver.download(module_name, action, payload, params, id)
+    end
+
+    def invoices
+      @invoices ||= Invoices.new(self)
+    end
+
+    def contractors
+      @contractors ||= Contractors.new(self)
+    end
+  end
+end

data/lib/wfirma/configuration.rb

@@ -0,0 +1,52 @@
+module Wfirma
+  # Application-wide defaults for Wfirma::Client.new, so the keys are named
+  # once - in an application's initializer, say - not at every call site.
+  #
+  #   Wfirma.configure do |config|
+  #     config.access_key = ENV.fetch("WFIRMA_ACCESS_KEY")
+  #     config.secret_key = ENV.fetch("WFIRMA_SECRET_KEY")
+  #     config.app_key    = ENV.fetch("WFIRMA_APP_KEY")
+  #     config.company_id = ENV.fetch("WFIRMA_COMPANY_ID")
+  #   end
+  #
+  #   Wfirma::Client.new                    # takes all four
+  #   Wfirma::Client.new(company_id: 456)   # overrides one, inherits the rest
+  #
+  # These are defaults for building a client, not a singleton the resources
+  # read on the way out. Every request still goes through a Client someone
+  # built, so a second company is another Client rather than a global to
+  # mutate mid-flight, and Client.new(driver:) reads none of this at all.
+  #
+  # A setting left unset means "whatever Drivers::Http defaults to", so the
+  # defaults for base_url and the timeouts live in one place only.
+  class Configuration
+    SETTINGS = %i[
+      access_key secret_key app_key company_id base_url open_timeout read_timeout
+    ].freeze
+
+    attr_accessor(*SETTINGS)
+
+    # Only the settings actually given, so unset ones fall through to the
+    # driver rather than overriding it with nil.
+    def to_h
+      SETTINGS.to_h { |name| [name, public_send(name)] }.compact
+    end
+  end
+
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+      config
+    end
+
+    # Mainly for tests: global defaults are the one piece of state here that
+    # leaks between examples.
+    def reset_config!
+      @config = nil
+    end
+  end
+end

data/lib/wfirma/contractors.rb

@@ -0,0 +1,132 @@
+module Wfirma
+  # Contractors (CRM) resource.
+  #
+  # An invoice can carry the buyer inline, but that data never reaches the
+  # contractor catalogue - each invoice only gets its own contractor_detail
+  # snapshot (verified against the live API). Resolving the customer through
+  # this resource and passing the resulting id as `contractor_id:` is what
+  # puts them in the wFirma contractor list, with one record reused across
+  # their invoices.
+  #
+  #   contractor = client.contractors.upsert(name: "ACME Sp. z o.o.", nip: "…", …)
+  #   raise contractor.errors.join(", ") unless contractor.success?
+  #
+  #   client.invoices.create(contractor_id: contractor.record_id, items: [...])
+  class Contractors
+    def initialize(client)
+      @client = client
+    end
+
+    # contractors/find narrowed by a single equality condition, which is all a
+    # tax-id lookup needs. Returns the matching contractor hashes (possibly
+    # empty); a failed query returns [] as well, so check the tax id you pass.
+    def find_by(field, value)
+      payload = {
+        "contractors" => {
+          "parameters" => {
+            "conditions" => {
+              "condition" => { "field" => field.to_s, "operator" => "eq", "value" => value.to_s }
+            }
+          }
+        }
+      }
+      records(@client.call("contractors", "find", payload))
+    end
+
+    def find_by_nip(nip)
+      find_by("nip", nip)
+    end
+
+    def create(attrs)
+      call("add", stringify_keys(attrs))
+    end
+
+    def update(contractor_id, attrs)
+      call("edit", stringify_keys(attrs), contractor_id)
+    end
+
+    # Reuses the catalogue record carrying this tax id, overwriting any of the
+    # given fields whose value differs, and creates one when there is none.
+    # Fields not passed are left alone, so edits made in the wFirma panel
+    # survive. Returns a Result either way - check success? before using
+    # record_id, since wFirma validates on write (postal code format, VIES).
+    #
+    # By default it recognises a returning customer by tax id, falling back to
+    # email for consumers who have none - see #recognise. Pass match_on to
+    # match on exactly one field instead. wFirma does not treat any of these
+    # as unique, so the first match wins; with nothing to match on, every call
+    # creates a new contractor.
+    #
+    # match_on is positional so that the customer can be passed as a bare hash
+    # - `upsert(name: "…", nip: "…")` would otherwise be read as keywords.
+    def upsert(attrs, match_on = nil)
+      attrs = stringify_keys(attrs)
+      existing = match_on ? match(attrs, match_on.to_s) : recognise(attrs)
+      return create(attrs) unless existing
+
+      changed = attrs.reject { |field, value| existing[field].to_s == value.to_s }
+      return unchanged_result(existing) if changed.empty?
+
+      update(existing["id"], changed)
+    end
+
+    private
+
+    # The tax id is authoritative. wFirma keeps a PESEL in that same `nip`
+    # field - `tax_id_type` says which kind of identifier it is - so this
+    # covers consumers who give one.
+    #
+    # A consumer with tax_id_type "none" has nothing there, so fall back to
+    # their email. That only ever adopts another record without a tax id: one
+    # person may well buy both privately and for their company off the same
+    # address, and a company record must not be overwritten with personal
+    # details. A consumer who changes email reads as a new customer, which is
+    # the safe direction to be wrong in.
+    def recognise(attrs)
+      match(attrs, "nip") || consumer_match(attrs)
+    end
+
+    def match(attrs, field)
+      value = attrs[field]
+      return nil if value.to_s.empty?
+
+      find_by(field, value).first
+    end
+
+    def consumer_match(attrs)
+      email = attrs["email"]
+      return nil if email.to_s.empty?
+
+      find_by("email", email).find { |contractor| contractor["nip"].to_s.empty? }
+    end
+
+    def call(action, contractor, id = nil)
+      payload = { "contractors" => { "contractor" => contractor } }
+      result(@client.call("contractors", action, payload, {}, id))
+    end
+
+    # Nothing to write, so hand back the record we already have in the shape
+    # wFirma would have answered with.
+    def unchanged_result(contractor)
+      result("contractors" => { "0" => { "contractor" => contractor } },
+             "status" => { "code" => "OK" })
+    end
+
+    def result(raw)
+      Result.new(raw, "contractors", "contractor")
+    end
+
+    def records(response)
+      entries = response["contractors"]
+      return [] unless entries.is_a?(Hash)
+
+      entries.filter_map do |key, value|
+        value["contractor"] if key.to_s.match?(/\A\d+\z/) && value.is_a?(Hash)
+      end
+    end
+
+    def stringify_keys(hash)
+      hash.to_h { |key, value| [key.to_s, value] }
+    end
+  end
+end

data/lib/wfirma/deep_dup.rb

@@ -0,0 +1,22 @@
+module Wfirma
+  # Payloads are plain JSON-safe hashes/arrays/scalars, so a simple recursive
+  # dup is enough to give responses and stored records an object graph fully
+  # independent from the caller's - mirroring the isolation a real HTTP
+  # round-trip (serialize/deserialize) would give.
+  module DeepDup
+    module_function
+
+    def deep_dup(value)
+      case value
+      when Hash
+        value.each_with_object({}) { |(key, val), copy| copy[deep_dup(key)] = deep_dup(val) }
+      when Array
+        value.map { |item| deep_dup(item) }
+      when String
+        value.dup
+      else
+        value
+      end
+    end
+  end
+end

data/lib/wfirma/drivers/fake/catalogue.rb

@@ -0,0 +1,44 @@
+module Wfirma
+  module Drivers
+    class Fake
+      # In-memory stand-in for wFirma's 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.
+      class Catalogue
+        include DeepDup
+
+        def initialize
+          @records = {}
+          @next_id = 0
+        end
+
+        # Answers the single equality condition Contractors#find_by sends,
+        # in wFirma's numeric-string-keyed shape.
+        def find(condition)
+          field = condition["field"].to_s
+          value = condition["value"].to_s
+          matches = @records.values.select { |record| record[field].to_s == value }
+          matches.each_with_index.to_h do |record, index|
+            [index.to_s, { "contractor" => deep_dup(record) }]
+          end
+        end
+
+        def add(attrs)
+          id = (@next_id += 1)
+          @records[id] = deep_dup(attrs).merge("id" => id.to_s)
+          deep_dup(@records[id])
+        end
+
+        # Merges in only the fields given, the way contractors/edit does.
+        # Returns nil when there is no such record.
+        def edit(id, attrs)
+          record = @records[id.to_i]
+          return nil unless record
+
+          record.merge!(deep_dup(attrs))
+          deep_dup(record)
+        end
+      end
+    end
+  end
+end