rail0-sdk 1.0.0

data/lib/rail0/types.rb

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+
+# Code generated by gen/generate.rb — DO NOT EDIT.
+# Re-run `ruby gen/generate.rb` after updating the gateway OpenAPI schema.
+#
+# Source: rail0-gateway/docs/openapi.json
+#
+# These Structs document the gateway's request/response shapes. They are
+# reference only — SDK methods return plain Hashes with symbol keys.
+
+module Rail0
+  module Types
+    # A wallet's on-chain balances, one entry per chain.
+    WalletBalances = Struct.new(
+      :wallet_id,  # String
+      :address,    # String
+      :balances,   # Array
+      keyword_init: true
+    )
+
+    # Balances on one chain. `native`/`tokens` are null when `error` is present; `error` is null on
+    # success.
+    ChainBalance = Struct.new(
+      :chain_id,      # Integer
+      :network_type,  # String
+      :native,        # AssetBalance
+      :tokens,        # Array
+      :error,         # BalanceError
+      keyword_init: true
+    )
+
+    # A single balance line — the native gas token or one ERC-20.
+    AssetBalance = Struct.new(
+      :symbol,    # String
+      :address,   # Token contract address; null for the native balance.
+      :decimals,  # Integer
+      :raw,       # String — Balance in base units (exact).
+      :amount,    # String — Human-decimal balance.
+      keyword_init: true
+    )
+
+    # Why a chain's balances couldn't be read.
+    BalanceError = Struct.new(
+      :code,     # String
+      :message,  # String
+      keyword_init: true
+    )
+
+    # Error envelope. Every error this API returns carries `code` (stable and machine-readable — the
+    # only field to branch on), `title` (a short label) and `detail` (one or two sentences fit to show a
+    # user verbatim). The wording comes from the gateway's error catalogue, so the same condition always
+    # reads the same way wherever it surfaces. `status` and `message` are the pre-code/title/detail
+    # names, derived from the same entry and kept for existing clients: `status` carries the family a
+    # client used to switch on (e.g. `forbidden`, `invalid_state`) where `code` is narrower, and
+    # `message` equals `detail`. Context fields may also be present (`resource`, `param`, `chain_id`,
+    # `token`, `payee`, `errors`).
+    ApiErrorBody = Struct.new(
+      :code,     # String
+      :title,    # String
+      :detail,   # String
+      :status,   # String — Legacy: the error family, or the code itself when there is no wider family.
+      :message,  # String — Legacy alias of `detail`.
+      keyword_init: true
+    )
+
+    # Gateway liveness/readiness. Only the database gates the HTTP code (200 healthy, 503 when the DB is
+    # unreachable); Sidekiq is reported but never flips the code, since the API still serves synchronous
+    # requests when workers are down. `status` is the global signal: `ok` (all good), `degraded` (DB ok
+    # but Sidekiq not ok), `error` (DB down — the only 503).
+    Health = Struct.new(
+      :status,            # String
+      :api_version,       # String
+      :contract_version,  # String
+      :db,                # String
+      :sidekiq,           # Hash — Worker fleet health (does not gate liveness).
+      :active_chains,     # Integer
+      :active_contracts,  # Integer
+      :timestamp,         # String
+      keyword_init: true
+    )
+
+    # A single-use SIWE nonce to embed in the sign-in message.
+    Nonce = Struct.new(
+      :nonce,       # String — The nonce value to place in the SIWE message's `Nonce:` field.
+      :expires_at,  # String — When the nonce expires and can no longer be used.
+      keyword_init: true
+    )
+
+    # Issued after a successful SIWE verification. SIWE alone proves control of the address, so a token
+    # is issued even when the address is not registered to any account; in that case `account_id` and
+    # `name` are null (an account-less session, e.g. a buyer). Clients that require an account must
+    # treat a null `account_id` as not-allowed.
+    Session = Struct.new(
+      :token,       # String — JWT bearer token.
+      :address,     # String — Resolved wallet address.
+      :account_id,  # String — The account owning the signed-in wallet, or null for an account-less (e.g. buyer) session.
+      :name,        # String — The account's human-readable name, or null for an account-less session.
+      :expires_at,  # String
+      keyword_init: true
+    )
+
+    # Public blockchain view.
+    #
+    # required_confirmations and finality_tag together say how long a payer waits. Read
+    # the PAIR, not the number: where a chain serves a finality tag the gateway gates on
+    # that tag, and the count is the fallback for chains serving none — so quoting the
+    # count on a tagged chain names a wait nobody applies.
+    Blockchain = Struct.new(
+      :chain_id,               # Integer
+      :name,                   # String
+      :native_symbol,          # String
+      :network_type,           # String
+      :explorer_url,           # String
+      :required_confirmations, # Integer
+      :finality_tag,           # String, nil where the chain serves no tag
+      keyword_init: true
+    )
+
+    # Public accepted-token view. The listing is not implicitly active-only (a payment references its
+    # token address forever, so a retired token must stay resolvable), so `active` tells a usable token
+    # from a retired one.
+    Token = Struct.new(
+      :chain_id,  # Integer
+      :symbol,    # String
+      :address,   # String
+      :decimals,  # Integer
+      :active,    # Boolean — False for a retired token: still resolvable for historical payments, but not usable for a new one.
+      keyword_init: true
+    )
+
+    # Public-safe wallet view (the reduced set a buyer needs to discover a merchant's payment methods).
+    Wallet = Struct.new(
+      :id,       # String
+      :address,  # String
+      :label,
+      :active,   # Boolean
+      keyword_init: true
+    )
+
+    # A wallet's token holding, with the wallet, token, and blockchain nested via their own schemas.
+    WalletToken = Struct.new(
+      :default,     # Boolean
+      :active,      # Boolean
+      :wallet,      # Wallet
+      :token,       # Token
+      :blockchain,  # Blockchain
+      keyword_init: true
+    )
+
+    # A wallet's token holding as nested under its wallet (GET /accounts/:id/wallets): the token plus
+    # this wallet's per-token flags, without re-nesting the wallet.
+    WalletTokenHolding = Struct.new(
+      :token,    # Token
+      :active,   # Boolean
+      :default,  # Boolean
+      keyword_init: true
+    )
+
+    # A wallet with its token holdings nested inline. `tokens` is empty when the wallet has none — the
+    # wallet is still returned, never omitted.
+    WalletWithTokens = Struct.new(
+      :id,       # String
+      :address,  # String
+      :label,
+      :active,   # Boolean
+      :tokens,   # Array
+      keyword_init: true
+    )
+
+    # Base persisted payment fields.
+    Payment = Struct.new(
+      :id,                    # String
+      :contract_id,           # String
+      :chain_id,              # Integer — EVM chain id of the deployment. On list rows too: `amount` is
+      #                         base units, and the token's decimals resolve from `token` PLUS its chain.
+      :rail0_id,              # String — Protocol-level identifier (66-char hex).
+      :status,                # String
+      :mode,                  # String
+      :amount,                # String
+      :capturable_amount,     # String — Mirrors on-chain capturableAmount (escrow still held); base units.
+      :refundable_amount,     # String — Mirrors on-chain refundableAmount (held by payee, still refundable); base units.
+      # The window after a PARTIAL capture where neither void nor release can return the
+      # buyer's remaining escrow — the answer to "why did both just refuse?".
+      :escrow_stranded,       # Boolean
+      :escrow_returnable_at,  # String, nil — ISO-8601 end of that window; nil outside it.
+      :config_hash,           # String
+      :payer,                 # String
+      :payee,                 # String
+      :token,                 # String
+      :authorization_expiry,  # Integer
+      :refund_expiry,         # Integer
+      :disputed,              # Boolean — True while an open dispute exists.
+      :last_error_code,       # Decoded reason of the last failed on-chain attempt; null once the payment makes forward progress. Non-null means the latest attempt failed.
+      :last_error_message,    # Human-readable form of last_error_code.
+      :description,
+      :metadata,
+      :signed_at,             # When the payer signature was stored (null while unsigned).
+      :created_at,            # String
+      :updated_at,            # String
+      keyword_init: true
+    )
+
+    # Buyer-driven, signal-only dispute lifecycle (no fund effect).
+    Dispute = Struct.new(
+      :id,            # String
+      :payment_id,    # String
+      :status,        # String
+      :reason,        # String — On-chain bytes32 reason code (hex).
+      :opened_block,
+      :opened_at,     # String
+      :closed_by,
+      :close_reason,
+      :closed_block,
+      :closed_at,
+      keyword_init: true
+    )
+
+    Transaction = Struct.new(
+      :id,                    # String
+      :payment_id,            # String
+      :operation,             # String
+      :status,                # String
+      :error_code,            # Decoded failure code, null unless `status` is "failed". Same catalogue as an error body's `code`: a RAIL0 custom error (`not_payee`), a token-level revert (`insufficient_token_balance`, `invalid_token_signature`, `authorization_already_used`), a Solidity panic, or a rejection that stopped the broadcast before the chain saw it (`insufficient_gas_funds`, `nonce_too_low`).
+      :error_title,           # String — Short label for `error_code`; null unless failed.
+      :error_detail,          # String — Sentence explaining the failure; null unless failed. Carries the chain's own words when the revert was not one the gateway recognises.
+      :error_message,         # Legacy alias of `error_detail`.
+      :unsigned_transaction,
+      :transaction_hash,
+      :amount,
+      :block_number,
+      :gas_used,              # Gas units used, mirrored from the indexer on confirm.
+      :gas_limit,             # Gas limit, mirrored from the indexer on confirm.
+      :effective_gas_price,   # Effective gas price in wei, mirrored from the indexer on confirm.
+      :base_fee_per_gas,      # Block base fee per gas in wei, mirrored from the indexer on confirm.
+      :gas_cost,              # Total gas cost in wei (gas_used * effective_gas_price); derived, null until confirmed.
+      :pending_at,
+      :submitted_at,
+      :confirmed_at,
+      :created_at,            # String
+      :updated_at,            # String
+      keyword_init: true
+    )
+
+    Webhook = Struct.new(
+      :id,                     # String
+      :name,                   # String
+      :callback_url,           # String
+      :topics,                 # Array<WebhookTopic> — every event this subscription delivers
+      :active,                 # Boolean
+      :circuit_state,          # String
+      :circuit_failure_count,  # Integer
+      :created_at,             # String
+      :updated_at,             # String
+      keyword_init: true
+    )
+
+    EventCallback = Struct.new(
+      :id,                # String
+      :webhook_id,        # String
+      :payment_id,        # String
+      :topic,             # String
+      :callback_url,      # String
+      :response_code,
+      :response_message,
+      :error_reason,
+      :status,            # String
+      :created_at,        # String
+      :payload,           # The JSON request body POSTed to the callback URL (decompressed).
+      keyword_init: true
+    )
+
+    # Sweeper view of a stale submitted transaction.
+    SyncTransaction = Struct.new(
+      :transaction_hash,  # String
+      :operation,         # String
+      :payment_id,        # String — Protocol-level rail0_id.
+      :chain_id,          # Integer
+      keyword_init: true
+    )
+
+    # Per-chain indexer config.
+    SyncBlockchain = Struct.new(
+      :chain_id,                # Integer
+      :start_block,             # Integer
+      :required_confirmations,  # Integer — Fallback burial depth, used where the chain serves no finality tag.
+      :finality_tag,            # String — Which block the chain calls settled ("safe", "finalized" or
+      #                           "depth"); the indexer gates every notify on it.
+      :explorer_url,            # Block explorer base URL; null when the chain has none.
+      :network_type,            # String — "testnet" or "mainnet"; selects which chains a deployment indexes.
+      :rpc_urls,                # Array — Ordered list of public RPC endpoints tried in turn (serial fallback).
+      :contracts,               # Array — Active RAIL0 contract addresses on the chain (all watched versions).
+      keyword_init: true
+    )
+  end
+end

data/lib/rail0/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Rail0
+  # 1.0.0 is where the PUBLISHED history starts. The gem reached 1.2.0 while it was
+  # consumed by path from a sibling checkout, where the number bought nothing: no registry
+  # ever served a 1.x, no tag was ever cut, and the one consumer resolves the working tree.
+  # Publishing from 1.2.0 would have implied two releases nobody can install.
+  VERSION = "1.0.0"
+end

data/lib/rail0/webhook_signature.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Rail0
+  # Verification for the signature the gateway puts on every webhook delivery.
+  #
+  # The SDK used to hand out `shared_secret` on create/rotate, tell the reader to
+  # verify deliveries with it, and provide nothing to verify with — so every
+  # consumer had to reverse-engineer the scheme, and getting it wrong is a security
+  # bug in THEIR app, not a failed request. (#9)
+  #
+  # A delivery carries:
+  #
+  #   X-Rail0-Topic      the topic, e.g. "payments.captured"
+  #   X-Rail0-Timestamp  unix seconds, as a string
+  #   X-Rail0-Signature  hex HMAC-SHA256 over "{timestamp}.{body}", keyed by the secret
+  #
+  # The timestamp is inside the signed string on purpose: without it a captured
+  # delivery is replayable forever, because the body alone stays valid indefinitely.
+  # That is why {verify} rejects a stale timestamp even when the digest matches —
+  # checking the digest and ignoring the clock leaves the replay window wide open.
+  module WebhookSignature
+    # Same window the gateway's own /sync channel uses, symmetric so a consumer
+    # whose clock runs fast doesn't reject live deliveries.
+    DEFAULT_TOLERANCE_SECONDS = 300
+
+    class << self
+      # Verify a delivery. Returns true / false — nothing here raises on a bad
+      # signature, since a spoofed request is an expected condition on a public
+      # endpoint, not an exception.
+      #
+      # @param body [String] the RAW request body, exactly as received. Re-serialising
+      #   a parsed hash changes key order and whitespace, and the digest with it.
+      # @param signature [String] the X-Rail0-Signature header.
+      # @param timestamp [String, Integer] the X-Rail0-Timestamp header.
+      # @param secret [String] the webhook's shared_secret.
+      # @param tolerance [Integer] accepted clock skew in seconds, either direction.
+      # @param now [Time] injectable clock, for tests.
+      # @return [Boolean]
+      # `verify`, not `verify?`: it is the SDK's public API and reads as the action it
+      # performs (see Naming/PredicateMethod in .rubocop-shared.yml).
+      def verify(body:, signature:, timestamp:, secret:, tolerance: DEFAULT_TOLERANCE_SECONDS, now: Time.now)
+        return false if body.nil? || secret.to_s.empty?
+        return false unless fresh?(timestamp, tolerance, now)
+
+        secure_equal?(signature.to_s, expected_signature(body, timestamp, secret))
+      end
+
+      # The signature the gateway would send for this (timestamp, body). Exposed so a
+      # consumer can log or diff the two sides when a delivery is being rejected —
+      # comparing digests by eye is otherwise the only way to debug it.
+      #
+      # @return [String] hex HMAC-SHA256 over "{timestamp}.{body}"
+      def expected_signature(body, timestamp, secret)
+        OpenSSL::HMAC.hexdigest("SHA256", secret, "#{timestamp}.#{body}")
+      end
+
+      private
+
+      def fresh?(timestamp, tolerance, now)
+        seconds = Integer(timestamp.to_s, 10)
+        (now.to_i - seconds).abs <= tolerance
+      rescue ArgumentError, TypeError
+        # A missing or non-numeric timestamp can't be inside any window.
+        false
+      end
+
+      # Constant-time compare: a byte-by-byte early return leaks how much of the
+      # digest matched, which is enough to forge one byte at a time.
+      # OpenSSL.secure_compare needs equal lengths to be meaningful, and returns
+      # false rather than raising on a mismatch, so the length check is explicit.
+      def secure_equal?(given, expected)
+        return false unless given.bytesize == expected.bytesize
+
+        OpenSSL.secure_compare(given, expected)
+      end
+    end
+  end
+end

data/lib/rail0-sdk.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# The gem is "rail0-sdk"; its entry point is `rail0`.
+#
+# This file is not cosmetic. Bundler requires a gem by its OWN name by default, so
+# `gem "rail0-sdk"` in a Gemfile with Bundler.require raises LoadError without it. It also
+# gives anyone who reaches for the name they installed the file they expect.
+#
+# The canonical path stays `rail0`, unchanged: it is what every existing caller, example and
+# integration test requires, and what the Rail0 module is named after.
+require_relative "rail0"

data/lib/rail0.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Entry point. Everything below is loaded with require_relative on purpose: the
+# gem used to unshift lib/rail0 and lib/rail0/resources onto the GLOBAL $LOAD_PATH
+# so its files could require each other by bare name ("request", "query", …).
+# That put ~20 generic basenames at the FRONT of the search path for the whole
+# process, so any gem loaded afterwards doing a bare `require "request"` silently
+# got ours — order-dependent and effectively undiagnosable. require_relative needs
+# no path at all. (#5)
+
+require_relative "rail0/version"
+require_relative "rail0/error_hints"
+require_relative "rail0/api_error"
+require_relative "rail0/backoff"
+require_relative "rail0/default_logger"
+require_relative "rail0/request"
+require_relative "rail0/http_client"
+require_relative "rail0/client"
+require_relative "rail0/webhook_signature"
+require_relative "rail0/stablecoins"

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification
+name: rail0-sdk
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Commerce Layer
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+description: |
+  REST client for the RAIL0 stablecoin payment API. Wraps the authorize →
+  capture → refund lifecycle with full type documentation, retry support,
+  pluggable logging, and optional off-chain EIP-3009 signing.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/rail0-sdk.rb
+- lib/rail0.rb
+- lib/rail0/api_error.rb
+- lib/rail0/backoff.rb
+- lib/rail0/client.rb
+- lib/rail0/default_logger.rb
+- lib/rail0/error_hints.rb
+- lib/rail0/http_client.rb
+- lib/rail0/request.rb
+- lib/rail0/resources/accounts.rb
+- lib/rail0/resources/analytics.rb
+- lib/rail0/resources/auth.rb
+- lib/rail0/resources/chains.rb
+- lib/rail0/resources/disputes.rb
+- lib/rail0/resources/health.rb
+- lib/rail0/resources/payment_methods.rb
+- lib/rail0/resources/payments.rb
+- lib/rail0/resources/query.rb
+- lib/rail0/resources/tokens.rb
+- lib/rail0/resources/wallets.rb
+- lib/rail0/resources/webhooks.rb
+- lib/rail0/signing.rb
+- lib/rail0/stablecoins.rb
+- lib/rail0/types.rb
+- lib/rail0/version.rb
+- lib/rail0/webhook_signature.rb
+homepage: https://github.com/commercelayer/rail0-ruby
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/commercelayer/rail0-ruby
+  bug_tracker_uri: https://github.com/commercelayer/rail0-ruby/issues
+  changelog_uri: https://github.com/commercelayer/rail0-ruby/releases
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: Ruby SDK for the RAIL0 stablecoin payment protocol
+test_files: []