rail0-sdk 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1304e38f4530a6bfdbfe8f3196ed562b4869b9e6ab7d455cae744afb21ad21ed
-  data.tar.gz: 87090219ed6aef2133815ca4a704a5c7a8e926cead00e59688a42aac25f29297
+  metadata.gz: 5432df0776e08a77c56678e4e977d87c81ddf2be6176fef59a95051e287a6ce9
+  data.tar.gz: 7747a265cc8d84f243a09a8b1ab66e3cba545a3817554bc321dc5aa9eaed34be
 SHA512:
-  metadata.gz: 77f22e52615cd7cac1b1535084a388111e20850e01a89a39628322bf825f8ea023c1db7e9d185bbb9c0616fa1827add2ebbdb2d8749cbf60fbfe099f6f0719f8
-  data.tar.gz: ae3d34f5cceffb1ea59f33114b53c5308eb115b929bfa581717e7e3357fedbb38a527ef0a35136943eadbc4fa0e93a589ebbacff4f13c880f885c95869644a4a
+  metadata.gz: 440edc898e25a83ad3c76615777b4074f7daf003904db75129df01c4fcb223aebad7e5a1e425212207842aa334cdab1bccfe79a0023fcf08578d5bc09da8462a
+  data.tar.gz: 7482c21a09309b6dabe1f26c4b19b29890d8b8dfc679d4fc1b15d8b1de76a39b2f5998414e2e28ab3ee840edc2e31e7531ebe3b215c0a308f92068d0754ac46a

data/README.md

@@ -378,6 +378,10 @@ client.payments.create(params, idempotency_key: nil)  # or keyword fields
 # Reusing a key for DIFFERENT terms raises Rail0::ApiError with code
 # "idempotency_key_reused" (422) instead of returning the first payment.
 client.payments.get(id)
+client.payments.update(id, description: "Order #42")  # → the payment, same shape as get
+client.payments.update(id, description: nil)          # nil (or "") clears it
+# The description is the only editable field: off-chain, so any status, settled included.
+# Payer or payee only (a non-participant gets 404); over 255 characters is a 422.
 client.payments.list(status: "authorized", disputed: false, chain_id: 84532, sort: "-created_at")
 client.payments.list(status: %w[authorized expired])  # any of several states → ?status=authorized,expired
 client.payments.list(operation: "refund")            # payments with at least one refund transaction
@@ -770,6 +774,17 @@ RAIL0 itself:
 A failed transaction carries the same triple as `error_code`, `error_title` and
 `error_detail`, whether it reverted on-chain or was refused before broadcast.
 
+### Ids in request paths
+
+Every id (and operation name) a method interpolates into a request path is
+percent-encoded as ONE path segment, so a value carrying `/`, `?`, `#`, a space or
+non-ASCII characters can never address a different route than the method names
+(`payments.get("../webhooks/x")` requests `/payments/..%2Fwebhooks%2Fx`, not
+`/webhooks/x`). The ids the gateway hands out — UUIDs, `0x` hex — are unchanged by it.
+A value that is `nil`, empty, `"."` or `".."` is never a valid id, and would still
+re-target the request once encoded, so the method raises `ArgumentError` before
+sending anything.
+
 ## Configuration
 
 ```ruby
@@ -854,7 +869,7 @@ lib/rail0/
     accounts.rb        the caller's own account profile, read and update (JWT)
     webhooks.rb        webhook subscription management (JWT)
     analytics.rb       account-scoped payment analytics (JWT)
-    query.rb           shared query-string helper
+    query.rb           shared query-string and path-segment helpers
 ```
 
 ## Development

data/lib/rail0/resources/accounts.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "query"
+
 module Rail0
   module Resources
     # The merchant account itself (requires JWT).
@@ -17,6 +19,8 @@ module Rail0
     # {Resources::Wallets}; buyer-facing discovery of what a merchant accepts lives on
     # {Resources::PaymentMethods}.
     class Accounts
+      include Query
+
       attr_reader :http
 
       def initialize(http)
@@ -29,7 +33,7 @@ module Rail0
       # @return [Hash] `id`, `name`, `email`, `created_at`, `updated_at`. `email` is part of
       #   the response because only the account's owner, or an operator, can read it.
       def get(account_id)
-        http.get("/accounts/#{account_id}")
+        http.get("/accounts/#{segment(account_id)}")
       end
 
       # Update the account's own profile (PATCH /accounts/:account_id).
@@ -55,7 +59,7 @@ module Rail0
         body[:email] = email unless email.nil?
         raise ArgumentError, "at least one of name or email is required" if body.empty?
 
-        http.patch("/accounts/#{account_id}", body)
+        http.patch("/accounts/#{segment(account_id)}", body)
       end
     end
   end

data/lib/rail0/resources/payments.rb

@@ -99,7 +99,25 @@ module Rail0
       #   (Integer or nil — divide `amount`, `capturable_amount` and `refundable_amount` by
       #   10**decimals to render them) and `in_flight` (Boolean — see {list}).
       def get(id)
-        http.get("/payments/#{id}")
+        http.get("/payments/#{segment(id)}")
+      end
+
+      # Set or clear a payment's description (PATCH /payments/{id}).
+      #
+      # The description is the only field this route edits: it is off-chain metadata, so
+      # it can change at any status, settled payments included. Only a participant (the
+      # payer or the payee) may edit it — a non-participant gets the same 404 as an unknown
+      # id, and a deactivated caller wallet a 403 `wallet_deactivated`.
+      #
+      # +description:+ is required, and is always sent: passing +nil+ sends JSON +null+,
+      # which clears it (as does +""+). Over 255 characters is a 422.
+      # (rail0-gateway#373)
+      #
+      # @param id [String] Payment UUID or rail0_id.
+      # @param description [String, nil] The new description; +nil+ or +""+ clears it.
+      # @return [Hash] The updated payment, the same shape {get} returns.
+      def update(id, description:)
+        http.patch("/payments/#{segment(id)}", { description: description })
       end
 
       # List on-chain transactions for a payment.
@@ -114,7 +132,7 @@ module Rail0
       # @return [Hash] { data: Array<Hash>, meta: { page:, per_page:, total: } }
       def transactions(id, operation: nil, status: nil, sort: nil, page: nil, per_page: nil)
         query = build_query(operation: operation, status: status, sort: sort, page: page, per_page: per_page)
-        http.get_list("/payments/#{id}/transactions#{query}")
+        http.get_list("/payments/#{segment(id)}/transactions#{query}")
       end
 
       # Fetch ONE of a payment's transactions
@@ -130,7 +148,7 @@ module Rail0
       # @param transaction_id [String] Transaction UUID.
       # @return [Hash]
       def get_transaction(id, transaction_id)
-        http.get("/payments/#{id}/transactions/#{transaction_id}")
+        http.get("/payments/#{segment(id)}/transactions/#{segment(transaction_id)}")
       end
 
       # Re-enqueue a stuck broadcast
@@ -153,7 +171,7 @@ module Rail0
       # @param transaction_id [String] The transaction row to redrive.
       # @return [Hash] The transaction, re-enqueued.
       def redrive(id, transaction_id)
-        http.post("/payments/#{id}/transactions/#{transaction_id}/redrive", {})
+        http.post("/payments/#{segment(id)}/transactions/#{segment(transaction_id)}/redrive", {})
       end
 
       # Submit the payer's EIP-712 signature (PUT /payments/{id}/sign).
@@ -161,7 +179,7 @@ module Rail0
       # @param params [Hash] { signature: "0x…" } (65-byte 0x-prefixed hex).
       # @return [Hash]
       def sign(id, params)
-        http.put("/payments/#{id}/sign", params)
+        http.put("/payments/#{segment(id)}/sign", params)
       end
 
       # List a payment's dispute open/close history.
@@ -173,7 +191,7 @@ module Rail0
       # @return [Hash] { data: Array<Hash>, meta: { page:, per_page:, total: } }
       def disputes(id, status: nil, sort: nil, page: nil, per_page: nil)
         query = build_query(status: status, sort: sort, page: page, per_page: per_page)
-        http.get_list("/payments/#{id}/disputes#{query}")
+        http.get_list("/payments/#{segment(id)}/disputes#{query}")
       end
 
       # Build the unsigned transaction for an operation
@@ -193,7 +211,7 @@ module Rail0
       # with different terms is refused 422 +idempotency_key_reused+. Scoped to this
       # payment. (rail0-gateway#331)
       def prepare(id, operation, body = nil, idempotency_key: nil)
-        http.post("/payments/#{id}/#{operation}/prepare", body,
+        http.post("/payments/#{segment(id)}/#{segment(operation)}/prepare", body,
                   headers: idempotency_headers(idempotency_key))
       end
 
@@ -203,7 +221,7 @@ module Rail0
       # @param params [Hash] { signed_transaction: "0x…" }.
       # @return [Hash]
       def submit(id, operation, params)
-        http.post("/payments/#{id}/#{operation}", params)
+        http.post("/payments/#{segment(id)}/#{segment(operation)}", params)
       end
 
       # Record a transaction the caller broadcast themselves (MetaMask/wallet flow)
@@ -213,7 +231,7 @@ module Rail0
       # @param params [Hash] { transaction_hash: "0x…" }.
       # @return [Hash]
       def submit_by_hash(id, operation, params)
-        http.post("/payments/#{id}/#{operation}/submitted", params)
+        http.post("/payments/#{segment(id)}/#{segment(operation)}/submitted", params)
       end
 
       # Phase 1 — build the unsigned authorize() transaction (escrow hold).
@@ -302,7 +320,7 @@ module Rail0
       # @param params [Hash] { signed_transaction: "0x…" }.
       # @return [Hash]
       def dispute(id, params)
-        http.post("/payments/#{id}/dispute", params)
+        http.post("/payments/#{segment(id)}/dispute", params)
       end
 
       # Phase 1 — build the unsigned closeDispute() transaction (payer only).
@@ -318,7 +336,7 @@ module Rail0
       # @param params [Hash] { signed_transaction: "0x…" }.
       # @return [Hash]
       def close_dispute(id, params)
-        http.post("/payments/#{id}/dispute/close", params)
+        http.post("/payments/#{segment(id)}/dispute/close", params)
       end
 
       # The payer's counterpart to {#submit_by_hash}, which covers only the operations
@@ -336,7 +354,7 @@ module Rail0
       # @param params [Hash] { transaction_hash: "0x…" }.
       # @return [Hash]
       def dispute_submit_by_hash(id, params)
-        http.post("/payments/#{id}/dispute/submitted", params)
+        http.post("/payments/#{segment(id)}/dispute/submitted", params)
       end
 
       # Report an already-broadcast close-dispute transaction by hash (payer only); HTTP 202.
@@ -344,14 +362,17 @@ module Rail0
       # @param params [Hash] { transaction_hash: "0x…" }.
       # @return [Hash]
       def close_dispute_submit_by_hash(id, params)
-        http.post("/payments/#{id}/dispute/close/submitted", params)
+        http.post("/payments/#{segment(id)}/dispute/close/submitted", params)
       end
 
       private
 
+      # +path+ is one of this class's own literals ("dispute/prepare",
+      # "dispute/close/prepare"), never caller input, so it is interpolated as-is:
+      # its `/` is meant to separate segments. Only +id+ goes through {#segment}.
       def prepare_dispute(path, id, reason, idempotency_key: nil)
         body = reason ? { reason: reason } : {}
-        http.post("/payments/#{id}/#{path}", body,
+        http.post("/payments/#{segment(id)}/#{path}", body,
                   headers: idempotency_headers(idempotency_key))
       end
 

data/lib/rail0/resources/query.rb

@@ -1,15 +1,59 @@
 # frozen_string_literal: true
 
 require "cgi"
+require "erb"
 
 module Rail0
   module Resources
-    # Shared query-string builder for resource classes. Included so every
-    # resource turns keyword filters into a URL query the same way: nil values
-    # are dropped, and booleans/integers are stringified.
+    # Shared URL builders for resource classes. Included so every resource turns
+    # keyword filters into a URL query the same way (nil values are dropped,
+    # booleans/integers are stringified) and escapes every caller-supplied path
+    # segment the same way ({#segment}).
     module Query
+      # Segments that would not stay put once interpolated: "." and ".." are dot
+      # segments that a URL normaliser (a proxy, a CDN, the server's router) may
+      # resolve away, and an empty one collapses the path onto its parent.
+      UNSAFE_SEGMENTS = ["", ".", ".."].freeze
+      private_constant :UNSAFE_SEGMENTS
+
       private
 
+      # Escapes ONE caller-supplied value for interpolation into a request path:
+      #
+      #   http.get("/payments/#{segment(id)}/transactions/#{segment(transaction_id)}")
+      #
+      # Paths used to be plain interpolation, so an id was pasted in raw: one
+      # containing `/`, `?`, `#` or `..` addressed a different route than the method
+      # named — `payments.get("../webhooks/x")` was a GET on /webhooks/x with the
+      # caller's token. The ids this SDK is handed normally come from the gateway, but
+      # a caller that forwards one from a URL (a proxy route, a CLI argument) passes
+      # along whatever it was given.
+      #
+      # ERB::Util.url_encode percent-encodes everything outside the RFC 3986
+      # unreserved set (A-Z a-z 0-9 - . _ ~), UTF-8 byte by byte, with a space as
+      # %20 — the path-correct form (CGI.escape, used for queries, would turn a
+      # space into `+`, which in a path is a literal plus). For the values legitimately
+      # passed (UUIDs, 0x hex, operation names, integer ids) it changes nothing. This
+      # matches rail0-ts's `path` tag, which uses encodeURIComponent.
+      #
+      # A value that is exactly "", "." or ".." raises ArgumentError instead: encoding
+      # leaves the dots as they are (they are unreserved), so the segment would still
+      # be a dot segment, and an empty one silently re-targets the parent route
+      # (`payments.get("")` would list payments). None of them is a valid id, so
+      # failing before the request is the only honest answer.
+      #
+      # @param value [#to_s] The id (or other caller-supplied value) to interpolate.
+      # @return [String] The percent-encoded segment.
+      # @raise [ArgumentError] If the value is nil, empty, "." or "..".
+      def segment(value)
+        str = value.to_s
+        if value.nil? || UNSAFE_SEGMENTS.include?(str)
+          raise ArgumentError, "invalid path segment #{value.inspect}: an id must not be nil, empty, \".\" or \"..\""
+        end
+
+        ERB::Util.url_encode(str)
+      end
+
       # Builds "?k=v&…" from keyword filters, or "" when every value is nil.
       #
       # An Array value becomes ONE comma-separated pair (`status: %w[a b]` →

data/lib/rail0/resources/wallets.rb

@@ -38,7 +38,7 @@ module Rail0
         query = build_query(chain_id: chain_id, token_symbol: token_symbol, active: active,
                             default: default, token_active: token_active,
                             sort: sort, page: page, per_page: per_page)
-        http.get_list("/accounts/#{account_id}/wallets#{query}")
+        http.get_list("/accounts/#{segment(account_id)}/wallets#{query}")
       end
 
       # Fetch a single wallet by its id or 0x address.
@@ -46,7 +46,7 @@ module Rail0
       # @param id_or_address [String] Wallet UUID or 0x address.
       # @return [Hash] id, address, label, active
       def get(account_id, id_or_address)
-        http.get("/accounts/#{account_id}/wallets/#{id_or_address}")
+        http.get(wallet_path(account_id, id_or_address))
       end
 
       # Add a wallet to the account.
@@ -74,7 +74,7 @@ module Rail0
       def create(account_id, address:, message:, signature:, label: nil)
         body = { address: address, message: message, signature: signature }
         body[:label] = label unless label.nil?
-        http.post("/accounts/#{account_id}/wallets", body)
+        http.post("/accounts/#{segment(account_id)}/wallets", body)
       end
 
       # Update a wallet's label and/or active status.
@@ -87,7 +87,7 @@ module Rail0
         body = {}
         body[:label]  = label  unless label.nil?
         body[:active] = active unless active.nil?
-        http.patch("/accounts/#{account_id}/wallets/#{id_or_address}", body)
+        http.patch(wallet_path(account_id, id_or_address), body)
       end
 
       # Soft-delete (deactivate) a wallet. Returns HTTP 204.
@@ -95,7 +95,7 @@ module Rail0
       # @param id_or_address [String] Wallet UUID or 0x address.
       # @return [nil]
       def delete(account_id, id_or_address)
-        http.delete("/accounts/#{account_id}/wallets/#{id_or_address}")
+        http.delete(wallet_path(account_id, id_or_address))
       end
 
       # Read a wallet's live on-chain balances across the configured chains. Each
@@ -109,7 +109,7 @@ module Rail0
       # @return [Hash] wallet_id, address, balances
       def balances(account_id, id_or_address, chain_id: nil, token_symbol: nil)
         query = build_query(chain_id: chain_id, token_symbol: token_symbol)
-        http.get("/accounts/#{account_id}/wallets/#{id_or_address}/balances#{query}")
+        http.get("#{wallet_path(account_id, id_or_address)}/balances#{query}")
       end
 
       # ── Token holdings ────────────────────────────────────────────────────────
@@ -133,7 +133,7 @@ module Rail0
       def add_token(account_id, id_or_address, chain_id:, token:, default: nil)
         body = { chain_id: chain_id, token: token }
         body[:default] = default unless default.nil?
-        http.post("/accounts/#{account_id}/wallets/#{id_or_address}/tokens", body)
+        http.post("#{wallet_path(account_id, id_or_address)}/tokens", body)
       end
 
       # Stop accepting a token on this wallet (soft delete). Returns HTTP 204.
@@ -150,13 +150,13 @@ module Rail0
       #
       # @return [nil]
       def remove_token(account_id, id_or_address, token_id)
-        http.delete("/accounts/#{account_id}/wallets/#{id_or_address}/tokens/#{token_id}")
+        http.delete("#{wallet_path(account_id, id_or_address)}/tokens/#{segment(token_id)}")
       end
 
       # Re-enable an existing token holding.
       # @return [Hash] the token holding
       def enable_token(account_id, id_or_address, token_id)
-        http.patch("/accounts/#{account_id}/wallets/#{id_or_address}/tokens/#{token_id}/enable")
+        http.patch("#{wallet_path(account_id, id_or_address)}/tokens/#{segment(token_id)}/enable")
       end
 
       # Disable an existing token holding without forgetting it — the holding (and
@@ -166,7 +166,15 @@ module Rail0
       # active default holding — promote another token to default first.
       # @return [Hash] the token holding
       def disable_token(account_id, id_or_address, token_id)
-        http.patch("/accounts/#{account_id}/wallets/#{id_or_address}/tokens/#{token_id}/disable")
+        http.patch("#{wallet_path(account_id, id_or_address)}/tokens/#{segment(token_id)}/disable")
+      end
+
+      private
+
+      # "/accounts/{account_id}/wallets/{id_or_address}" with both ids escaped by
+      # {Query#segment} — the prefix every single-wallet route shares.
+      def wallet_path(account_id, id_or_address)
+        "/accounts/#{segment(account_id)}/wallets/#{segment(id_or_address)}"
       end
     end
   end

data/lib/rail0/resources/webhooks.rb

@@ -71,7 +71,7 @@ module Rail0
       # @param id [String] Webhook UUID.
       # @return [Hash]
       def get(id)
-        http.get("/webhooks/#{id}")
+        http.get("/webhooks/#{segment(id)}")
       end
 
       # Update a webhook's name, callback_url, and/or topics.
@@ -87,35 +87,35 @@ module Rail0
         body[:name]         = name          unless name.nil?
         body[:callback_url] = callback_url  unless callback_url.nil?
         body[:topics]       = Array(topics) unless topics.nil?
-        http.patch("/webhooks/#{id}", body)
+        http.patch("/webhooks/#{segment(id)}", body)
       end
 
       # Re-enable a disabled webhook.
       # @param id [String] Webhook UUID.
       # @return [Hash]
       def enable(id)
-        http.put("/webhooks/#{id}/enable")
+        http.put("/webhooks/#{segment(id)}/enable")
       end
 
       # Disable a webhook (stops deliveries without deleting it).
       # @param id [String] Webhook UUID.
       # @return [Hash]
       def disable(id)
-        http.put("/webhooks/#{id}/disable")
+        http.put("/webhooks/#{segment(id)}/disable")
       end
 
       # Generate a new shared secret, returned once on the response.
       # @param id [String] Webhook UUID.
       # @return [Hash] webhook record including the new shared_secret
       def rotate_secret(id)
-        http.put("/webhooks/#{id}/rotate_secret")
+        http.put("/webhooks/#{segment(id)}/rotate_secret")
       end
 
       # Reset the delivery circuit breaker and re-enable the webhook.
       # @param id [String] Webhook UUID.
       # @return [Hash]
       def reset_circuit(id)
-        http.put("/webhooks/#{id}/reset_circuit")
+        http.put("/webhooks/#{segment(id)}/reset_circuit")
       end
 
       # List delivery attempts for a webhook.
@@ -138,7 +138,7 @@ module Rail0
         query = build_query(status: status, topic: topic, payment_id: payment_id,
                             response_code: response_code, since: since, until: until_time,
                             sort: sort, page: page, per_page: per_page)
-        http.get_list("/webhooks/#{id}/event_callbacks#{query}")
+        http.get_list("/webhooks/#{segment(id)}/event_callbacks#{query}")
       end
 
       # Re-deliver one recorded delivery's exact payload
@@ -161,14 +161,14 @@ module Rail0
       # @param callback_id [String] The event callback's UUID (from {event_callbacks}).
       # @return [Hash] `{ status: "queued" }` (HTTP 202).
       def redeliver(id, callback_id)
-        http.post("/webhooks/#{id}/event_callbacks/#{callback_id}/redeliver", {})
+        http.post("/webhooks/#{segment(id)}/event_callbacks/#{segment(callback_id)}/redeliver", {})
       end
 
       # Delete a webhook. Returns HTTP 204.
       # @param id [String] Webhook UUID.
       # @return [nil]
       def delete(id)
-        http.delete("/webhooks/#{id}")
+        http.delete("/webhooks/#{segment(id)}")
       end
     end
   end

data/lib/rail0/types.rb

@@ -173,16 +173,6 @@ module Rail0
       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(

data/lib/rail0/version.rb

@@ -5,5 +5,5 @@ module Rail0
   # 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.3.0"
+  VERSION = "1.4.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rail0-sdk
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Commerce Layer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-29 00:00:00.000000000 Z
+date: 2026-10-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: logger