rail0-sdk 1.0.0

data/lib/rail0/api_error.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Rail0
+  # Raised for non-2xx responses from the RAIL0 gateway, mirroring the code/title/detail
+  # triple the gateway answers with. `detail` is written to be shown to a user; `hint` is
+  # this SDK's own advice, present only for codes worth adding a next step to.
+  class ApiError < StandardError
+    # @!attribute [r] status
+    #   @return [Integer] HTTP status code (e.g. 404, 409, 422).
+    # @!attribute [r] error
+    #   @return [String] The specific condition, and the only field to branch on — e.g.
+    #     "not_capturable", "insufficient_token_balance", "insufficient_gas_funds".
+    # @!attribute [r] title
+    #   @return [String, nil] Short label for the failure, e.g. "Not enough balance".
+    # @!attribute [r] detail
+    #   @return [String, nil] One or two sentences fit to show a user verbatim. Also this
+    #     exception's message.
+    # @!attribute [r] retry_after
+    #   @return [Integer, nil] Seconds the gateway asked the caller to wait, from the
+    #     `Retry-After` header — present on a 429 (`error == "rate_limited"`) and nil
+    #     otherwise. Surfaced because the alternative is a caller guessing: the SDK used
+    #     to drop the header, so "rate limited" arrived with no idea of for how long.
+    #
+    #     Note it is the WHOLE window the gateway throttles over, not the time left in it
+    #     — the limiter sends its period verbatim — so it is an upper bound on the wait,
+    #     not a measurement. Rail0::Backoff clamps it for that reason.
+    attr_reader :status, :error, :title, :detail, :retry_after
+
+    # @param status [Integer]
+    # @param error [String]
+    # @param message [String] The detail; kept positional for compatibility.
+    # @param title [String, nil]
+    # @param retry_after [Integer, nil]
+    def initialize(status, error, message, title: nil, retry_after: nil)
+      super(message)
+      @status = status
+      @error = error
+      @title = title
+      @detail = message
+      @retry_after = retry_after
+      freeze
+    end
+
+    # This SDK's actionable next step for the error, or nil when it has none.
+    # @return [String, nil]
+    def hint
+      Rail0.describe_error(error)
+    end
+  end
+end

data/lib/rail0/backoff.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Rail0
+  # How long to wait before retrying a request the gateway rate-limited.
+  #
+  # Pure, and its own module, because the two interesting decisions here are easy to get
+  # backwards and impossible to notice once they are wrong — a client that waits too
+  # little walks straight back into the limiter, and one that waits too long looks hung.
+  #
+  # 1. JITTER NEVER SHORTENS THE WAIT BELOW WHAT IT IS FOR.
+  #    On a server-instructed wait it is ADDITIVE: scaling a Retry-After DOWN means retrying
+  #    before the window the server named has passed, which is a second 429 by construction.
+  #    So the instruction is honoured in full and a small random tail is added.
+  #
+  #    On a guessed wait it is EQUAL jitter — half the delay fixed, half random — not the
+  #    textbook "full jitter" that multiplies the whole delay by rand(). Full jitter can
+  #    land arbitrarily close to zero, which makes a real pause indistinguishable from the
+  #    bug where a Retry-After of "0" is honoured as a duration and the retry fires
+  #    immediately. A floor spreads the herd just as well and leaves "did we actually wait"
+  #    observable.
+  #
+  #    Why any jitter at all when the server told us the time: because callers align on
+  #    it. rail0-admin proxies every merchant over ONE session, so they share the
+  #    per-session bucket and would all be told the same Retry-After, wake together, and
+  #    recreate the burst the limiter just rejected.
+  #
+  # 2. THE CAP IS NOT PARANOIA. The gateway sends the WHOLE period as Retry-After
+  #    (rack_attack.rb: `headers["retry-after"] = match_data[:period].to_s`), not the time
+  #    remaining in the window — so hitting the limit one second in is told to wait the
+  #    full 60. Capping bounds both that over-wait and a hostile or misconfigured value
+  #    from anything between the client and the gateway.
+  module Backoff
+    module_function
+
+    # @param retry_after [Integer, Float, nil] the server's Retry-After, in seconds.
+    #   Absent, unparseable, zero or negative all mean "no instruction" — and zero is the
+    #   trap: it is a valid duration, so treating it as one produces a burst of
+    #   back-to-back requests against the very limiter that asked for a pause.
+    # @param attempt [Integer] 1 for the first retry, 2 for the second, …
+    # @param base [Float] the exponential backoff's first delay, in seconds.
+    # @param cap [Float] the longest wait to allow, in seconds.
+    # @param jitter [Float, nil] randomness in [0,1); injected only by tests. Nil draws it.
+    # @return [Float] seconds to sleep.
+    def throttle_delay(retry_after:, attempt:, base:, cap:, jitter: nil)
+      random = jitter || Kernel.rand
+      instructed = positive_number(retry_after)
+
+      if instructed
+        # Honour it in full (clamped), plus a fraction of one base delay so aligned
+        # callers do not wake in lockstep.
+        [instructed, cap].min + (random * base)
+      else
+        # No instruction: exponential from `base`, EQUAL jitter (half fixed, half random),
+        # clamped.
+        full = base * (2**(attempt - 1))
+        [(full / 2.0) + ((full / 2.0) * random), cap].min
+      end
+    end
+
+    # @return [Float, nil] the value when it is a positive number, else nil.
+    def positive_number(value)
+      number = Float(value, exception: false)
+      number&.positive? ? number : nil
+    end
+  end
+end

data/lib/rail0/client.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative "http_client"
+require_relative "resources/auth"
+require_relative "resources/chains"
+require_relative "resources/tokens"
+require_relative "resources/health"
+require_relative "resources/payment_methods"
+require_relative "resources/accounts"
+require_relative "resources/wallets"
+require_relative "resources/payments"
+require_relative "resources/disputes"
+require_relative "resources/webhooks"
+require_relative "resources/analytics"
+
+module Rail0
+  # Entry point for the RAIL0 SDK.
+  #
+  #   client = Rail0::Client.new(base_url: "https://api.rail0.xyz")
+  #   resp   = client.auth.login(private_key: "0x...", domain: "api.rail0.xyz")
+  #   resp   = client.payments.create(chain_id: 84532, mode: "authorize", amount: "100.00", token: "0x...", payer: "0x...", payee: "0x...")
+  #
+  # Most of this API is authenticated: the ENTIRE payments sub-tree (create, sign,
+  # every prepare/submit, reads and list) plus wallets, webhooks, disputes and
+  # analytics. Only chains, tokens, health and payment_methods are public. The token
+  # is supplied via +headers+: pass +{ "Authorization" => "Bearer <jwt>" }+ (obtained
+  # from +auth.login+). The SDK does not persist the token for you.
+  class Client
+    # @!attribute [r] auth
+    #   @return [Resources::Auth] SIWE authentication operations.
+    # @!attribute [r] chains
+    #   @return [Resources::Chains] Public blockchain catalog.
+    # @!attribute [r] tokens
+    #   @return [Resources::Tokens] Public token catalog.
+    # @!attribute [r] health
+    #   @return [Resources::Health] Gateway liveness/readiness check.
+    # @!attribute [r] payment_methods
+    #   @return [Resources::PaymentMethods] Public buyer-facing payment-method discovery.
+    # @!attribute [r] accounts
+    #   @return [Resources::Accounts] The account's own profile (JWT, holder only).
+    # @!attribute [r] wallets
+    #   @return [Resources::Wallets] Account-scoped wallet management (JWT).
+    # @!attribute [r] payments
+    #   @return [Resources::Payments] Payment lifecycle operations.
+    # @!attribute [r] disputes
+    #   @return [Resources::Disputes] Account-level dispute list (JWT).
+    # @!attribute [r] webhooks
+    #   @return [Resources::Webhooks] Webhook subscription management (JWT).
+    # @!attribute [r] analytics
+    #   @return [Resources::Analytics] Account-scoped payment analytics (JWT).
+    attr_reader :auth, :chains, :tokens, :health, :payment_methods,
+                :accounts, :wallets, :payments, :disputes, :webhooks, :analytics
+
+    # @param base_url [String] Base URL of the RAIL0 API, e.g. "https://api.rail0.xyz".
+    # @param headers [Hash] Default headers merged into every request (e.g. Authorization).
+    # @param token [String, #call, nil] Bearer token, or a callable resolved per request
+    #   (e.g. +token: -> { current_jwt }+) so one shared client survives a token
+    #   refresh. An explicit Authorization in +headers+ takes precedence.
+    # @param timeout [Numeric] Timeout in seconds. Default: 30.
+    # @param logger [#call, nil] Optional logger. Pass Rail0::DEFAULT_LOGGER for built-in output.
+    # @param max_retries [Integer] Extra attempts after a network failure. Default: 0.
+    # @param retry_delay [Numeric] Base delay in seconds between retries (exponential backoff). Default: 0.2.
+    # @param retry_on_429 [Boolean] Retry a rate-limited request, waiting the gateway's
+    #   Retry-After. Default: false — an automatic sleep hides back-pressure from the
+    #   process that could react to it, and stalls a request/response app. Turn it on in a
+    #   job. It works on its own: no need to set +max_retries+ as well.
+    # @param retry_after_cap [Numeric] Longest Retry-After to honour, in seconds. Default: 60.
+    def initialize(base_url:, headers: {}, token: nil, timeout: 30, logger: nil,
+                   max_retries: 0, retry_delay: 0.2, retry_on_429: false, retry_after_cap: 60)
+      http = HttpClient.new(
+        base_url: base_url, headers: headers, token: token, timeout: timeout,
+        logger: logger, max_retries: max_retries, retry_delay: retry_delay,
+        retry_on_429: retry_on_429, retry_after_cap: retry_after_cap
+      )
+      @auth            = Resources::Auth.new(http)
+      @chains          = Resources::Chains.new(http)
+      @tokens          = Resources::Tokens.new(http)
+      @health          = Resources::Health.new(http)
+      @payment_methods = Resources::PaymentMethods.new(http)
+      @accounts        = Resources::Accounts.new(http)
+      @wallets         = Resources::Wallets.new(http)
+      @payments        = Resources::Payments.new(http)
+      @disputes        = Resources::Disputes.new(http)
+      @webhooks        = Resources::Webhooks.new(http)
+      @analytics       = Resources::Analytics.new(http)
+      freeze
+    end
+  end
+end

data/lib/rail0/default_logger.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module Rail0
+  # One log record emitted per request attempt.
+  # rubocop:disable Lint/StructNewOverride -- `method` is the HTTP method, which is the right
+  # name for it on a log record. It shadows Struct#method (reflection), which nothing here
+  # uses; renaming the field to avoid that would make every log line read worse.
+  LogEntry = Struct.new(
+    :method, :url, :duration_ms, :request_body,
+    :status, :response_body, :error, :attempt, :will_retry,
+    keyword_init: true
+  )
+  # rubocop:enable Lint/StructNewOverride
+
+  # Default logger for Rail0::Client's `logger:` option. A Logger subclass:
+  # formats a Rail0::LogEntry into a one-line summary and logs it through the
+  # standard Logger machinery, so #level, #formatter, and any IO/file logdev
+  # all work normally instead of being reimplemented.
+  #
+  #   client = Rail0::Client.new(base_url: "https://api.rail0.xyz", logger: Rail0::DEFAULT_LOGGER)
+  #   # [rail0] GET 200 https://.../payments/0x… 87ms
+  #
+  #   # Write to a file, only warnings and above:
+  #   client = Rail0::Client.new(
+  #     base_url: "https://api.rail0.xyz",
+  #     logger:   Rail0::DefaultLogger.new("rail0.log", level: Logger::WARN)
+  #   )
+  class DefaultLogger < Logger
+    def initialize(logdev = $stdout, *args, **kwargs)
+      super
+    end
+
+    # The callable interface HttpClient expects: one Rail0::LogEntry per
+    # request attempt. Routes to #error on failure so raising the level past
+    # DEBUG still surfaces failed requests, and to #debug otherwise.
+    def call(entry)
+      entry.error ? error(message_for(entry)) : debug(message_for(entry))
+    end
+
+    private
+
+    def message_for(entry)
+      flag        = entry.error ? " ERROR" : ""
+      status_part = entry.status ? " #{entry.status}" : ""
+      attempt_part =
+        if entry.attempt && (entry.attempt > 1 || entry.will_retry)
+          retry_part = entry.will_retry ? ", retrying" : ""
+          " [attempt #{entry.attempt}#{retry_part}]"
+        else
+          ""
+        end
+
+      parts = ["[rail0]#{flag}#{attempt_part} #{entry.method}#{status_part} #{entry.url} #{entry.duration_ms.round}ms"]
+      parts << "-> #{entry.request_body.inspect}" if entry.request_body
+      parts << "<- #{entry.response_body.inspect}" if entry.response_body
+      parts << "! #{entry.error}"                  if entry.error
+      parts.join(" ")
+    end
+  end
+
+  # Ready-to-use DefaultLogger writing to $stdout at the default level, shared
+  # so callers who just want the built-in output don't need to instantiate
+  # their own. Frozen -- it can't be reconfigured (no #level=, no #formatter=)
+  # since that would leak across every Client sharing it; anyone wanting a
+  # different IO/level should build their own via DefaultLogger.new(...).
+  #
+  #   client = Rail0::Client.new(base_url: "https://api.rail0.xyz", logger: Rail0::DEFAULT_LOGGER)
+  DEFAULT_LOGGER = DefaultLogger.new.freeze
+
+  # The `logger:` used when the caller doesn't pass one. Discards every entry,
+  # so HttpClient can always unconditionally call `logger.call(entry)` without
+  # ever checking whether logging is actually configured.
+  class NullLogger
+    def call(_entry); end
+  end
+
+  # NullLogger is stateless, so every HttpClient built without an explicit
+  # `logger:` shares this one frozen instance instead of allocating its own.
+  NULL_LOGGER = NullLogger.new.freeze
+end

data/lib/rail0/error_hints.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Rail0
+  # Actionable next steps per error code, supplementing the gateway's own `detail`.
+  # Shared source with the Go SDK (rail0.DescribeError), the TS SDK (describeError) and
+  # the CLI's hints — keep the four in step.
+  ERROR_HINTS = {
+    "amount_exceeds_capturable" => "amount is above the capturable balance — check capturableAmount on the payment",
+    "amount_exceeds_refundable" => "amount is above the refundable balance — check refundableAmount on the payment",
+    "not_capturable" => "the payment must be 'authorized' or 'partially_captured' to capture",
+    "not_voidable" => "void is only allowed while 'authorized' with nothing captured — use release for the remainder after a capture",
+    "not_releasable" => "release opens only after authorizationExpiry",
+    "not_refundable" => "nothing is refundable — the payment must be charged/captured and within the refund window",
+    "not_signable" => "the payment must be 'unsigned' to sign",
+    "already_signed" => "the payer signature is already stored — the payee can act now",
+    "no_signature" => "the payer has not signed yet",
+    "wrong_mode" => "this operation doesn't match the payment's mode (authorize vs charge)",
+    "already_disputed" => "a dispute is already open — close it first",
+    "not_disputed" => "there is no open dispute to close",
+    "nothing_to_dispute" => "a dispute needs a merchant-held (refundable) balance",
+    "transaction_not_overwritable" => "a transaction for this operation is already in flight — wait for it to settle",
+    "signer_mismatch" => "the signing key doesn't match the payment's payer/payee",
+    # The SIWE BINDING failures, split out of signer_mismatch so a failed login says
+    # WHICH part of the proof did not bind (#216). None names the server's own
+    # expectation: that endpoint is unauthenticated, so echoing the allow-list or the
+    # expected chain id would turn every hint into a probe.
+    "siwe_domain_not_allowed" => "sign with the origin the front-end is served from, and have it added to the gateway's SIWE domain allow-list",
+    "siwe_uri_mismatch" => "the message's uri host must equal its own domain",
+    "siwe_chain_mismatch" => "use the chain id the client library sends - this login is off-chain and nominal",
+    "siwe_proof_expired" => "get a fresh nonce and sign again",
+    # Address-wide, not one token: "sign in again", not "that token is dead".
+    "sessions_revoked" => "every session issued before this address's revoke-all cutoff is refused - sign in again",
+    "config_hash_mismatch" => "the payment record and its on-chain deployment disagree — the payment cannot be operated as recorded",
+    "payment_not_on_chain" => "the contract has no record of this payment — its opening transaction may never have confirmed",
+    "unsupported_contract_version" => "the payment's RAIL0 deployment is newer or older than this gateway supports — upgrade the gateway",
+    "insufficient_token_balance" => "the paying wallet does not hold enough of the token — top it up and retry",
+    "invalid_token_signature" => "the EIP-3009 authorization did not recover to the paying wallet — wrong key, chain, token or amount",
+    "authorization_already_used" => "that EIP-3009 authorization was already spent or cancelled — each is single-use, create a fresh payment",
+    "authorization_not_yet_valid" => "the authorization's validAfter is still in the future",
+    "token_account_blocked" => "the token issuer has blocklisted one of the wallets in this transfer",
+    "token_paused" => "the token contract is paused by its issuer — no transfer can settle right now",
+    "insufficient_gas_funds" => "the sending wallet cannot cover gas — fund it with the chain's native token",
+    "nonce_too_low" => "a transaction with that nonce is already on-chain — re-prepare the operation",
+    "replacement_underpriced" => "another transaction with that nonce is pending and this one does not pay enough to replace it",
+    "gas_price_too_low" => "the fee is below what the node accepts — re-prepare to pick up current fees",
+    "already_known" => "the node already has this exact transaction — wait for it to confirm rather than resending",
+    "rpc_unavailable" => "no configured RPC endpoint answered — the transaction was not submitted",
+    "not_the_payee" => "only the payment's payee can do this — sign in with the merchant's wallet",
+    "not_the_payer" => "only the payment's payer can do this — sign in with the buyer's wallet",
+    "not_a_participant" => "only the payer and the payee can see or act on a payment",
+    "not_payee" => "only the merchant (payee) may do this",
+    "not_payer" => "only the buyer (payer) may do this",
+    "not_payer_or_payee" => "only the payer or the payee may do this",
+    "refund_expired" => "the refund window has closed (refundExpiry passed) — refund/dispute is no longer possible",
+    "authorization_not_expired" => "release opens only after authorizationExpiry — wait until it passes",
+    "already_captured" => "already (partially) captured — use release for the remainder, not void",
+    "token_not_accepted" => "the token isn't in this deployment's allowlist",
+    "payment_already_exists" => "a payment with this id already exists on-chain",
+    # Ported from rail0-go, which had drifted five codes ahead of this table (#13).
+    "unsupported_payment_method" => "the payee (merchant) doesn't accept this token/chain — check the merchant's payment methods",
+    "idempotency_key_reused" => "that Idempotency-Key was already used for a payment with different terms — reuse it only to retry the same request, or pick a new key",
+    "unknown_token" => "the token isn't configured on this chain",
+    "no_active_contract" => "no active RAIL0 contract on that chain",
+    "missing_param" => "a required parameter is missing from the request",
+    # A BARE forbidden is not a party mismatch: the gateway split those into codes of
+    # their own (not_the_payee, not_the_payer, wallet_deactivated, not_your_account)
+    # because they need different fixes. This entry kept describing one of them long
+    # after the split — and the rule it named no longer exists in the gateway at all.
+    "forbidden" => "not permitted for this session — typically the operator grant, a resource owned by another account, or a transaction signed by the wrong wallet"
+  }.freeze
+
+  # An actionable hint for a rail0 error code, or nil when the code is unknown.
+  # @param code [String, nil]
+  # @return [String, nil]
+  def self.describe_error(code)
+    return nil if code.nil? || code.to_s.empty?
+
+    ERROR_HINTS[code.to_s]
+  end
+end

data/lib/rail0/http_client.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative "default_logger"
+require_relative "request"
+
+module Rail0
+  # @!visibility private
+  class HttpClient
+    attr_reader :base_url, :timeout, :logger, :max_retries, :retry_delay,
+                :retry_on_429, :retry_after_cap
+
+    # @param retry_on_429 [Boolean] retry a rate-limited request, waiting the gateway's
+    #   Retry-After (see Rail0::Backoff). OFF by default, deliberately: an automatic
+    #   sleep hides back-pressure from the one process that could react to it, and in a
+    #   request/response app it turns a 429 into a stalled page. Turn it on for a job.
+    #
+    #   It does NOT need `max_retries` to be set as well. That pairing is a footgun —
+    #   the flag would silently do nothing — so on its own it allows one retry.
+    # @param retry_after_cap [Numeric] longest wait to honour, in seconds. The gateway
+    #   sends its whole throttle period as Retry-After rather than the time left in it,
+    #   so this bounds both the over-wait and any hostile value from in between.
+    def initialize(base_url:, headers: {}, token: nil, timeout: 30, logger: nil,
+                   max_retries: 0, retry_delay: 0.2, retry_on_429: false,
+                   retry_after_cap: 60)
+      @base_url        = base_url.chomp("/")
+      @static_headers  = { "Content-Type" => "application/json" }.merge(headers)
+      @token           = token
+      @timeout         = timeout
+      @logger          = logger || NULL_LOGGER
+      @max_retries     = max_retries
+      @retry_delay     = retry_delay
+      @retry_on_429    = retry_on_429
+      @retry_after_cap = retry_after_cap
+      freeze
+    end
+
+    # Headers for one request.
+    #
+    # A `token` is resolved HERE, per request, rather than baked in at construction:
+    # you need a client to call auth.login, and the login's JWT to build the client
+    # you actually use, so a header fixed at construction forced a whole new client
+    # (and its ten resource objects) on every sign-in and every refresh. Passing a
+    # callable — `token: -> { current_jwt }` — keeps one shared client valid across
+    # token rotations, which is what a long-lived process needs. A String token is
+    # accepted for the simple case, and an explicit Authorization in `headers`
+    # still wins so nothing existing changes. (#11)
+    #
+    # The object stays frozen: what varies is the proc's answer, not this object.
+    def headers
+      return @static_headers if @token.nil? || @static_headers.key?("Authorization")
+
+      resolved = @token.respond_to?(:call) ? @token.call : @token
+      return @static_headers if resolved.nil? || resolved.to_s.empty?
+
+      @static_headers.merge("Authorization" => "Bearer #{resolved}")
+    end
+
+    def get(path)
+      request(:get, path)
+    end
+
+    # GET a paginated collection endpoint. The gateway returns a bare JSON array
+    # with pagination carried in the X-Total-Count / X-Page / X-Per-Page response
+    # headers (not a {data, meta} envelope), so this reads the meta back from the
+    # headers and wraps the array. Non-paginated array endpoints (blockchains,
+    # tokens, payment_methods) use plain #get instead.
+    # @return [Hash] { data: Array<Hash>, meta: { page:, per_page:, total: } }
+    def get_list(path)
+      request(:get, path, nil, paginated: true)
+    end
+
+    # @param headers [Hash] extra headers merged over the client defaults for this
+    #   request only (e.g. { "Idempotency-Key" => "..." }).
+    def post(path, body = nil, headers: {})
+      request(:post, path, body, headers: headers)
+    end
+
+    def put(path, body = nil)
+      request(:put, path, body)
+    end
+
+    def patch(path, body = nil)
+      request(:patch, path, body)
+    end
+
+    def delete(path)
+      request(:delete, path)
+    end
+
+    private
+
+    def request(method, path, body = nil, paginated: false, headers: {})
+      Request.new(
+        client: self, method: method, path: path, body: body,
+        paginated: paginated, extra_headers: headers
+      ).call
+    end
+  end
+end