remitmd 0.1.5 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ed253579479f34977bda545675b25e12f9b73333b7cf36e640ae328c6b13073
-  data.tar.gz: f49f3163a37cb08a328e17de589fcc894ae168a3a486af06a419bd2edc1c79b9
+  metadata.gz: b29ac02ca95fe1053bed848cca89111698f1744bbeb145681a76a3f9ed2d8e66
+  data.tar.gz: d55c4f33eaaa686fa0036e3a0566ee6382a0a544c01093a3d9887e745b2eaa01
 SHA512:
-  metadata.gz: ebb1c4b3e6b91a29634e3ed89207d4d95e4de701595d33e654f41128ba9d6aba9a76344c6a6f9ad1991f87dcda32c60480cc2fb75d593ea894fd784e2aefbb27
-  data.tar.gz: ba0a10cb153c66c3ca62c919c33d19dff4d34b50c4c81f129455d1f5bc147778b985731c593bfb55525934b3baeafb2fafea3d09cddb1117d435cbc52a0944b2
+  metadata.gz: 9c00d48fc571e6975d9dfd32c679d5b9cf46205742a8a725022907eb997d42de7a61ae040c22dfafb7d5a994277d25f5dafd2e589611e849f94a70c692d71102
+  data.tar.gz: dff3c27cf317ce994999efd38d57f1173f0a1136da0bf4dbcdbf1ff5879a9f737bef96875802108ca130b4e46b3b94eec1cc0f52cace3152c89357018d9f9621

data/README.md

@@ -1,5 +1,7 @@
 # remit.md Ruby SDK
 
+> [Skill MD](https://remit.md) · [Docs](https://remit.md/docs) · [Agent Spec](https://remit.md/agent.md)
+
 Universal payment protocol for AI agents — Ruby client library.
 
 [![CI](https://github.com/remit-md/sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/remit-md/sdk/actions/workflows/ci.yml)
@@ -38,7 +40,7 @@ Or from environment variables:
 ```ruby
 wallet = Remitmd::RemitWallet.from_env
 # Requires: REMITMD_PRIVATE_KEY
-# Optional: REMITMD_CHAIN (default: "base"), REMITMD_API_URL, REMITMD_RPC_URL
+# Optional: REMITMD_CHAIN (default: "base"), REMITMD_API_URL
 ```
 
 Permits are auto-signed. Every payment method fetches the on-chain USDC nonce, signs an EIP-2612 permit, and includes it automatically.
@@ -267,19 +269,6 @@ permit = wallet.sign_usdc_permit(
 tx = wallet.pay("0xRecipient...", 5.00, permit: permit)
 ```
 
-### Custom RPC URL
-
-Override the JSON-RPC endpoint used for nonce fetching:
-
-```ruby
-wallet = Remitmd::RemitWallet.new(
-  private_key: key,
-  chain: "base_sepolia",
-  rpc_url: "https://your-rpc-provider.com/v1/base-sepolia"
-)
-# Or via environment: REMITMD_RPC_URL
-```
-
 ## License
 
 MIT — see [LICENSE](LICENSE)

data/lib/remitmd/a2a.rb

@@ -4,7 +4,7 @@ require "net/http"
 require "json"
 require "uri"
 
-module RemitMd
+module Remitmd
   # A2A capability extension declared in an agent card.
   AgentExtension = Data.define(:uri, :description, :required)
 
@@ -37,7 +37,7 @@ module RemitMd
 
     # Fetch and parse the A2A agent card from +base_url/.well-known/agent-card.json+.
     #
-    #   card = RemitMd::AgentCard.discover("https://remit.md")
+    #   card = Remitmd::AgentCard.discover("https://remit.md")
     #   puts card.name   # => "remit.md"
     #   puts card.url    # => "https://remit.md/a2a"
     #
@@ -55,4 +55,190 @@ module RemitMd
       new(JSON.parse(response.body))
     end
   end
+
+  # ─── A2A task types ──────────────────────────────────────────────────────────
+
+  # Status of an A2A task.
+  class A2ATaskStatus
+    attr_reader :state, :message
+
+    def initialize(data)
+      @state   = data["state"].to_s
+      @message = data["message"]
+    end
+  end
+
+  # An artifact part within an A2A artifact.
+  A2AArtifactPart = Data.define(:kind, :data)
+
+  # An artifact returned by an A2A task.
+  class A2AArtifact
+    attr_reader :name, :parts
+
+    def initialize(data)
+      @name  = data["name"]
+      @parts = (data["parts"] || []).map do |p|
+        A2AArtifactPart.new(kind: p["kind"].to_s, data: p["data"] || {})
+      end
+    end
+  end
+
+  # An A2A task returned by message/send, tasks/get, or tasks/cancel.
+  class A2ATask
+    attr_reader :id, :status, :artifacts
+
+    def initialize(data)
+      @id        = data["id"].to_s
+      @status    = A2ATaskStatus.new(data["status"] || {})
+      @artifacts = (data["artifacts"] || []).map { |a| A2AArtifact.new(a) }
+    end
+
+    # Extract txHash from task artifacts, if present.
+    # @return [String, nil]
+    def tx_hash
+      artifacts.each do |artifact|
+        artifact.parts.each do |part|
+          tx = part.data["txHash"] if part.data.is_a?(Hash)
+          return tx if tx.is_a?(String)
+        end
+      end
+      nil
+    end
+  end
+
+  # ─── IntentMandate ──────────────────────────────────────────────────────────
+
+  # A mandate authorizing a payment intent.
+  class IntentMandate
+    attr_reader :mandate_id, :expires_at, :issuer, :max_amount, :currency
+
+    def initialize(mandate_id:, expires_at:, issuer:, max_amount:, currency: "USDC")
+      @mandate_id = mandate_id
+      @expires_at = expires_at
+      @issuer     = issuer
+      @max_amount = max_amount
+      @currency   = currency
+    end
+
+    def to_h
+      {
+        mandateId: @mandate_id,
+        expiresAt: @expires_at,
+        issuer:    @issuer,
+        allowance: {
+          maxAmount: @max_amount,
+          currency:  @currency,
+        },
+      }
+    end
+  end
+
+  # ─── A2A JSON-RPC client ────────────────────────────────────────────────────
+
+  # A2A JSON-RPC client — send payments and manage tasks via the A2A protocol.
+  #
+  # @example
+  #   card   = Remitmd::AgentCard.discover("https://remit.md")
+  #   signer = Remitmd::PrivateKeySigner.new(ENV["REMITMD_KEY"])
+  #   client = Remitmd::A2AClient.from_card(card, signer)
+  #   task   = client.send(to: "0xRecipient...", amount: 10)
+  #   puts task.status.state
+  #
+  class A2AClient
+    CHAIN_IDS = {
+      "base"         => 8453,
+      "base-sepolia" => 84_532,
+    }.freeze
+
+    # @param endpoint [String] full A2A endpoint URL from the agent card
+    # @param signer [#sign, #address] a signer for EIP-712 authentication
+    # @param chain_id [Integer] chain ID
+    # @param verifying_contract [String] verifying contract address
+    def initialize(endpoint:, signer:, chain_id:, verifying_contract: "")
+      parsed    = URI(endpoint)
+      @base_url = "#{parsed.scheme}://#{parsed.host}#{parsed.port == parsed.default_port ? "" : ":#{parsed.port}"}"
+      @path     = parsed.path.empty? ? "/a2a" : parsed.path
+      @transport = HttpTransport.new(
+        base_url:       @base_url,
+        signer:         signer,
+        chain_id:       chain_id,
+        router_address: verifying_contract
+      )
+    end
+
+    # Convenience constructor from an AgentCard and a signer.
+    # @param card [AgentCard]
+    # @param signer [#sign, #address]
+    # @param chain [String] chain name (default: "base")
+    # @param verifying_contract [String]
+    # @return [A2AClient]
+    def self.from_card(card, signer, chain: "base", verifying_contract: "")
+      chain_id = CHAIN_IDS[chain] || CHAIN_IDS["base"]
+      new(
+        endpoint:            card.url,
+        signer:              signer,
+        chain_id:            chain_id,
+        verifying_contract:  verifying_contract
+      )
+    end
+
+    # Send a direct USDC payment via message/send.
+    # @param to [String] recipient 0x address
+    # @param amount [Numeric] amount in USDC
+    # @param memo [String] optional memo
+    # @param mandate [IntentMandate, nil] optional intent mandate
+    # @return [A2ATask]
+    def send(to:, amount:, memo: "", mandate: nil)
+      nonce      = SecureRandom.hex(16)
+      message_id = SecureRandom.hex(16)
+
+      message = {
+        messageId: message_id,
+        role:      "user",
+        parts: [
+          {
+            kind: "data",
+            data: {
+              model:  "direct",
+              to:     to,
+              amount: format("%.2f", amount),
+              memo:   memo,
+              nonce:  nonce,
+            },
+          },
+        ],
+      }
+
+      message[:metadata] = { mandate: mandate.to_h } if mandate
+
+      rpc("message/send", { message: message }, message_id)
+    end
+
+    # Fetch the current state of an A2A task by ID.
+    # @param task_id [String]
+    # @return [A2ATask]
+    def get_task(task_id)
+      rpc("tasks/get", { id: task_id }, task_id[0, 16])
+    end
+
+    # Cancel an in-progress A2A task.
+    # @param task_id [String]
+    # @return [A2ATask]
+    def cancel_task(task_id)
+      rpc("tasks/cancel", { id: task_id }, task_id[0, 16])
+    end
+
+    private
+
+    def rpc(method, params, call_id)
+      body = { jsonrpc: "2.0", id: call_id, method: method, params: params }
+      data = @transport.post(@path, body)
+      if data.is_a?(Hash) && data["error"]
+        err_msg = data["error"]["message"] || JSON.generate(data["error"])
+        raise RemitError.new("SERVER_ERROR", "A2A error: #{err_msg}")
+      end
+      result = data.is_a?(Hash) ? (data["result"] || data) : data
+      A2ATask.new(result)
+    end
+  end
 end

data/lib/remitmd/errors.rb

@@ -15,29 +15,64 @@ module Remitmd
   #     puts e.doc_url  # => "https://remit.md/docs/api-reference/error-codes#invalid_address"
   #   end
   class RemitError < StandardError
-    # Error code constants
-    INVALID_ADDRESS         = "INVALID_ADDRESS"
-    INVALID_AMOUNT          = "INVALID_AMOUNT"
-    INSUFFICIENT_FUNDS      = "INSUFFICIENT_FUNDS"
+    # Error code constants — matches TS SDK (28 codes)
+    # Auth errors
+    INVALID_SIGNATURE       = "INVALID_SIGNATURE"
+    NONCE_REUSED            = "NONCE_REUSED"
+    TIMESTAMP_EXPIRED       = "TIMESTAMP_EXPIRED"
+    UNAUTHORIZED            = "UNAUTHORIZED"
+
+    # Balance / funds
+    INSUFFICIENT_BALANCE    = "INSUFFICIENT_BALANCE"
+    BELOW_MINIMUM           = "BELOW_MINIMUM"
+
+    # Escrow errors
     ESCROW_NOT_FOUND        = "ESCROW_NOT_FOUND"
+    ESCROW_ALREADY_FUNDED   = "ESCROW_ALREADY_FUNDED"
+    ESCROW_EXPIRED          = "ESCROW_EXPIRED"
+
+    # Invoice errors
+    INVALID_INVOICE         = "INVALID_INVOICE"
+    DUPLICATE_INVOICE       = "DUPLICATE_INVOICE"
+    SELF_PAYMENT            = "SELF_PAYMENT"
+    INVALID_PAYMENT_TYPE    = "INVALID_PAYMENT_TYPE"
+
+    # Tab errors
+    TAB_DEPLETED            = "TAB_DEPLETED"
+    TAB_EXPIRED             = "TAB_EXPIRED"
     TAB_NOT_FOUND           = "TAB_NOT_FOUND"
+
+    # Stream errors
     STREAM_NOT_FOUND        = "STREAM_NOT_FOUND"
+    RATE_EXCEEDS_CAP        = "RATE_EXCEEDS_CAP"
+
+    # Bounty errors
+    BOUNTY_EXPIRED          = "BOUNTY_EXPIRED"
+    BOUNTY_CLAIMED          = "BOUNTY_CLAIMED"
+    BOUNTY_MAX_ATTEMPTS     = "BOUNTY_MAX_ATTEMPTS"
     BOUNTY_NOT_FOUND        = "BOUNTY_NOT_FOUND"
-    DEPOSIT_NOT_FOUND       = "DEPOSIT_NOT_FOUND"
-    UNAUTHORIZED            = "UNAUTHORIZED"
-    RATE_LIMITED            = "RATE_LIMITED"
+
+    # Chain errors
+    CHAIN_MISMATCH          = "CHAIN_MISMATCH"
+    CHAIN_UNSUPPORTED       = "CHAIN_UNSUPPORTED"
+
+    # Rate limiting
+    RATE_LIMITED             = "RATE_LIMITED"
+
+    # Cancellation errors
+    CANCEL_BLOCKED_CLAIM_START = "CANCEL_BLOCKED_CLAIM_START"
+    CANCEL_BLOCKED_EVIDENCE    = "CANCEL_BLOCKED_EVIDENCE"
+
+    # Protocol errors
+    VERSION_MISMATCH        = "VERSION_MISMATCH"
     NETWORK_ERROR           = "NETWORK_ERROR"
+
+    # Legacy aliases (kept for backward compat within the SDK)
+    INVALID_ADDRESS         = "INVALID_ADDRESS"
+    INVALID_AMOUNT          = "INVALID_AMOUNT"
+    INSUFFICIENT_FUNDS      = INSUFFICIENT_BALANCE
     SERVER_ERROR            = "SERVER_ERROR"
-    NONCE_REUSED            = "NONCE_REUSED"
-    SIGNATURE_INVALID       = "SIGNATURE_INVALID"
-    ESCROW_ALREADY_RELEASED = "ESCROW_ALREADY_RELEASED"
-    ESCROW_EXPIRED          = "ESCROW_EXPIRED"
-    TAB_LIMIT_EXCEEDED      = "TAB_LIMIT_EXCEEDED"
-    BOUNTY_ALREADY_AWARDED  = "BOUNTY_ALREADY_AWARDED"
-    STREAM_NOT_ACTIVE       = "STREAM_NOT_ACTIVE"
-    DEPOSIT_ALREADY_SETTLED = "DEPOSIT_ALREADY_SETTLED"
-    USDC_TRANSFER_FAILED    = "USDC_TRANSFER_FAILED"
-    CHAIN_UNAVAILABLE       = "CHAIN_UNAVAILABLE"
+    DEPOSIT_NOT_FOUND       = "DEPOSIT_NOT_FOUND"
 
     attr_reader :code, :doc_url, :context
 

data/lib/remitmd/http.rb

@@ -8,9 +8,11 @@ require "openssl"
 
 module Remitmd
   # Chain configuration: maps chain names to (api_url, chain_id) pairs.
+  # Canonical keys use hyphens; underscored variants are accepted as aliases.
   CHAIN_CONFIG = {
-    "base"          => { url: "https://remit.md/api/v1",          chain_id: 8453 },
-    "base_sepolia"  => { url: "https://testnet.remit.md/api/v1",      chain_id: 84532 },
+    "base"          => { url: "https://remit.md/api/v1",             chain_id: 8453 },
+    "base-sepolia"  => { url: "https://testnet.remit.md/api/v1",    chain_id: 84532 },
+    "base_sepolia"  => { url: "https://testnet.remit.md/api/v1",    chain_id: 84532 },
   }.freeze
 
   # HTTP transport layer. Signs each request with EIP-712 auth headers and
@@ -40,9 +42,11 @@ module Remitmd
 
     def request(method, path, body)
       attempt = 0
+      # Generate idempotency key once per request (stable across retries).
+      idempotency_key = %i[post put patch].include?(method) ? SecureRandom.uuid : nil
       begin
         attempt += 1
-        req  = build_request(method, path, body)
+        req  = build_request(method, path, body, idempotency_key)
         resp = @http.request(req)
         handle_response(resp, path)
       rescue RemitError => e
@@ -58,7 +62,7 @@ module Remitmd
       end
     end
 
-    def build_request(method, path, body)
+    def build_request(method, path, body, idempotency_key = nil)
       full_path = "#{@uri.path}#{path}"
       req = case method
             when :get  then Net::HTTP::Get.new(full_path)
@@ -70,9 +74,10 @@ module Remitmd
       nonce_hex   = "0x#{nonce_bytes.unpack1("H*")}"
       timestamp   = Time.now.to_i
 
-      # Compute EIP-712 hash and sign it.
+      # Strip query string before signing — only the path is included in EIP-712.
+      sign_path   = full_path.split("?").first
       http_method = method.to_s.upcase
-      digest      = eip712_hash(http_method, full_path, timestamp, nonce_bytes)
+      digest      = eip712_hash(http_method, sign_path, timestamp, nonce_bytes)
       signature   = @signer.sign(digest)
 
       req["Content-Type"]      = "application/json"
@@ -81,6 +86,7 @@ module Remitmd
       req["X-Remit-Nonce"]     = nonce_hex
       req["X-Remit-Timestamp"] = timestamp.to_s
       req["X-Remit-Signature"] = signature
+      req["X-Idempotency-Key"] = idempotency_key if idempotency_key
 
       if body
         req.body = body.to_json
@@ -150,8 +156,10 @@ module Remitmd
       when 200..299
         parsed
       when 400
-        code = parsed["code"] || RemitError::SERVER_ERROR
-        raise RemitError.new(code, parsed["message"] || "Bad request", context: parsed)
+        # Support nested error format: { "error": { "code": "...", "message": "..." } }
+        err = parsed.is_a?(Hash) && parsed["error"].is_a?(Hash) ? parsed["error"] : parsed
+        code = err["code"] || RemitError::SERVER_ERROR
+        raise RemitError.new(code, err["message"] || "Bad request", context: parsed)
       when 401
         raise RemitError.new(RemitError::UNAUTHORIZED,
                              "Authentication failed — check your private key and chain ID")

data/lib/remitmd/keccak.rb

@@ -77,7 +77,7 @@ module Remitmd
         RC.each { |rc| keccak_round!(state, rc) }
       end
 
-      def keccak_round!(state, rc) # rubocop:disable Metrics/MethodLength
+      def keccak_round!(state, rc)
         # Theta
         c = Array.new(5) do |x|
           state[x] ^ state[x + 5] ^ state[x + 10] ^ state[x + 15] ^ state[x + 20]

data/lib/remitmd/mock.rb

@@ -148,7 +148,6 @@ module Remitmd
           "deposit"        => "0xMockDeposit00000000000000000000000001",
           "fee_calculator" => "0xMockFeeCalc0000000000000000000000001",
           "key_registry"   => "0xMockKeyReg000000000000000000000000001",
-          "arbitration"    => "0xMockArbitr000000000000000000000000001",
         }
 
       # Balance
@@ -181,6 +180,7 @@ module Remitmd
         invoice_id = fetch!(b, :invoice_id)
         inv = @state[:pending_invoices].delete(invoice_id)
         raise not_found(RemitError::ESCROW_NOT_FOUND, invoice_id) unless inv
+
         payee  = (inv[:to_agent] || inv["to_agent"]).to_s
         amount = decimal!(inv, :amount)
         memo   = (inv[:task] || inv["task"]).to_s
@@ -200,7 +200,7 @@ module Remitmd
       in ["POST", path] if path.end_with?("/release") && path.include?("/escrows/")
         id  = extract_id(path, "/escrows/", "/release")
         esc = @state[:escrows].fetch(id) { raise not_found(RemitError::ESCROW_NOT_FOUND, id) }
-        new_esc = update_escrow(esc, status: EscrowStatus::RELEASED)
+        new_esc = update_escrow(esc, status: EscrowStatus::COMPLETED)
         @state[:escrows][id] = new_esc
         tx = make_tx(from: esc.payer, to: esc.payee, amount: esc.amount)
         @state[:transactions] << tx
@@ -269,7 +269,7 @@ module Remitmd
       in ["POST", path] if path.end_with?("/close") && path.include?("/tabs/")
         id  = extract_id(path, "/tabs/", "/close")
         tab = @state[:tabs].fetch(id) { raise not_found(RemitError::TAB_NOT_FOUND, id) }
-        new_tab = update_tab(tab, status: TabStatus::SETTLED)
+        new_tab = update_tab(tab, status: TabStatus::CLOSED)
         @state[:tabs][id] = new_tab
         tab_hash(new_tab)
 
@@ -311,7 +311,7 @@ module Remitmd
       # Bounty submit
       in ["POST", path] if path.end_with?("/submit") && path.include?("/bounties/")
         id = extract_id(path, "/bounties/", "/submit")
-        bnt = @state[:bounties].fetch(id) { raise not_found(RemitError::BOUNTY_NOT_FOUND, id) }
+        @state[:bounties].fetch(id) { raise not_found(RemitError::BOUNTY_NOT_FOUND, id) }
         {
           "id"            => 1,
           "bounty_id"     => id,
@@ -323,9 +323,9 @@ module Remitmd
 
       # Bounty award
       in ["POST", path] if path.end_with?("/award") && path.include?("/bounties/")
-        id            = extract_id(path, "/bounties/", "/award")
-        submission_id = (b[:submission_id] || b["submission_id"]).to_i
-        bnt           = @state[:bounties].fetch(id) { raise not_found(RemitError::BOUNTY_NOT_FOUND, id) }
+        id  = extract_id(path, "/bounties/", "/award")
+        _submission_id = (b[:submission_id] || b["submission_id"]).to_i
+        bnt = @state[:bounties].fetch(id) { raise not_found(RemitError::BOUNTY_NOT_FOUND, id) }
         new_bnt = update_bounty(bnt, status: BountyStatus::AWARDED)
         @state[:bounties][id] = new_bnt
         bounty_hash(new_bnt)
@@ -621,6 +621,7 @@ module Remitmd
     def check_balance!(amount)
       bal = @state[:balance]
       return if bal >= amount
+
       raise RemitError.new(
         RemitError::INSUFFICIENT_FUNDS,
         "Insufficient balance: have #{bal.to_s("F")} USDC, need #{amount.to_s("F")} USDC",