merge: resolve main into task/1_refactoring (error triple + analytics)

[pviti]

Targets task/1_refactoring, not main: merging this clears the conflicts on #2 without anyone force-pushing over your branch, and lets you see how each one was resolved before accepting it.

My fault that they exist — I merged #3 into main while your PR was open, without checking.

The five conflicts

The two changes are additive, not competing — nothing was dropped from either side.

File	Kept from yours	Kept from mine
api_error.rb	grouped @!attribute docs, freeze	code/title/detail, #hint
http_client.rb	all of it (body moved to Request)	— re-applied in request.rb, see below
client.rb	bare requires, grouped docs, freeze	analytics wired + documented
lib/rail0.rb	$LOAD_PATH setup, require list	error_hints before api_error
README.md	Request/DefaultLogger structure lines	api_error + error_hints descriptions

freeze still holds with the extra ivars — they are all assigned before it.

The one resolution that could have done damage is http_client.rb. Your refactoring moved the body into Request, so my edit had nowhere to live there; taking your file wholesale would have silently reverted it. The fix is re-applied in request.rb, which now also passes title: to ApiError:

body[:code] || body[:error] || body[:status]     # was: status first — the family, not the condition
body[:detail] || body[:message] || body[:error]  # was: detail ignored

Without that, e.error would report invalid_state where the gateway said amount_exceeds_refundable.

One fix of yours, found on the way

lib/rail0/default_logger.rb requires "logger", which nothing declares. It left Ruby's default gems in 4.0, so under bundler on a Ruby this gemspec claims to support (required_ruby_version ">= 3.0", no upper bound) requiring the SDK fails outright — that is what stopped me verifying the merge. Added as a runtime dependency in the gemspec; drop it if you would rather pin the Ruby version instead.

Verification

107 examples, 0 failures. Run on Ruby 4.0.5: rbsecp256k1 6.0.0 does not build against the 3.3.4 you pinned on this machine, so the suite has not been exercised on 3.3.4 here — worth a run on your side.

🤖 Generated with Claude Code

[pviti]

Applied this branch's comment convention to the files that came in from main — they still carried the gateway repo's heavier commenting style, which read as an import rather than as part of this refactoring.

Dropped: the family dividers inside ERROR_HINTS, the rationale paragraphs on ApiError / #hint and the analytics methods, the notes above request.rb's error_code and error_message (this branch had already stripped the originals there), the require note in lib/rail0.rb, and the gemspec paragraph — reduced to the single line that says why the dependency exists.

Kept: what each class is for, and every @param / @return.

analytics.rb also picks up the conventions the other resources gained here — require "query", attr_reader :http with freeze, and calling http rather than @http — so the new resource reads like disputes.rb and payments.rb rather than like something bolted on.

Nothing explanatory was lost, only relocated: the one resolution that could silently revert the error fix (http_client.rb → request.rb) is spelled out in the PR description above, which is where it survives a future refactoring better than a comment would.

107 examples, 0 failures.